[ { "path": ".fossil-settings/binary-glob", "content": "*.bmp\n*.gif\n*.png\n" }, { "path": ".fossil-settings/crlf-glob", "content": "win/*.bat\nwin/*.vc\nwin/rc/*.rc\n" }, { "path": ".fossil-settings/encoding-glob", "content": "win/buildall.vc.bat\nwin/makefile.vc\nwin/rules-ext.vc\nwin/rules.vc\nwin/targets.vc\nwin/rc/*.bmp\nwin/rc/*.cur\nwin/rc/*.ico\nwin/rc/*.rc\n" }, { "path": ".fossil-settings/ignore-glob", "content": "*.a\n*.dll\n*.dylib\n*.dylib.E\n*.exe\n*.exp\n*.la\n*.lib\n*.lo\n*.o\n*.obj\n*.pdb\n*.res\n*.sl\n*.so\n*/Makefile\n*/autom4te.cache\n*/config.cache\n*/config.log\n*/config.status\n*/tkConfig.sh\n*/wish*\n*/tktest\n*/versions.vc\n*/version.vc\n*/libtk.vfs\n*/libtk*.zip\n*/tkUuid.h\n.git\nhtml\nmacosx/configure\nwin/Debug*\nwin/Release*\nwin/*.manifest\nwin/nmhlp-out.txt\nwin/nmakehlp.out\nunix/tk.pc\nunix/Tk-Info.plist\nunix/Wish-Info.plist\nunix/Credits.html\n" }, { "path": ".fossil-settings/manifest", "content": "u\n" }, { "path": ".gitattributes", "content": "# Set the default behavior, in case people don't have core.autocrlf set.\n* eol=lf\n* text=auto\n\n# Explicitly declare text files you want to always be normalized and converted\n# to native line endings on checkout.\n*.3 text\n*.c text\n*.css text\n*.enc text\n*.h text\n*.htm text\n*.html text\n*.java text\n*.js text\n*.json text\n*.n text\n*.svg text\n*.ts text\n*.tcl text\n*.test text\n\n# Declare files that will always have CRLF line endings on checkout.\n*.bat eol=crlf\n*.rc eol=crlf\n*.sln eol=crlf\n*.vc eol=crlf\n\n# Denote all files that are truly binary and should not be modified.\n*.a binary\n*.bmp binary\n*.cur binary\n*.dll binary\n*.exe binary\n*.gif binary\n*.gz binary\n*.ico binary\n*.jpg binary\n*.lib binary\n*.pdf binary\n*.png binary\n*.xlsx binary\n*.zip binary\n" }, { "path": ".github/ISSUE_TEMPLATE.md", "content": "Important Note\n==========\nPlease do not file issues with Tk on Github. They are unlikely to be noticed in a timely fashion. Tk issues are hosted in the [tk fossil repository on core.tcl-lang.org](https://core.tcl-lang.org/tk/tktnew); please post them there.\n" }, { "path": ".github/PULL_REQUEST_TEMPLATE.md", "content": "Important Note\n==========\nPlease do not file pull requests with Tk on Github. They are unlikely to be noticed in a timely fashion. Tk issues (including patches) are hosted in the [tk fossil repository on core.tcl-lang.org](https://core.tcl-lang.org/tk/tktnew); please post them there.\n" }, { "path": ".github/workflows/linux-build.yml", "content": "name: Linux\non:\n push:\n branches:\n - \"main\"\n - \"core-9-0-branch\"\n tags:\n - \"core-**\"\npermissions:\n contents: read\ndefaults:\n run:\n shell: bash\n working-directory: tk/unix\nenv:\n ERROR_ON_FAILURES: 1\njobs:\n build:\n runs-on: ubuntu-24.04\n strategy:\n matrix:\n compiler:\n - \"gcc\"\n - \"clang\"\n config:\n - \"\"\n - \"CFLAGS=-DTK_NO_DEPRECATED=1\"\n - \"--disable-shared\"\n - \"--enable-symbols\"\n steps:\n - name: Checkout Tk\n uses: actions/checkout@v6\n with:\n path: tk\n - name: Checkout Tcl 9.1\n uses: actions/checkout@v6\n with:\n repository: tcltk/tcl\n ref: main\n path: tcl\n - name: Setup Environment (compiler=${{ matrix.compiler }})\n run: |\n sudo apt-get update\n sudo apt-get install libxss-dev libxft-dev libcups2-dev libatk1.0-dev libatk-bridge2.0-dev\n mkdir \"$HOME/install dir\"\n touch tk/doc/man.macros tk/generic/tkStubInit.c\n echo \"CFGOPT=$CFGOPT\" >> $GITHUB_ENV\n echo \"CC=$COMPILER\" >> $GITHUB_ENV\n echo \"TOOL_DIR=$(cd tcl/tools;pwd)\" >> $GITHUB_ENV\n echo \"BUILD_CONFIG_ID=$OPTS\" >> $GITHUB_ENV\n working-directory: \".\"\n env:\n CFGOPT: ${{ matrix.config }}\n COMPILER: ${{ matrix.compiler }}\n OPTS: ${{ matrix.compiler }}${{ matrix.config }}\n - name: Configure and Build Tcl\n run: |\n ./configure $CFGOPT \"--prefix=$HOME/install dir\" || {\n cat config.log\n echo \"::warning::Failure during Tcl Configure\"\n exit 1\n }\n make all install || {\n echo \"::warning::Failure during Tcl Build\"\n exit 1\n }\n echo \"TCL_CONFIG_PATH=`pwd`\" >> $GITHUB_ENV\n working-directory: tcl/unix\n - name: Configure (opts=${{ matrix.config }})\n run: |\n ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH \"--prefix=$HOME/install dir\" || {\n cat config.log\n echo \"::error::Failure during Configure\"\n exit 1\n }\n - name: Build\n run: |\n make binaries libraries || {\n echo \"::error::Failure during Build\"\n exit 1\n }\n - name: Build Test Harness\n run: |\n make tktest || {\n echo \"::error::Failure during Build\"\n exit 1\n }\n - name: Test-Drive Installation\n run: |\n make install || {\n echo \"::error::Failure during Install\"\n exit 1\n }\n - name: Create Distribution Package\n run: |\n make dist || {\n echo \"::error::Failure during Distribute\"\n exit 1\n }\n - name: Convert Documentation to HTML\n run: |\n make html-tk TOOL_DIR=$TOOL_DIR || {\n echo \"::error::Failure during Distribute\"\n exit 1\n }\n - name: Discover Version ID\n if: ${{ env.BUILD_CONFIG_ID == 'gcc' }}\n run: |\n cd /tmp/dist\n echo \"VERSION=`ls -d tk* | sed 's/tk//'`\" >> $GITHUB_ENV\n - name: Upload Source Distribution\n if: ${{ env.BUILD_CONFIG_ID == 'gcc' }}\n uses: actions/upload-artifact@v7\n with:\n name: Tk ${{ env.VERSION }} Source distribution (snapshot)\n path: |\n /tmp/dist/tk*\n !/tmp/dist/tk*/html/**\n - name: Upload Documentation Distribution\n if: ${{ env.BUILD_CONFIG_ID == 'gcc' }}\n uses: actions/upload-artifact@v7\n with:\n name: Tk ${{ env.VERSION }} HTML documentation (snapshot)\n path: /tmp/dist/tk*/html\n test:\n runs-on: ubuntu-24.04\n strategy:\n matrix:\n compiler:\n - \"gcc\"\n config:\n - \"\"\n - \"--enable-symbols\"\n steps:\n - name: Checkout Tk\n uses: actions/checkout@v6\n with:\n path: tk\n - name: Checkout Tcl 9.1\n uses: actions/checkout@v5\n with:\n repository: tcltk/tcl\n ref: main\n path: tcl\n - name: Setup Environment (compiler=${{ matrix.compiler }})\n run: |\n sudo apt-get update\n sudo apt-get install libxss-dev libxft-dev libcups2-dev xvfb libicu-dev xfonts-75dpi xfonts-100dpi xfonts-scalable libxfont2 unifont\n mkdir \"$HOME/install dir\"\n touch tk/doc/man.macros tk/generic/tkStubInit.c\n echo \"CFGOPT=$CFGOPT\" >> $GITHUB_ENV\n echo \"CC=$COMPILER\" >> $GITHUB_ENV\n working-directory: \".\"\n env:\n CFGOPT: ${{ matrix.config }}\n COMPILER: ${{ matrix.compiler }}\n - name: Configure and Build Tcl\n run: |\n ./configure $CFGOPT \"--prefix=$HOME/install dir\" || {\n cat config.log\n echo \"::warning::Failure during Tcl Configure\"\n exit 1\n }\n make all install || {\n echo \"::warning::Failure during Tcl Build\"\n exit 1\n }\n echo \"TCL_CONFIG_PATH=`pwd`\" >> $GITHUB_ENV\n working-directory: tcl/unix\n - name: Configure ${{ matrix.config }}\n run: |\n ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH \"--prefix=$HOME/install dir\" || {\n cat config.log\n echo \"::error::Failure during Configure\"\n exit 1\n }\n - name: Build\n run: |\n make binaries libraries tktest || {\n echo \"::error::Failure during Build\"\n exit 1\n }\n - name: Run Tests\n run: |\n xvfb-run --auto-servernum make test-classic | tee out-classic.txt\n xvfb-run --auto-servernum make test-ttk | tee out-ttk.txt\n grep -q \"Failed\t0\" out-classic.txt || {\n echo \"::error::Failure during Test\"\n exit 1\n }\n grep -q \"Failed\t0\" out-ttk.txt || {\n echo \"::error::Failure during Test\"\n exit 1\n }\n timeout-minutes: 10\n" }, { "path": ".github/workflows/linux-with-tcl9-build.yml", "content": "name: Linux (with Tcl 9.0)\non:\n push:\n branches:\n - \"main\"\n - \"core-9-0-branch\"\n tags:\n - \"core-**\"\npermissions:\n contents: read\ndefaults:\n run:\n shell: bash\n working-directory: tk/unix\nenv:\n ERROR_ON_FAILURES: 1\njobs:\n build:\n runs-on: ubuntu-24.04\n strategy:\n matrix:\n compiler:\n - \"gcc\"\n - \"clang\"\n config:\n - \"\"\n - \"CFLAGS=-DTK_NO_DEPRECATED=1\"\n - \"--disable-shared\"\n - \"--enable-symbols\"\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n path: tk\n - name: Checkout Tcl 9.0\n uses: actions/checkout@v4\n with:\n repository: tcltk/tcl\n ref: core-9-0-branch\n path: tcl\n - name: Setup Environment (compiler=${{ matrix.compiler }})\n run: |\n sudo apt-get install libx11-dev\n mkdir \"$HOME/install dir\"\n touch tk/doc/man.macros tk/generic/tkStubInit.c\n echo \"CFGOPT=$CFGOPT\" >> $GITHUB_ENV\n echo \"CC=$COMPILER\" >> $GITHUB_ENV\n echo \"TOOL_DIR=$(cd tcl/tools;pwd)\" >> $GITHUB_ENV\n echo \"BUILD_CONFIG_ID=$OPTS\" >> $GITHUB_ENV\n working-directory: \".\"\n env:\n CFGOPT: ${{ matrix.config }}\n COMPILER: ${{ matrix.compiler }}\n OPTS: ${{ matrix.compiler }}${{ matrix.config }}\n - name: Configure and Build Tcl\n run: |\n ./configure $CFGOPT \"--prefix=$HOME/install dir\" || {\n cat config.log\n echo \"::warning::Failure during Tcl Configure\"\n exit 1\n }\n make all install || {\n echo \"::warning::Failure during Tcl Build\"\n exit 1\n }\n echo \"TCL_CONFIG_PATH=`pwd`\" >> $GITHUB_ENV\n working-directory: tcl/unix\n - name: Configure (opts=${{ matrix.config }})\n run: |\n ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH \"--prefix=$HOME/install dir\" || {\n cat config.log\n echo \"::error::Failure during Configure\"\n exit 1\n }\n - name: Build\n run: |\n make binaries libraries || {\n echo \"::error::Failure during Build\"\n exit 1\n }\n - name: Build Test Harness\n run: |\n make tktest || {\n echo \"::error::Failure during Build\"\n exit 1\n }\n - name: Test-Drive Installation\n run: |\n make install || {\n echo \"::error::Failure during Install\"\n exit 1\n }\n - name: Create Distribution Package\n run: |\n make dist || {\n echo \"::error::Failure during Distribute\"\n exit 1\n }\n - name: Convert Documentation to HTML\n run: |\n make html-tk TOOL_DIR=$TOOL_DIR || {\n echo \"::error::Failure during Distribute\"\n exit 1\n }\n test:\n runs-on: ubuntu-24.04\n strategy:\n matrix:\n compiler:\n - \"gcc\"\n config:\n - \"\"\n - \"--enable-symbols\"\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n path: tk\n - name: Checkout Tcl 9.0\n uses: actions/checkout@v4\n with:\n repository: tcltk/tcl\n ref: core-9-0-branch\n path: tcl\n - name: Setup Environment (compiler=${{ matrix.compiler }})\n run: |\n sudo apt-get update\n sudo apt-get install xvfb libx11-dev libicu-dev xfonts-75dpi xfonts-100dpi xfonts-scalable libxfont2 unifont\n mkdir \"$HOME/install dir\"\n touch tk/doc/man.macros tk/generic/tkStubInit.c\n echo \"CFGOPT=$CFGOPT\" >> $GITHUB_ENV\n echo \"CC=$COMPILER\" >> $GITHUB_ENV\n working-directory: \".\"\n env:\n CFGOPT: ${{ matrix.config }}\n COMPILER: ${{ matrix.compiler }}\n - name: Configure and Build Tcl\n run: |\n ./configure $CFGOPT \"--prefix=$HOME/install dir\" || {\n cat config.log\n echo \"::warning::Failure during Tcl Configure\"\n exit 1\n }\n make all install || {\n echo \"::warning::Failure during Tcl Build\"\n exit 1\n }\n echo \"TCL_CONFIG_PATH=`pwd`\" >> $GITHUB_ENV\n working-directory: tcl/unix\n - name: Configure ${{ matrix.config }}\n run: |\n ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH \"--prefix=$HOME/install dir\" || {\n cat config.log\n echo \"::error::Failure during Configure\"\n exit 1\n }\n - name: Build\n run: |\n make binaries libraries tktest || {\n echo \"::error::Failure during Build\"\n exit 1\n }\n - name: Run Tests\n run: |\n xvfb-run --auto-servernum make test-classic | tee out-classic.txt\n xvfb-run --auto-servernum make test-ttk | tee out-ttk.txt\n grep -q \"Failed\t0\" out-classic.txt || {\n echo \"::error::Failure during Test\"\n exit 1\n }\n grep -q \"Failed\t0\" out-ttk.txt || {\n echo \"::error::Failure during Test\"\n exit 1\n }\n timeout-minutes: 15\n" }, { "path": ".github/workflows/mac-build.yml", "content": "name: macOS\non:\n push:\n branches:\n - \"main\"\n - \"core-9-0-branch\"\n tags:\n - \"core-**\"\npermissions:\n contents: read\nenv:\n ERROR_ON_FAILURES: 1\njobs:\n framework:\n runs-on: macos-26\n defaults:\n run:\n shell: bash\n working-directory: tk/macosx\n steps:\n - name: Checkout Tk\n uses: actions/checkout@v6\n with:\n path: tk\n - name: Check out Tcl 9.1\n uses: actions/checkout@v6\n with:\n repository: tcltk/tcl\n ref: main\n path: tcl\n - name: Prepare checked out repositories\n run: |\n touch tk/generic/tkStubInit.c\n mkdir build\n echo \"BUILD_DIR=`cd build && pwd`\" >> $GITHUB_ENV\n echo \"DESTDIR=`cd build && pwd`\" >> $GITHUB_ENV\n working-directory: .\n - name: Build Tcl\n run: |\n make all\n working-directory: tcl/macosx\n - name: Build\n run: |\n make all install || {\n echo \"::error::Failure during Build\"\n exit 1\n }\n - name: Run Tests\n run: |\n make TK_NO_STDERR=1 test | tee out.txt\n nmatches=$( grep -c \"Failed\t0\" out.txt )\n if [ $nmatches -lt 4 ]\n then\n echo \"::error::Failure during Test\"\n exit 1\n fi\n timeout-minutes: 30\n prefix:\n runs-on: macos-26\n strategy:\n matrix:\n symbols:\n - 'no'\n - 'mem'\n options:\n - '--enable-aqua'\n - '--disable-aqua'\n defaults:\n run:\n shell: bash\n working-directory: tk/unix\n steps:\n - name: Checkout Tk\n uses: actions/checkout@v6\n with:\n path: tk\n - name: Check out Tcl 9.1\n uses: actions/checkout@v6\n with:\n repository: tcltk/tcl\n ref: main\n path: tcl\n - name: Prepare checked out repositories\n env:\n SET_DISPLAY: ${{ contains(matrix.options, '--disable-aqua') }}\n run: |\n touch tkStubInit.c\n mkdir \"$HOME/install dir\"\n echo \"USE_XVFB=$SET_DISPLAY\" >> $GITHUB_ENV\n working-directory: tk/generic\n - name: Add X11 (if required)\n if: ${{ env.USE_XVFB == 'true' }}\n run: |\n brew install --cask xquartz\n sudo /opt/X11/libexec/privileged_startx || true\n working-directory: .\n - name: Build Tcl\n run: |\n ./configure $CFGOPT --disable-zipfs \"--prefix=$HOME/install dir\" || {\n cat config.log\n echo \"::error::Failure during Tcl Configure\"\n exit 1\n }\n make all || {\n echo \"::error::Failure during Tcl Build\"\n exit 1\n }\n make install || {\n echo \"::error::Failure during Tcl Install\"\n exit 1\n }\n working-directory: tcl/unix\n env:\n CFGOPT: --enable-symbols=${{ matrix.symbols }}\n - name: Configure (symbols=${{ matrix.symbols }} ${{matrix.options }})\n run: |\n ./configure $CFGOPT --disable-zipfs \"--prefix=$HOME/install dir\" --disable-xft || {\n cat config.log\n echo \"::error::Failure during Configure\"\n exit 1\n }\n env:\n CFGOPT: --enable-symbols=${{ matrix.symbols }} ${{matrix.options }}\n - name: Build\n run: |\n make all tktest || {\n echo \"::error::Failure during Build\"\n exit 1\n }\n - name: Run Tests\n run: |\n if [ $USE_XVFB == true ]; then\n function runXvfb {\n PATH=$PATH:/opt/X11/bin\n Xvfb $1 &\n XVFB_PID=$!\n echo Launched Xvfb $1 as process $XVFB_PID >&2\n trap \"echo killing process $XVFB_PID... >&2; kill $XVFB_PID\" 0\n export DISPLAY=$1\n sleep 2\n }\n else\n function runXvfb {\n echo Xvfb not used, this is a --enable-aqua build\n export TK_NO_STDERR=1\n }\n fi\n ( runXvfb :0; make test-classic; exit $? ) | tee out-classic.txt || {\n echo \"::error::Failure during Test (classic)\"\n exit 1\n }\n ( runXvfb :0; make test-ttk; exit $? ) | tee out-ttk.txt || {\n echo \"::error::Failure during Test (ttk)\"\n exit 1\n }\n cat out-classic.txt | grep -q \"Failed\t0\" || {\n echo \"::error::Failure in classic test results\"\n exit 1\n }\n cat out-ttk.txt | grep -q \"Failed\t0\" || {\n echo \"::error::Failure in ttk test results\"\n exit 1\n }\n timeout-minutes: 20\n - name: Carry out trial installation\n run: |\n make install || {\n cat config.log\n echo \"::error::Failure during Install\"\n exit 1\n }\n" }, { "path": ".github/workflows/onefiledist.yml", "content": "name: Build Binaries\non:\n push:\n branches:\n - \"main\"\n - \"core-9-0-branch\"\n tags:\n - \"core-**\"\npermissions:\n contents: read\njobs:\n linux:\n name: Linux\n runs-on: ubuntu-24.04\n defaults:\n run:\n shell: bash\n env:\n CC: gcc\n CFGOPT: --disable-symbols --disable-shared\n steps:\n - name: Checkout Tk\n uses: actions/checkout@v6\n with:\n path: tk\n - name: Checkout Tcl 9.1\n uses: actions/checkout@v6\n with:\n repository: tcltk/tcl\n ref: main\n path: tcl\n - name: Prepare\n run: |\n sudo apt-get update\n sudo apt-get install libxss-dev libxft-dev libcups2-dev libatk1.0-dev libatk-bridge2.0-dev\n touch tcl/generic/tclStubInit.c tcl/generic/tclOOStubInit.c\n touch tk/generic/tkStubInit.c\n echo \"INST_DIR=$(cd install;pwd)\" >> $GITHUB_ENV\n echo \"VER_PATH=$(cd tcl/tools; pwd)/addVerToFile.tcl\" >> $GITHUB_ENV\n working-directory: \".\"\n - name: Configure Tcl\n run: |\n ./configure $CFGOPT --prefix=$INST_DIR\n working-directory: tcl/unix\n - name: Build & Install Tcl\n run: |\n make binaries libraries install\n make shell SCRIPT=\"$VER_PATH $GITHUB_ENV\"\n working-directory: tcl/unix\n - name: Configure Tk\n run: |\n ./configure $CFGOPT --with-tcl=$INST_DIR/lib --prefix=$INST_DIR\n working-directory: tk/unix\n - name: Build & Install Tk\n run: |\n make binaries libraries install\n working-directory: tk/unix\n # TODO: need the Tk version separately for distro naming below\n - name: Package\n run: |\n cp bin/wish9.1 ${BUILD_NAME}\n chmod +x ${BUILD_NAME}\n tar -cf ${BUILD_NAME}.tar ${BUILD_NAME}\n working-directory: ${{ env.INST_DIR }}\n env:\n BUILD_NAME: wish${{ env.TCL_PATCHLEVEL }}_snapshot\n - name: Upload\n uses: actions/upload-artifact@v7\n with:\n name: Wish ${{ env.TCL_PATCHLEVEL }} Linux single-file build (snapshot)\n path: ${{ env.INST_DIR }}/*.tar\n - name: Describe Installation Zip Contents\n if: ${{ always() }}\n run: |\n unzip -l wish${{ env.TCL_PATCHLEVEL }}_snapshot || true\n working-directory: ${{ env.INST_DIR }}\n macos:\n name: macOS\n runs-on: macos-15\n defaults:\n run:\n shell: bash\n env:\n CC: gcc\n CFGOPT: --disable-symbols --disable-shared\n steps:\n - name: Checkout Tk\n uses: actions/checkout@v6\n with:\n path: tk\n - name: Checkout Tcl 9.1\n uses: actions/checkout@v6\n with:\n repository: tcltk/tcl\n ref: main\n path: tcl\n - name: Checkout create-dmg\n uses: actions/checkout@v6\n with:\n repository: create-dmg/create-dmg\n ref: v1.2.2\n path: create-dmg\n - name: Prepare\n run: |\n mkdir -p install/contents\n touch tcl/generic/tclStubInit.c tcl/generic/tclOOStubInit.c || true\n touch tk/generic/tkStubInit.c || true\n wget https://github.com/culler/macher/releases/download/v1.8/macher\n sudo cp macher /usr/local/bin\n sudo chmod a+x /usr/local/bin/macher\n echo \"INST_DIR=$(cd install;pwd)\" >> $GITHUB_ENV\n echo \"VER_PATH=$(cd tcl/tools; pwd)/addVerToFile.tcl\" >> $GITHUB_ENV\n echo \"CREATE_DMG=$(cd create-dmg;pwd)/create-dmg\" >> $GITHUB_ENV\n echo \"CFLAGS=-arch x86_64 -arch arm64\" >> $GITHUB_ENV\n working-directory: \".\"\n - name: Configure Tcl\n run: |\n ./configure $CFGOPT --prefix=$INST_DIR\n working-directory: tcl/unix\n - name: Build & Install Tcl\n run: |\n make binaries libraries install\n make shell SCRIPT=\"$VER_PATH $GITHUB_ENV\"\n working-directory: tcl/unix\n - name: Configure Tk\n run: |\n ./configure $CFGOPT --with-tcl=$INST_DIR/lib --prefix=$INST_DIR \\\n --enable-aqua\n working-directory: tk/unix\n - name: Build & Install Tk\n run: |\n make binaries libraries install\n working-directory: tk/unix\n # TODO: need the Tk version separately for distro naming below\n - name: Package\n run: |\n cp ../tk/unix/wish contents/${BUILD_NAME}\n chmod +x contents/${BUILD_NAME}\n cat > contents/README.txt <> $GITHUB_ENV\n echo \"VER_PATH=$(cd tcl/tools; pwd)/addVerToFile.tcl\" >> $GITHUB_ENV\n working-directory: \".\"\n - name: Configure Tcl\n run: |\n ./configure $CFGOPT --prefix=$INST_DIR\n working-directory: tcl/win\n - name: Build & Install Tcl\n run: |\n make binaries libraries install\n $INST_DIR/bin/tclsh* $VER_PATH $GITHUB_ENV\n working-directory: tcl/win\n - name: Configure Tk\n run: |\n ./configure $CFGOPT --with-tcl=$INST_DIR/lib --prefix=$INST_DIR\n working-directory: tk/win\n - name: Build & Install Tk\n run: |\n make all install\n echo \"TK_BIN=`pwd`/`echo wish*.exe`\" >> $GITHUB_ENV\n working-directory: tk/win\n # TODO: need the Tk version separately for distro naming below\n - name: Package\n run: |\n cp ${TK_BIN} combined/${BUILD_NAME}.exe\n working-directory: install\n env:\n BUILD_NAME: wish${{ env.TCL_PATCHLEVEL }}_snapshot\n - name: Upload\n uses: actions/upload-artifact@v7\n with:\n name: Wish ${{ env.TCL_PATCHLEVEL }} Windows single-file build (snapshot)\n path: install/combined/wish${{ env.TCL_PATCHLEVEL }}_snapshot.exe\n" }, { "path": ".github/workflows/win-build.yml", "content": "name: Windows\non:\n push:\n branches:\n - \"main\"\n - \"core-9-0-branch\"\n tags:\n - \"core-**\"\npermissions:\n contents: read\nenv:\n ERROR_ON_FAILURES: 1\njobs:\n msvc:\n runs-on: windows-2025\n defaults:\n run:\n shell: powershell\n working-directory: tk/win\n # Using powershell means we need to explicitly stop on failure\n strategy:\n matrix:\n config:\n - \"\"\n - \"OPTS=symbols\"\n - \"OPTS=static\"\n steps:\n - name: Checkout Tk\n uses: actions/checkout@v6\n with:\n path: tk\n - name: Checkout Tcl 9.1\n uses: actions/checkout@v6\n with:\n repository: tcltk/tcl\n ref: main\n path: tcl\n - name: Init MSVC\n uses: ilammy/msvc-dev-cmd@v1\n - name: Make Install Location\n working-directory: tcl\n run: |\n echo \"TCLDIR=`pwd`\" >> $GITHUB_ENV\n cd ..\n mkdir install\n cd install\n echo \"INSTALLDIR=`pwd`\" >> $GITHUB_ENV\n - name: Build Tcl (${{ matrix.config }})\n run: |\n &nmake -f makefile.vc release install ${{ matrix.config }}\n if ($lastexitcode -ne 0) {\n throw \"nmake exit code: $lastexitcode\"\n }\n working-directory: tcl/win\n - name: Build Tk (${{ matrix.config }})\n run: |\n &nmake -f makefile.vc all ${{ matrix.config }}\n if ($lastexitcode -ne 0) {\n throw \"nmake exit code: $lastexitcode\"\n }\n - name: Build Test Harness (${{ matrix.config }})\n run: |\n &nmake -f makefile.vc tktest ${{ matrix.config }}\n if ($lastexitcode -ne 0) {\n throw \"nmake exit code: $lastexitcode\"\n }\n - name: Run Tk Tests (${{ matrix.config }})\n run: |\n nmake -f makefile.vc test-classic ${{ matrix.config }} | tee out-classic.txt || {\n echo \"::error::Failure during Test\"\n exit 1\n }\n nmake -f makefile.vc test-ttk ${{ matrix.config }} | tee out-ttk.txt || {\n echo \"::error::Failure during Test\"\n exit 1\n }\n grep -q \"Failed\t0\" out-classic.txt || {\n echo \"::error::Failure during Test\"\n exit 1\n }\n grep -q \"Failed\t0\" out-ttk.txt || {\n echo \"::error::Failure during Test\"\n exit 1\n }\n env:\n CI_BUILD_WITH_MSVC: 1\n shell: bash\n timeout-minutes: 10\n - name: Build Help (${{ matrix.config }})\n run: |\n &nmake -f makefile.vc htmlhelp ${{ matrix.config }}\n if ($lastexitcode -ne 0) {\n throw \"nmake exit code: $lastexitcode\"\n }\n - name: Install (${{ matrix.config }})\n run: |\n &nmake -f makefile.vc install ${{ matrix.config }}\n if ($lastexitcode -ne 0) {\n throw \"nmake exit code: $lastexitcode\"\n }\n gcc:\n runs-on: windows-2025\n defaults:\n run:\n shell: msys2 {0}\n working-directory: win\n strategy:\n matrix:\n config:\n - \"\"\n - \"--enable-symbols=mem\"\n - \"--enable-symbols=all\"\n - \"--disable-shared\"\n steps:\n - name: Install MSYS2\n uses: msys2/setup-msys2@v2\n with:\n msystem: MINGW64\n install: git mingw-w64-x86_64-toolchain make zip\n - name: Checkout Tk\n uses: actions/checkout@v6\n - name: Checkout Tcl 9.1\n uses: actions/checkout@v6\n with:\n repository: tcltk/tcl\n ref: main\n path: tcl\n - name: Prepare\n run: |\n touch tkStubInit.c\n touch \"${HOME}/forWinDialog-5.12.7\"\n mkdir \"${HOME}/install_dir\"\n echo \"INSTALL_DIR=${HOME}/install_dir\" >> $GITHUB_ENV\n working-directory: generic\n - name: Configure and Build Tcl (${{ matrix.config }})\n run: |\n ./configure $CFGOPT \"--prefix=$INSTALL_DIR\" || {\n cat config.log\n echo \"::warning::Failure during Tcl Configure\"\n exit 1\n }\n make all install || {\n echo \"::warning::Failure during Tcl Build\"\n exit 1\n }\n echo \"TCL_CONFIG_PATH=`pwd`\" >> $GITHUB_ENV\n env:\n CFGOPT: --enable-64bit ${{ matrix.config }}\n working-directory: tcl/win\n - name: Configure Tk (${{ matrix.config }})\n run: |\n ./configure $CFGOPT \"--prefix=$HOME/INSTALL_DIR\" \"--with-tcl=$TCL_CONFIG_PATH\" || {\n cat config.log\n echo \"::error::Failure during Configure\"\n exit 1\n }\n env:\n CFGOPT: --enable-64bit ${{ matrix.config }}\n - name: Build Tk\n run: |\n make all install tktest || {\n echo \"::error::Failure during Build\"\n exit 1\n }\n - name: Run Tk Tests\n run: |\n make test-classic | tee out-classic.txt\n make test-ttk | tee out-ttk.txt\n grep -q \"Failed\t0\" out-classic.txt || {\n echo \"::error::Failure during Test\"\n exit 1\n }\n grep -q \"Failed\t0\" out-ttk.txt || {\n echo \"::error::Failure during Test\"\n exit 1\n }\n timeout-minutes: 10\n" }, { "path": ".gitignore", "content": "*.a\n*.bundle\n*.dll\n*.dylib\n*.dylib.E\n*.exe\n*.exp\n*.lib\n*.o\n*.obj\n*.pdb\n*.res\n*.sl\n*.so\n.fslckout\n_FOSSIL_\nMakefile\nTk-Info.plist\nWish-Info.plist\nCredits.html\nautom4te.cache\nconfig.cache\nconfig.log\nconfig.status\nconfig.status.lineno\nhtml\nmanifest.uuid\n_FOSSIL_\n*/tkConfig.sh\n*/wish\n*/tktest\n*/versions.vc\n*/version.vc\n*/libtk.vfs\n*/libtk*.zip\n*/tkUuid.h\nlibtommath/bn.ilg\nlibtommath/bn.ind\nlibtommath/pretty.build\nlibtommath/tommath.src\nlibtommath/*.log\nlibtommath/*.pdf\nlibtommath/*.pl\nlibtommath/*.sh\nlibtommath/doc/*\nlibtommath/tombc/*\nlibtommath/pre_gen/*\nlibtommath/pics/*\nlibtommath/mtest/*\nlibtommath/logs/*\nlibtommath/etc/*\nlibtommath/demo/*\nlibtommath/*.out\nlibtommath/*.tex\nmacosx/configure\nunix/autoMkindex.tcl\nunix/dltest.marker\nunix/tk.pc\nunix/tclIndex\nwin/Debug*\nwin/Release*\nwin/tk.pc\nwin/*.manifest\nwin/nmakehlp.out\nwin/nmhlp-out.txt\n" }, { "path": ".project", "content": "\n\n\ttk9.1\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\n" }, { "path": ".settings/org.eclipse.core.resources.prefs", "content": "eclipse.preferences.version=1\nencoding/=UTF-8\n" }, { "path": ".settings/org.eclipse.core.runtime.prefs", "content": "eclipse.preferences.version=1\nline.separator=\\n\n" }, { "path": "README.md", "content": "# README: Tk\n\nThis is the **Tk 9.1a2** source distribution.\n\nYou can get any source release of Tk from [our distribution\nsite](https://sourceforge.net/projects/tcl/files/Tcl/).\n\n9.1 (in development, daily build)\n[![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)\n[![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)\n[![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)\n
\n9.0 (production release, daily build)\n[![Build Status](https://github.com/tcltk/tk/actions/workflows/linux-build.yml/badge.svg?branch=core-9-0-branch)](https://github.com/tcltk/tk/actions/workflows/linux-build.yml?query=branch%3Acore-9-0-branch)\n[![Build Status](https://github.com/tcltk/tk/actions/workflows/win-build.yml/badge.svg?branch=core-9-0-branch)](https://github.com/tcltk/tk/actions/workflows/win-build.yml?query=branch%3Acore-9-0-branch)\n[![Build Status](https://github.com/tcltk/tk/actions/workflows/mac-build.yml/badge.svg?branch=core-9-0-branch)](https://github.com/tcltk/tk/actions/workflows/mac-build.yml?query=branch%3Acore-9-0-branch)\n\n## 1. Introduction\n\nThis directory contains the sources and documentation for Tk, a\ncross-platform GUI toolkit implemented with the Tcl scripting language.\n\nFor details on features, incompatibilities, and potential problems with\nthis release, see [the Tcl/Tk 9.1 Web page](https://www.tcl-lang.org/software/tcltk/9.1.html)\nor refer to the \"changes\" file in this directory, which contains a\ndescription of the changes in Tk 9.1 compared to Tk 9.0\n\nTk is maintained, enhanced, and distributed freely by the Tcl community.\nSource code development and tracking of bug reports and feature requests\ntake place at [core.tcl-lang.org](https://core.tcl-lang.org/).\nTcl/Tk release and mailing list services are [hosted by\nSourceForge](https://sourceforge.net/projects/tcl/)\nwith the Tcl Developer Xchange hosted at\n[www.tcl-lang.org](https://www.tcl-lang.org).\n\nTk is a freely available open-source package. You can do virtually\nanything you like with it, such as modifying it, redistributing it,\nand selling it either in whole or in part. See the file\n`license.terms` for complete information.\n\n## 2. See Tcl README.md\n\nPlease see the README.md file that comes with the associated Tcl release\nfor more information. There are pointers there to extensive\ndocumentation. In addition, there are additional README files\nin the subdirectories of this distribution.\n" }, { "path": "bitmaps/error.xbm", "content": "#define error_width 17\n#define error_height 17\nstatic unsigned char error_bits[] = {\n 0xf0, 0x0f, 0x00, 0x58, 0x15, 0x00, 0xac, 0x2a, 0x00, 0x16, 0x50, 0x00,\n 0x2b, 0xa0, 0x00, 0x55, 0x40, 0x01, 0xa3, 0xc0, 0x00, 0x45, 0x41, 0x01,\n 0x83, 0xc2, 0x00, 0x05, 0x45, 0x01, 0x03, 0xca, 0x00, 0x05, 0x74, 0x01,\n 0x0a, 0xa8, 0x00, 0x14, 0x58, 0x00, 0xe8, 0x2f, 0x00, 0x50, 0x15, 0x00,\n 0xa0, 0x0a, 0x00};\n" }, { "path": "bitmaps/gray12.xbm", "content": "#define gray12_width 16\n#define gray12_height 16\nstatic unsigned char gray12_bits[] = {\n 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22,\n 0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88,\n 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88};\n" }, { "path": "bitmaps/gray25.xbm", "content": "#define gray25_width 16\n#define gray25_height 16\nstatic unsigned char gray25_bits[] = {\n 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22,\n 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22,\n 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22};\n" }, { "path": "bitmaps/gray50.xbm", "content": "#define gray50_width 16\n#define gray50_height 16\nstatic unsigned char gray50_bits[] = {\n 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa,\n 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa,\n 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa};\n" }, { "path": "bitmaps/gray75.xbm", "content": "#define gray75_width 16\n#define gray75_height 16\nstatic unsigned char gray75_bits[] = {\n 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd,\n 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd,\n 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd};\n" }, { "path": "bitmaps/hourglass.xbm", "content": "#define hourglass_width 19\n#define hourglass_height 21\nstatic unsigned char hourglass_bits[] = {\n 0xff, 0xff, 0x07, 0x55, 0x55, 0x05, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01,\n 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xc2, 0x0a, 0x03, 0x46, 0x05, 0x01,\n 0x82, 0x0a, 0x03, 0x06, 0x05, 0x01, 0x02, 0x03, 0x03, 0x86, 0x05, 0x01,\n 0xc2, 0x0a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01,\n 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0xff, 0xff, 0x07,\n 0xab, 0xaa, 0x02};\n" }, { "path": "bitmaps/info.xbm", "content": "#define info_width 8\n#define info_height 21\nstatic unsigned char info_bits[] = {\n 0x3c, 0x2a, 0x16, 0x2a, 0x14, 0x00, 0x00, 0x3f, 0x15, 0x2e, 0x14, 0x2c,\n 0x14, 0x2c, 0x14, 0x2c, 0x14, 0x2c, 0xd7, 0xab, 0x55};\n" }, { "path": "bitmaps/questhead.xbm", "content": "#define questhead_width 20\n#define questhead_height 22\nstatic unsigned char questhead_bits[] = {\n 0xf8, 0x1f, 0x00, 0xac, 0x2a, 0x00, 0x56, 0x55, 0x00, 0xeb, 0xaf, 0x00,\n 0xf5, 0x5f, 0x01, 0xfb, 0xbf, 0x00, 0x75, 0x5d, 0x01, 0xfb, 0xbe, 0x02,\n 0x75, 0x5d, 0x05, 0xab, 0xbe, 0x0a, 0x55, 0x5f, 0x07, 0xab, 0xaf, 0x00,\n 0xd6, 0x57, 0x01, 0xac, 0xab, 0x00, 0xd8, 0x57, 0x00, 0xb0, 0xaa, 0x00,\n 0x50, 0x55, 0x00, 0xb0, 0x0b, 0x00, 0xd0, 0x17, 0x00, 0xb0, 0x0b, 0x00,\n 0x58, 0x15, 0x00, 0xa8, 0x2a, 0x00};\n" }, { "path": "bitmaps/question.xbm", "content": "#define question_width 17\n#define question_height 27\nstatic unsigned char question_bits[] = {\n 0xf0, 0x0f, 0x00, 0x58, 0x15, 0x00, 0xac, 0x2a, 0x00, 0x56, 0x55, 0x00,\n 0x2b, 0xa8, 0x00, 0x15, 0x50, 0x01, 0x0b, 0xa0, 0x00, 0x05, 0x60, 0x01,\n 0x0b, 0xa0, 0x00, 0x05, 0x60, 0x01, 0x0b, 0xb0, 0x00, 0x00, 0x58, 0x01,\n 0x00, 0xaf, 0x00, 0x80, 0x55, 0x00, 0xc0, 0x2a, 0x00, 0x40, 0x15, 0x00,\n 0xc0, 0x02, 0x00, 0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x40, 0x01, 0x00,\n 0xc0, 0x02, 0x00, 0x00, 0x00, 0x00, 0x80, 0x01, 0x00, 0xc0, 0x02, 0x00,\n 0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x00, 0x01, 0x00};\n" }, { "path": "bitmaps/warning.xbm", "content": "#define warning_width 6\n#define warning_height 19\nstatic unsigned char warning_bits[] = {\n 0x0c, 0x16, 0x2b, 0x15, 0x2b, 0x15, 0x2b, 0x16, 0x0a, 0x16, 0x0a, 0x16,\n 0x0a, 0x00, 0x00, 0x1e, 0x0a, 0x16, 0x0a};\n" }, { "path": "changes.md", "content": "\nThe source code for Tk is managed by fossil. Tk developers coordinate all\nchanges to the Tk source code at\n\n> [Tk Source Code](https://core.tcl-lang.org/tk/)\n\nRelease Tk 9.1a2 arises from the check-in with tag `core-9-1-a2`.\n\nTk 9.1a2 continues the Tk 9.x series of releases. The Tk 9.x series\ndo not support Tcl 8.6. The Tk 9.1 series extends the Tcl 9.0 series.\nTo make use of Tk 9.1a2, first a Tcl 9.0 or 9.1 release must be present.\nAs new Tk features are developed, expect them to appear in Tk 9, but not\nnecessarily in Tk 8.\n\n# 9.1 Features and Interfaces\n - [MS-Win: remove Windows XP dialog variants for tk_chooseDirectory and tk_getOpenFile](https://core.tcl-lang.org/tk/tktview/441c52)\n - [Extend Tk_CanvasTextInfo](https://core.tcl-lang.org/tips/doc/trunk/tip/704.md)\n - [Add new states to ttk::treeview and ttk::notebook](https://core.tcl-lang.org/tips/doc/trunk/tip/719.md)\n - [Limit tk_messageBox to physical screen width](https://core.tcl-lang.org/tk/info/e19f1d891)\n - [Constrain own Dialogs to the physical screen size](https://core.tcl-lang.org/tk/info/7c28f835)\n - [Add a ttk::toggleswitch widget to the core](https://core.tcl-lang.org/tips/doc/trunk/tip/727.md)\n - [Add a tk attribtable command to the core](https://core.tcl-lang.org/tips/doc/trunk/tip/729.md)\n - [Implement more X11 region functions on Windows and Aqua](https://core.tcl-lang.org/tk/info/50fdbc36ad)\n - [Add accessibility/screen reader support to the core](https://core.tcl-lang.org/tips/doc/trunk/tip/733.md)\n - [Scroll entry with mouse wheel](https://core.tcl-lang.org/tips/doc/trunk/tip/736.md)\n - [Add a Wide.TSpinbox style to the core](https://core.tcl-lang.org/tips/doc/trunk/tip/739.md)\n - [Add support for native file icons to the core](https://core.tcl-lang.org/tips/doc/trunk/tip/743.md)\n - [Re-implement the Aqua send command](https://core.tcl-lang.org/tk/info/1574913cc772201e)\n - [Make the selection colors of the listbox widget fully native-conform](https://core.tcl-lang.org/tips/doc/trunk/tip/747.md)\n - [Add support for bidrectional text / RTL languages on Windows and X11](https://core.tcl-lang.org/tk/info/058e738f9f06fe20)\n - [Add Mouse Wheel Zoom Support to Tk Console](https://core.tcl-lang.org/tips/doc/trunk/tip/742.md)\n\n# Potential incompatibilities to 9.0\n - [MS-Win: Remove the -xpstyle option from tk_chooseDirectory and tk_getOpenFile](https://core.tcl-lang.org/tk/tktview/441c52)\n - [MS-Win: Eliminate the \"xpnative\" ttk style, in favor of \"vista\"](https://core.tcl-lang.org/tk/tktview/441c52)\n - [No longer allow negative screen distances in most cases](https://core.tcl-lang.org/tips/doc/trunk/tip/698.md)\n - [RTL/bidirectional text is a configure option on X11 (--enable-bidi). Additionally, there are some visual artifacts with bidi strings in the text widget in cursor and selection events on all platforms](https://core.tcl-lang.org/tk/tktview/cf94f5afd)\n" }, { "path": "doc/3DBorder.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1993 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1998 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_Alloc3DBorderFromObj, Tk_ClipDrawableToRect, Tk_DrawHighlightBorder, Tk_Get3DBorder, Tk_Get3DBorderColors, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \\- draw borders with three-dimensional appearance\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n\nTk_3DBorder\n\\fBTk_Alloc3DBorderFromObj\\fR(\\fIinterp, tkwin, objPtr\\fR)\n.sp\n\\fBTk_ClipDrawableToRect\\fR(\\fIdisplay, drawable, x, y, width, height\\fR)\n.sp\n\\fBTk_DrawHighlightBorder\\fR(\\fItkwin, fgGC, bgGC, highlightWidth, drawable\\fR)\n.sp\nTk_3DBorder\n\\fBTk_Get3DBorder\\fR(\\fIinterp, tkwin, colorName\\fR)\n.sp\n\\fBTk_Get3DBorderColors\\fR(\\fIborder, bgColorPtr, darkColorPtr, lightColorPtr\\fR)\n.sp\nTk_3DBorder\n\\fBTk_Get3DBorderFromObj\\fR(\\fItkwin, objPtr\\fR)\n.sp\n\\fBTk_Draw3DRectangle\\fR(\\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\\fR)\n.sp\n\\fBTk_Fill3DRectangle\\fR(\\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\\fR)\n.sp\n\\fBTk_Draw3DPolygon\\fR(\\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\\fR)\n.sp\n\\fBTk_Fill3DPolygon\\fR(\\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\\fR)\n.sp\n\\fBTk_3DVerticalBevel\\fR(\\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\\fR)\n.sp\n\\fBTk_3DHorizontalBevel\\fR(\\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\\fR)\n.sp\n\\fBTk_SetBackgroundFromBorder\\fR(\\fItkwin, border\\fR)\n.sp\nconst char *\n\\fBTk_NameOf3DBorder\\fR(\\fIborder\\fR)\n.sp\nXColor *\n\\fBTk_3DBorderColor\\fR(\\fIborder\\fR)\n.sp\nGC *\n\\fBTk_3DBorderGC\\fR(\\fItkwin, border, which\\fR)\n.sp\n\\fBTk_Free3DBorderFromObj\\fR(\\fItkwin, objPtr\\fR)\n.sp\n\\fBTk_Free3DBorder\\fR(\\fIborder\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tk_3DBorder\" borderWidth\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP Tk_Window tkwin in\nToken for window (for all procedures except \\fBTk_Get3DBorder\\fR,\nmust be the window for which the border was allocated).\n.AP Tcl_Obj *objPtr in\nPointer to value whose value describes color corresponding to\nbackground (flat areas). Illuminated edges will be brighter than\nthis and shadowed edges will be darker than this.\n.AP \"const char\" *colorName in\nSame as \\fIobjPtr\\fR except value is supplied as a string rather\nthan a value.\n.AP Drawable drawable in\nX token for window or pixmap; indicates where graphics are to be drawn.\nMust either be the X window for \\fItkwin\\fR or a pixmap with the\nsame screen and depth as \\fItkwin\\fR.\n.AP Tk_3DBorder border in\nToken for border previously allocated in call to \\fBTk_Get3DBorder\\fR.\n.AP int x in\nX-coordinate of upper-left corner of rectangle describing border\nor bevel, in pixels.\n.AP int y in\nY-coordinate of upper-left corner of rectangle describing border or\nbevel, in pixels.\n.AP int width in\nWidth of rectangle describing border or bevel, in pixels.\n.AP int height in\nHeight of rectangle describing border or bevel, in pixels.\n.AP int borderWidth in\nWidth of border in pixels. Positive means border is inside rectangle\ngiven by \\fIx\\fR, \\fIy\\fR, \\fIwidth\\fR, \\fIheight\\fR, negative means\nborder is outside rectangle.\n.AP int highlightWidth in\nWidth of ring around the outside of the widget if the widget has received the\ninput focus.\n.AP int relief in\nIndicates 3-D position of interior of value relative to exterior;\nshould be \\fBTK_RELIEF_RAISED\\fR, \\fBTK_RELIEF_SUNKEN\\fR, \\fBTK_RELIEF_GROOVE\\fR,\n\\fBTK_RELIEF_SOLID\\fR, or \\fBTK_RELIEF_RIDGE\\fR (may also be \\fBTK_RELIEF_FLAT\\fR\nfor \\fBTk_Fill3DRectangle\\fR).\n.AP XPoint *pointPtr in\nPointer to array of points describing the set of vertices in a polygon.\nThe polygon need not be closed (it will be closed automatically if it\nis not).\n.AP int numPoints in\nNumber of points at \\fI*pointPtr\\fR.\n.AP int polyBorderWidth in\nWidth of border in pixels. If positive, border is drawn to left of\ntrajectory given by \\fIpointPtr\\fR; if negative, border is drawn to\nright of trajectory. If \\fIleftRelief\\fR is \\fBTK_RELIEF_GROOVE\\fR or\n\\fBTK_RELIEF_RIDGE\\fR then the border is centered on the trajectory.\n.AP int leftRelief in\nHeight of left side of polygon's path relative to right. \\fBTK_RELIEF_RAISED\\fR\nmeans left side should appear higher and \\fBTK_RELIEF_SUNKEN\\fR means right side\nshould appear higher;\n\\fBTK_RELIEF_GROOVE\\fR and \\fBTK_RELIEF_RIDGE\\fR mean the obvious things.\nFor \\fBTk_Fill3DPolygon\\fR, \\fBTK_RELIEF_FLAT\\fR may also be specified to\nindicate no difference in height.\n.AP int leftBevel in\nNon-zero means this bevel forms the left side of the value; zero means\nit forms the right side.\n.AP int leftIn in\nNon-zero means that the left edge of the horizontal bevel angles in,\nso that the bottom of the edge is farther to the right than\nthe top.\nZero means the edge angles out, so that the bottom is farther to the\nleft than the top.\n.AP int rightIn in\nNon-zero means that the right edge of the horizontal bevel angles in,\nso that the bottom of the edge is farther to the left than the top.\nZero means the edge angles out, so that the bottom is farther to the\nright than the top.\n.AP int topBevel in\nNon-zero means this bevel forms the top side of the value; zero means\nit forms the bottom side.\n.AP int which in\nSpecifies which of the border's graphics contexts is desired.\nMust be \\fBTK_3D_FLAT_GC\\fR, \\fBTK_3D_LIGHT_GC\\fR, or \\fBTK_3D_DARK_GC\\fR.\n.AP XColor *bgColorPtr out\nPointer to location in which to store the background color of the given border.\n.AP XColor *darkColorPtr out\nPointer to location in which to store the color for darker areas of the\ngiven border.\n.AP XColor *lightColorPtr out\nPointer to location in which to store the color for lighter areas of the\ngiven border.\n.AP GC fgGC in\nForeground X graphics context.\n.AP GC fgGC in\nBackground X graphics context.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures provide facilities for drawing window borders in a\nway that produces a three-dimensional appearance.\n\\fBTk_Alloc3DBorderFromObj\\fR\nallocates colors and Pixmaps needed to draw a border in the window\ngiven by the \\fItkwin\\fR argument. The value of \\fIobjPtr\\fR\nis a standard Tk color name that determines the border colors.\nThe color indicated by \\fIobjPtr\\fR will not actually be used in\nthe border; it indicates the background color for the window\n(i.e. a color for flat surfaces).\nThe illuminated portions of the border will appear brighter than indicated\nby \\fIobjPtr\\fR, and the shadowed portions of the border will appear\ndarker than \\fIobjPtr\\fR.\n.PP\n\\fBTk_Alloc3DBorderFromObj\\fR returns a token that may be used in later calls\nto \\fBTk_Draw3DRectangle\\fR. If an error occurs in allocating information\nfor the border (e.g. a bogus color name was given)\nthen NULL is returned and an error message is left as the result of\ninterpreter \\fIinterp\\fR.\nIf it returns successfully, \\fBTk_Alloc3DBorderFromObj\\fR caches\ninformation about the return value in \\fIobjPtr\\fR, which speeds up\nfuture calls to \\fBTk_Alloc3DBorderFromObj\\fR with the same \\fIobjPtr\\fR\nand \\fItkwin\\fR.\n.PP\n\\fBTk_ClipDrawableToRect\\fR will clip all drawing into the drawable \\fId\\fR\nto the given rectangle. If \\fIwidth\\fR or \\fIheight\\fR are negative, reset\nto no clipping.\nSubsequent drawing into \\fId\\fR is offset and clipped as specified.\nThe function is only used when \\fBTK_NO_DOUBLE_BUFFERING\\fR is specified at\ncompile time.\n.PP\n\\fBTk_DrawHighlightBorder\\fR draws a rectangular ring around the outside of\na widget to indicate that it has received the input focus.\nOn the Macintosh, this puts a 1 pixel border in the bgGC color between\nthe widget and the focus ring, except in the case where highlightWidth\nis 0 or 1, in which case the border is left out.\nFor proper Mac L&F, use highlightWidth of 3.\n.PP\n\\fBTk_Get3DBorder\\fR is identical to \\fBTk_Alloc3DBorderFromObj\\fR except\nthat the color is specified with a string instead of a value. This\nprevents \\fBTk_Get3DBorder\\fR from caching the return value, so\n\\fBTk_Get3DBorder\\fR is less efficient than \\fBTk_Alloc3DBorderFromObj\\fR.\n.PP\n\\fBTk_Get3DBorderColors\\fR returns the used colors of the given border.\n.PP\n\\fBTk_Get3DBorderFromObj\\fR returns the token for an existing border, given\nthe window and color name used to create the border.\n\\fBTk_Get3DBorderFromObj\\fR does not actually create the border; it must\nalready have been created with a previous call to\n\\fBTk_Alloc3DBorderFromObj\\fR or \\fBTk_Get3DBorder\\fR. The return\nvalue is cached in \\fIobjPtr\\fR, which speeds up\nfuture calls to \\fBTk_Get3DBorderFromObj\\fR with the same \\fIobjPtr\\fR\nand \\fItkwin\\fR.\n.PP\nOnce a border structure has been created, \\fBTk_Draw3DRectangle\\fR may be\ninvoked to draw the border.\nThe \\fItkwin\\fR argument specifies the\nwindow for which the border was allocated, and \\fIdrawable\\fR\nspecifies a window or pixmap in which the border is to be drawn.\n\\fIDrawable\\fR need not refer to the same window as \\fItkwin\\fR, but it\nmust refer to a compatible\npixmap or window: one associated with the same screen and with the\nsame depth as \\fItkwin\\fR.\nThe \\fIx\\fR, \\fIy\\fR, \\fIwidth\\fR, and\n\\fIheight\\fR arguments define the bounding box of the border region\nwithin \\fIdrawable\\fR (usually \\fIx\\fR and \\fIy\\fR are zero and\n\\fIwidth\\fR and \\fIheight\\fR are the dimensions of the window), and\n\\fIborderWidth\\fR specifies the number of pixels actually\noccupied by the border. The \\fIrelief\\fR argument indicates\nwhich of several three-dimensional effects is desired:\n\\fBTK_RELIEF_RAISED\\fR means that the interior of the rectangle should\nappear raised relative to the exterior of the rectangle, and\n\\fBTK_RELIEF_SUNKEN\\fR means that the interior should appear depressed.\n\\fBTK_RELIEF_GROOVE\\fR and \\fBTK_RELIEF_RIDGE\\fR mean that there should\nappear to be a groove or ridge around the exterior of the rectangle.\n.PP\n\\fBTk_Fill3DRectangle\\fR is somewhat like \\fBTk_Draw3DRectangle\\fR except\nthat it first fills the rectangular area with the background color\n(one corresponding\nto the color used to create \\fIborder\\fR). Then it calls\n\\fBTk_Draw3DRectangle\\fR to draw a border just inside the outer edge of\nthe rectangular area. The argument \\fIrelief\\fR indicates the desired\neffect (\\fBTK_RELIEF_FLAT\\fR means no border should be drawn; all that\nhappens is to fill the rectangle with the background color).\n.PP\nThe procedure \\fBTk_Draw3DPolygon\\fR may be used to draw more complex\nshapes with a three-dimensional appearance. The \\fIpointPtr\\fR and\n\\fInumPoints\\fR arguments define a trajectory, \\fIpolyBorderWidth\\fR\nindicates how wide the border should be (and on which side of the\ntrajectory to draw it), and \\fIleftRelief\\fR indicates which side\nof the trajectory should appear raised. \\fBTk_Draw3DPolygon\\fR\ndraws a border around the given trajectory using the colors from\n\\fIborder\\fR to produce a three-dimensional appearance. If the trajectory is\nnon-self-intersecting, the appearance will be a raised or sunken\npolygon shape. The trajectory may be self-intersecting, although\nit's not clear how useful this is.\n.PP\n\\fBTk_Fill3DPolygon\\fR is to \\fBTk_Draw3DPolygon\\fR what\n\\fBTk_Fill3DRectangle\\fR is to \\fBTk_Draw3DRectangle\\fR: it fills\nthe polygonal area with the background color from \\fIborder\\fR,\nthen calls \\fBTk_Draw3DPolygon\\fR to draw a border around the\narea (unless \\fIleftRelief\\fR is \\fBTK_RELIEF_FLAT\\fR; in this case no\nborder is drawn).\n.PP\nThe procedures \\fBTk_3DVerticalBevel\\fR and \\fBTk_3DHorizontalBevel\\fR\nprovide lower-level drawing primitives that are used by\nprocedures such as \\fBTk_Draw3DRectangle\\fR.\nThese procedures are also useful in their own right for drawing\nrectilinear border shapes.\n\\fBTk_3DVerticalBevel\\fR draws a vertical beveled edge, such as the\nleft or right side of a rectangle, and \\fBTk_3DHorizontalBevel\\fR\ndraws a horizontal beveled edge, such as the top or bottom of a\nrectangle.\nEach procedure takes \\fIx\\fR, \\fIy\\fR, \\fIwidth\\fR, and \\fIheight\\fR\narguments that describe the rectangular area of the beveled edge\n(e.g., \\fIwidth\\fR is the border width for \\fBTk_3DVerticalBevel\\fR).\nThe \\fIleftBorder\\fR and \\fItopBorder\\fR arguments indicate the\nposition of the border relative to the\n.QW inside\nof the value, and\n\\fIrelief\\fR indicates the relief of the inside of the value relative\nto the outside.\n\\fBTk_3DVerticalBevel\\fR just draws a rectangular region.\n\\fBTk_3DHorizontalBevel\\fR draws a trapezoidal region to generate\nmitered corners; it should be called after \\fBTk_3DVerticalBevel\\fR\n(otherwise \\fBTk_3DVerticalBevel\\fR will overwrite the mitering in\nthe corner).\nThe \\fIleftIn\\fR and \\fIrightIn\\fR arguments to \\fBTk_3DHorizontalBevel\\fR\ndescribe the mitering at the corners; a value of 1 means that the bottom\nedge of the trapezoid will be shorter than the top, 0 means it will\nbe longer.\nFor example, to draw a rectangular border the top bevel should be\ndrawn with 1 for both \\fIleftIn\\fR and \\fIrightIn\\fR, and the\nbottom bevel should be drawn with 0 for both arguments.\n.PP\nThe procedure \\fBTk_SetBackgroundFromBorder\\fR will modify the background\npixel and/or pixmap of \\fItkwin\\fR to produce a result compatible\nwith \\fIborder\\fR. For color displays, the resulting background will\njust be the color specified when \\fIborder\\fR was created; for monochrome\ndisplays, the resulting background\nwill be a light stipple pattern, in order to distinguish the background from\nthe illuminated portion of the border.\n.PP\nGiven a token for a border, the procedure \\fBTk_NameOf3DBorder\\fR\nwill return the color name that was used to create the border.\n.PP\nThe procedure \\fBTk_3DBorderColor\\fR returns the XColor structure\nthat will be used for flat surfaces drawn for its \\fIborder\\fR\nargument by procedures like \\fBTk_Fill3DRectangle\\fR.\nThe return value corresponds to the color name that was used to\ncreate the border.\nThe XColor, and its associated pixel value, will remain allocated\nas long as \\fIborder\\fR exists.\n.PP\nThe procedure \\fBTk_3DBorderGC\\fR returns one of the X graphics contexts\nthat are used to draw the border.\nThe argument \\fIwhich\\fR selects which one of the three possible GC's:\n\\fBTK_3D_FLAT_GC\\fR returns the context used for flat surfaces,\n\\fBTK_3D_LIGHT_GC\\fR returns the context for light shadows,\nand \\fBTK_3D_DARK_GC\\fR returns the context for dark shadows.\n.PP\nWhen a border is no longer needed, \\fBTk_Free3DBorderFromObj\\fR\nor \\fBTk_Free3DBorder\\fR should\nbe called to release the resources associated with it.\nFor \\fBTk_Free3DBorderFromObj\\fR the border to release is specified\nwith the window and color name used to create the\nborder; for \\fBTk_Free3DBorder\\fR the border to release is specified\nwith the Tk_3DBorder token for the border.\nThere should be exactly one call to \\fBTk_Free3DBorderFromObj\\fR or\n\\fBTk_Free3DBorder\\fR for each call to \\fBTk_Alloc3DBorderFromObj\\fR\nor \\fBTk_Get3DBorder\\fR.\n.SH KEYWORDS\n3D, background, border, color, depressed, illumination, value, polygon,\nraised, shadow, three-dimensional effect\n" }, { "path": "doc/AddOption.3", "content": "'\\\"\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" All rights reserved.\n'\\\"\n.TH Tk_AddOption 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_AddOption \\- Add an option to the option database\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nvoid\n\\fBTk_AddOption\\fR(\\fItkwin, name, value, priority\\fR)\n.sp\nTcl_Obj *\n\\fBTk_GetSystemDefault\\fR(\\fItkwin, dbName, className\\fR)\n.fi\n.SH ARGUMENTS\n.AP Tk_Window tkwin in\nToken for window.\n.AP \"const char\" *name in\nMulti-element name of option.\n.AP \"const char\" *value in\nValue of option.\n.AP \"const char\" *dbName in\nThe option database name.\n.AP \"const char\" *className in\nThe name of the option class.\n.AP int priority in\nOverall priority level to use for option.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_AddOption\\fR is invoked to add an option to the database\nassociated with \\fItkwin\\fR's main window. \\fIName\\fR\ncontains the option being specified and consists of names and/or\nclasses separated by asterisks or dots, in the usual X format.\n\\fIValue\\fR contains the text string to associate with \\fIname\\fR;\nthis value will be returned in calls to \\fBTk_GetOption\\fR.\n\\fIPriority\\fR specifies the priority of the value; when options are\nqueried using \\fBTk_GetOption\\fR, the value with the highest priority\nis returned. \\fIPriority\\fR must be between 0 and \\fBTK_MAX_PRIO\\fR (100).\nSome common priority values are:\n.IP \\fBTK_WIDGET_DEFAULT_PRIO\\fR (20)\nUsed for default values hard-coded into widgets.\n.IP \\fBTK_STARTUP_FILE_PRIO\\fR (40)\nUsed for options specified in application-specific startup files.\n.IP \\fBTK_USER_DEFAULT_PRIO\\fR (60)\nUsed for options specified in user-specific defaults files, such as\n\\fB.Xdefaults\\fR, resource databases loaded into the X server, or\nuser-specific startup files.\n.IP \\fBTK_INTERACTIVE_PRIO\\fR (80)\nUsed for options specified interactively after the application starts\nrunning.\n.PP\n\\fBTk_GetSystemDefault\\fR returns a Tcl_Obj* with the string identifying\na configuration option matching the given \\fIdbname\\fR and \\fIclassName\\fR.\nReturns NULL if there are no system defaults that match this pair.\n.SH KEYWORDS\nclass, name, option, add\n" }, { "path": "doc/BindTable.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CreateBindingTable 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \\- invoke scripts in response to X events\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_BindingTable\n\\fBTk_CreateBindingTable\\fR(\\fIinterp\\fR)\n.sp\n\\fBTk_DeleteBindingTable\\fR(\\fIbindingTable\\fR)\n.sp\nunsigned long\n\\fBTk_CreateBinding\\fR(\\fIinterp, bindingTable, object, eventString, script, append\\fR)\n.sp\nint\n\\fBTk_DeleteBinding\\fR(\\fIinterp, bindingTable, object, eventString\\fR)\n.sp\nconst char *\n\\fBTk_GetBinding\\fR(\\fIinterp, bindingTable, object, eventString\\fR)\n.sp\n\\fBTk_GetAllBindings\\fR(\\fIinterp, bindingTable, object\\fR)\n.sp\n\\fBTk_DeleteAllBindings\\fR(\\fIbindingTable, object\\fR)\n.sp\n\\fBTk_BindEvent\\fR(\\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_BindingTable bindingTable\n.AP Tcl_Interp *interp in\nInterpreter to use when invoking bindings in binding table. Also\nused for returning results and errors from binding procedures.\n.AP Tk_BindingTable bindingTable in\nToken for binding table; must have been returned by some previous\ncall to \\fBTk_CreateBindingTable\\fR.\n.AP \"void *\" object in\nIdentifies object with which binding is associated.\n.AP \"const char\" *eventString in\nString describing event sequence.\n.AP \"const char\" *script in\nTcl script to invoke when binding triggers.\n.AP int append in\nNon-zero means append \\fIscript\\fR to existing script for binding,\nif any; zero means replace existing script with new one.\n.AP XEvent *eventPtr in\nX event to match against bindings in \\fIbindingTable\\fR.\n.AP Tk_Window tkwin in\nIdentifier for any window on the display where the event occurred.\nUsed to find display-related information such as key maps.\n.AP Tcl_Size numObjects in\nNumber of object identifiers pointed to by \\fIobjectPtr\\fR.\n.AP \"void **\" objectPtr in\nPoints to an array of object identifiers: bindings will be considered\nfor each of these objects in order from first to last.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures provide a general-purpose mechanism for creating\nand invoking bindings.\nBindings are organized in terms of \\fIbinding tables\\fR.\nA binding table consists of a collection of bindings plus a history\nof recent events.\nWithin a binding table, bindings are associated with \\fIobjects\\fR.\nThe meaning of an object is defined by clients of the binding package.\nFor example, Tk keeps uses one binding table to hold all of the bindings\ncreated by the \\fBbind\\fR command.\nFor this table, objects are pointers to strings such as window names, class\nnames, or other binding tags such as \\fBall\\fR.\nTk also keeps a separate binding table for each canvas widget, which manages\nbindings created by the canvas's \\fBbind\\fR widget command; within\nthis table, an object is either a pointer to the internal structure for a\ncanvas item or a Tk_Uid identifying a tag.\n.PP\nThe procedure \\fBTk_CreateBindingTable\\fR creates a new binding\ntable and associates \\fIinterp\\fR with it (when bindings in the\ntable are invoked, the scripts will be evaluated in \\fIinterp\\fR).\n\\fBTk_CreateBindingTable\\fR returns a token for the table, which\nmust be used in calls to other procedures such as \\fBTk_CreateBinding\\fR\nor \\fBTk_BindEvent\\fR.\n.PP\n\\fBTk_DeleteBindingTable\\fR frees all of the state associated\nwith a binding table.\nOnce it returns the caller should not use the \\fIbindingTable\\fR\ntoken again.\n.PP\n\\fBTk_CreateBinding\\fR adds a new binding to an existing table.\nThe \\fIobject\\fR argument identifies the object with which the\nbinding is to be associated, and it may be any one-word value.\nTypically it is a pointer to a string or data structure.\nThe \\fIeventString\\fR argument identifies the event or sequence\nof events for the binding; see the documentation for the\n\\fBbind\\fR command for a description of its format.\n\\fIscript\\fR is the Tcl script to be evaluated when the binding\ntriggers.\n\\fIappend\\fR indicates what to do if there already\nexists a binding for \\fIobject\\fR and \\fIeventString\\fR: if \\fIappend\\fR\nis zero then \\fIscript\\fR replaces the old script; if \\fIappend\\fR\nis non-zero then the new script is appended to the old one.\n\\fBTk_CreateBinding\\fR returns an X event mask for all the events\nassociated with the bindings.\nThis information may be useful to invoke \\fBXSelectInput\\fR to\nselect relevant events, or to disallow the use of certain events\nin bindings.\nIf an error occurred while creating the binding (e.g., \\fIeventString\\fR\nrefers to a non-existent event), then 0 is returned and an error\nmessage is left as the result of interpreter \\fIinterp\\fR.\n.PP\n\\fBTk_DeleteBinding\\fR removes from \\fIbindingTable\\fR the\nbinding given by \\fIobject\\fR and \\fIeventString\\fR, if\nsuch a binding exists.\n\\fBTk_DeleteBinding\\fR always returns \\fBTCL_OK\\fR.\nIn some cases it may reset the interpreter result to the default\nempty value.\n.PP\n\\fBTk_GetBinding\\fR returns a pointer to the script associated\nwith \\fIeventString\\fR and \\fIobject\\fR in \\fIbindingTable\\fR.\nIf no such binding exists then NULL is returned and an error\nmessage is left as the result of interpreter \\fIinterp\\fR.\n.PP\n\\fBTk_GetAllBindings\\fR returns in \\fIinterp\\fR's result a list\nof all the event strings for which there are bindings in\n\\fIbindingTable\\fR associated with \\fIobject\\fR.\nIf there are no bindings for \\fIobject\\fR, the result will be an empty\nstring.\n.PP\n\\fBTk_DeleteAllBindings\\fR deletes all of the bindings in\n\\fIbindingTable\\fR that are associated with \\fIobject\\fR.\n.PP\n\\fBTk_BindEvent\\fR is called to process an event.\nIt makes a copy of the event in an internal history list associated\nwith the binding table, then it checks for bindings that match\nthe event.\n\\fBTk_BindEvent\\fR processes each of the objects pointed to\nby \\fIobjectPtr\\fR in turn.\nFor each object, it finds all the bindings that match the current\nevent history, selects the most specific binding using the priority\nmechanism described in the documentation for \\fBbind\\fR,\nand invokes the script for that binding.\nIf there are no matching bindings for a particular object, then\nthe object is skipped.\n\\fBTk_BindEvent\\fR continues through all of the objects, handling\nexceptions such as errors, \\fBbreak\\fR, and \\fBcontinue\\fR as\ndescribed in the documentation for \\fBbind\\fR.\n.SH KEYWORDS\nbinding, event, object, script\n" }, { "path": "doc/CanvPsY.3", "content": "'\\\"\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CanvasPs 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple \\- utility procedures for generating Postscript for canvases\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\ndouble\n\\fBTk_CanvasPsY\\fR(\\fIcanvas, canvasY\\fR)\n.sp\nint\n\\fBTk_CanvasPsBitmap\\fR(\\fIinterp, canvas, bitmap, x, y, width, height\\fR)\n.sp\nint\n\\fBTk_CanvasPsColor\\fR(\\fIinterp, canvas, colorPtr\\fR)\n.sp\nint\n\\fBTk_CanvasPsFont\\fR(\\fIinterp, canvas, tkFont\\fR)\n.sp\n\\fBTk_CanvasPsPath\\fR(\\fIinterp, canvas, coordPtr, numPoints\\fR)\n.sp\nint\n\\fBTk_CanvasPsStipple\\fR(\\fIinterp, canvas, bitmap\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tcl_Size \"numPoints\"\n.AP Tk_Canvas canvas in\nA token that identifies a canvas widget for which Postscript is\nbeing generated.\n.AP double canvasY in\nY-coordinate in the space of the canvas.\n.AP Tcl_Interp *interp in/out\nA Tcl interpreter; Postscript is appended to its result, or the\nresult may be replaced with an error message.\n.AP Pixmap bitmap in\nBitmap to use for generating Postscript.\n.AP int x in\nX-coordinate within \\fIbitmap\\fR of left edge of region to output.\n.AP int y in\nY-coordinate within \\fIbitmap\\fR of top edge of region to output.\n.AP \"int\" width in\nWidth of region of bitmap to output, in pixels.\n.AP \"int\" height in\nHeight of region of bitmap to output, in pixels.\n.AP XColor *colorPtr in\nInformation about color value to set in Postscript.\n.AP Tk_Font tkFont in\nFont for which Postscript is to be generated.\n.AP double *coordPtr in\nPointer to an array of coordinates for one or more\npoints specified in canvas coordinates.\nThe order of values in \\fIcoordPtr\\fR is x1, y1, x2, y2, x3, y3,\nand so on.\n.AP Tcl_Size numPoints in\nNumber of points at \\fIcoordPtr\\fR.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures are called by canvas type managers to carry out\ncommon functions related to generating Postscript.\nMost of the procedures take a \\fIcanvas\\fR argument, which\nrefers to a canvas widget for which Postscript is being\ngenerated.\n.PP\n\\fBTk_CanvasPsY\\fR takes as argument a y-coordinate in the space of\na canvas and returns the value that should be used for that point\nin the Postscript currently being generated for \\fIcanvas\\fR.\nY coordinates require transformation because Postscript uses an\norigin at the lower-left corner whereas X uses an origin at the\nupper-left corner.\nCanvas x coordinates can be used directly in Postscript without\ntransformation.\n.PP\n\\fBTk_CanvasPsBitmap\\fR generates Postscript to describe a region\nof a bitmap.\nThe Postscript is generated in proper image data format for Postscript,\ni.e., as data between angle brackets, one bit per pixel.\nThe Postscript is appended to the result of interpreter \\fIinterp\\fR\nand \\fBTCL_OK\\fR is returned unless an error occurs, in which case\n\\fBTCL_ERROR\\fR is returned and the interpreter result is overwritten\nwith an error message.\n.PP\n\\fBTk_CanvasPsColor\\fR generates Postscript to set the current color\nto correspond to its \\fIcolorPtr\\fR argument, taking into account any\ncolor map specified in the \\fBpostscript\\fR command.\nIt appends the Postscript to the interpreter \\fIinterp\\fR's result and returns\n\\fBTCL_OK\\fR unless an error occurs, in which case \\fBTCL_ERROR\\fR is\nreturned and the interpreter's result is overwritten with an error message.\n.PP\n\\fBTk_CanvasPsFont\\fR generates Postscript that sets the current font\nto match \\fItkFont\\fR as closely as possible.\n\\fBTk_CanvasPsFont\\fR takes into account any font map specified\nin the \\fBpostscript\\fR command, and it does\nthe best it can at mapping X fonts to Postscript fonts.\nIt appends the Postscript to interpreter \\fIinterp\\fR's result and\nreturns \\fBTCL_OK\\fR unless an error occurs, in which case\n\\fBTCL_ERROR\\fR is returned and the interpreter's result is\noverwritten with an error message.\n.PP\n\\fBTk_CanvasPsPath\\fR generates Postscript to set the current path\nto the set of points given by \\fIcoordPtr\\fR and \\fInumPoints\\fR.\nIt appends the resulting Postscript to the result of interpreter \\fIinterp\\fR.\n.PP\n\\fBTk_CanvasPsStipple\\fR generates Postscript that will fill the\ncurrent path in stippled fashion.\nIt uses \\fIbitmap\\fR as the stipple pattern and the current Postscript\ncolor; ones in the stipple bitmap are drawn in the current color, and\nzeroes are not drawn at all.\nThe Postscript is appended to interpreter \\fIinterp\\fR's result and\n\\fBTCL_OK\\fR is returned, unless an error occurs, in which case\n\\fBTCL_ERROR\\fR is returned and the interpreter's result is\noverwritten with an error message.\n.SH KEYWORDS\nbitmap, canvas, color, font, path, Postscript, stipple\n" }, { "path": "doc/CanvTkwin.3", "content": "'\\\"\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CanvasTkwin 3 4.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \\- utility procedures for canvas type managers\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Window\n\\fBTk_CanvasTkwin\\fR(\\fIcanvas\\fR)\n.sp\nint\n\\fBTk_CanvasGetCoord\\fR(\\fIinterp, canvas, string, doublePtr\\fR)\n.sp\n\\fBTk_CanvasDrawableCoords\\fR(\\fIcanvas, x, y, drawableXPtr, drawableYPtr\\fR)\n.sp\n\\fBTk_CanvasSetStippleOrigin\\fR(\\fIcanvas, gc\\fR)\n.sp\n\\fBTk_CanvasWindowCoords\\fR(\\fIcanvas, x, y, screenXPtr, screenYPtr\\fR)\n.sp\n\\fBTk_CanvasEventuallyRedraw\\fR(\\fIcanvas, x1, y1, x2, y2\\fR)\n.sp\nTk_OptionParseProc *\\fBTk_CanvasTagsParseProc\\fR;\n.sp\nTk_OptionPrintProc *\\fBTk_CanvasTagsPrintProc\\fR;\n.fi\n.SH ARGUMENTS\n.AS Tk_ItemType *drawableXPtr\n.AP Tk_Canvas canvas in\nA token that identifies a canvas widget.\n.AP Tcl_Interp *interp in/out\nInterpreter to use for error reporting.\n.AP \"const char\" *string in\nTextual description of a canvas coordinate.\n.AP double *doublePtr out\nPoints to place to store a converted coordinate.\n.AP double x in\nAn x coordinate in the space of the canvas.\n.AP double y in\nA y coordinate in the space of the canvas.\n.AP short *drawableXPtr out\nPointer to a location in which to store an x coordinate in the space\nof the drawable currently being used to redisplay the canvas.\n.AP short *drawableYPtr out\nPointer to a location in which to store a y coordinate in the space\nof the drawable currently being used to redisplay the canvas.\n.AP GC gc out\nGraphics context to modify.\n.AP short *screenXPtr out\nPoints to a location in which to store the screen coordinate in the\ncanvas window that corresponds to \\fIx\\fR.\n.AP short *screenYPtr out\nPoints to a location in which to store the screen coordinate in the\ncanvas window that corresponds to \\fIy\\fR.\n.AP int x1 in\nLeft edge of the region that needs redisplay. Only pixels at or to\nthe right of this coordinate need to be redisplayed.\n.AP int y1 in\nTop edge of the region that needs redisplay. Only pixels at or below\nthis coordinate need to be redisplayed.\n.AP int x2 in\nRight edge of the region that needs redisplay. Only pixels to\nthe left of this coordinate need to be redisplayed.\n.AP int y2 in\nBottom edge of the region that needs redisplay. Only pixels above\nthis coordinate need to be redisplayed.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures are called by canvas type managers to perform various\nutility functions.\n.PP\n\\fBTk_CanvasTkwin\\fR returns the Tk_Window associated with a particular\ncanvas.\n.PP\n\\fBTk_CanvasGetCoord\\fR translates a string specification of a\ncoordinate (such as \\fB2p\\fR or \\fB1.6c\\fR) into a double-precision\ncanvas coordinate.\nIf \\fIstring\\fR is a valid coordinate description then \\fBTk_CanvasGetCoord\\fR\nstores the corresponding canvas coordinate at *\\fIdoublePtr\\fR\nand returns \\fBTCL_OK\\fR.\nOtherwise it stores an error message in the interpreter result and\nreturns \\fBTCL_ERROR\\fR.\n.PP\n\\fBTk_CanvasDrawableCoords\\fR is called by type managers during\nredisplay to compute where to draw things.\nGiven \\fIx\\fR and \\fIy\\fR coordinates in the space of the\ncanvas, \\fBTk_CanvasDrawableCoords\\fR computes the corresponding\npixel in the drawable that is currently being used for redisplay;\nit returns those coordinates in *\\fIdrawableXPtr\\fR and *\\fIdrawableYPtr\\fR.\nThis procedure should not be invoked except during redisplay.\n.PP\n\\fBTk_CanvasSetStippleOrigin\\fR is also used during redisplay.\nIt sets the stipple origin in \\fIgc\\fR so that stipples drawn\nwith \\fIgc\\fR in the current offscreen pixmap will line up\nwith stipples drawn with origin (0,0) in the canvas's actual\nwindow.\n\\fBTk_CanvasSetStippleOrigin\\fR is needed in order to guarantee\nthat stipple patterns line up properly when the canvas is\nredisplayed in small pieces.\nRedisplays are carried out in double-buffered fashion where a\npiece of the canvas is redrawn in an offscreen pixmap and then\ncopied back onto the screen.\nIn this approach the stipple origins in graphics contexts need to\nbe adjusted during each redisplay to compensate for the position\nof the off-screen pixmap relative to the window.\nIf an item is being drawn with stipples, its type manager typically\ncalls \\fBTk_CanvasSetStippleOrigin\\fR just before using \\fIgc\\fR\nto draw something; after it is finished drawing, the type manager\ncalls \\fBXSetTSOrigin\\fR to restore the origin in \\fIgc\\fR back to (0,0)\n(the restore is needed because graphics contexts are shared, so\nthey cannot be modified permanently).\n.PP\n\\fBTk_CanvasWindowCoords\\fR is similar to \\fBTk_CanvasDrawableCoords\\fR\nexcept that it returns coordinates in the canvas's window on the\nscreen, instead of coordinates in an off-screen pixmap.\n.PP\n\\fBTk_CanvasEventuallyRedraw\\fR may be invoked by a type manager\nto inform Tk that a portion of a canvas needs to be redrawn.\nThe \\fIx1\\fR, \\fIy1\\fR, \\fIx2\\fR, and \\fIy2\\fR arguments\nspecify the region that needs to be redrawn, in canvas coordinates.\nType managers rarely need to invoke \\fBTk_CanvasEventuallyRedraw\\fR,\nsince Tk can normally figure out when an item has changed and make\nthe redisplay request on its behalf (this happens, for example\nwhenever Tk calls a \\fIconfigureProc\\fR or \\fIscaleProc\\fR).\nThe only time that a type manager needs to call\n\\fBTk_CanvasEventuallyRedraw\\fR is if an item has changed on its own\nwithout being invoked through one of the procedures in its Tk_ItemType;\nthis could happen, for example, in an image item if the image is\nmodified using image commands.\n.PP\n\\fBTk_CanvasTagsParseProc\\fR and \\fBTk_CanvasTagsPrintProc\\fR are\nprocedures that handle the \\fB\\-tags\\fR option for canvas items.\nThe code of a canvas type manager will not call these procedures\ndirectly, but will use their addresses to create a \\fBTk_CustomOption\\fR\nstructure for the \\fB\\-tags\\fR option. The code typically looks\nlike this:\n.PP\n.CS\nstatic const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,\n Tk_CanvasTagsPrintProc, NULL\n};\n\nstatic const Tk_ConfigSpec configSpecs[] = {\n ...\n {TK_CONFIG_CUSTOM, \"-tags\", NULL, NULL,\n NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},\n ...\n};\n.CE\n.SH KEYWORDS\ncanvas, focus, item type, redisplay, selection, type manager\n" }, { "path": "doc/CanvTxtInfo.3", "content": "'\\\"\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CanvasTextInfo 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CanvasTextInfo \\- additional information for managing text items in canvases\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_CanvasTextInfo *\n\\fBTk_CanvasGetTextInfo\\fR(\\fIcanvas\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Canvas canvas\n.AP Tk_Canvas canvas in\nA token that identifies a particular canvas widget.\n.BE\n.SH DESCRIPTION\n.PP\nTextual canvas items are somewhat more complicated to manage than\nother items, due to things like the selection and the input focus.\n\\fBTk_CanvasGetTextInfo\\fR may be invoked by a type manager\nto obtain additional information needed for items that display text.\nThe return value from \\fBTk_CanvasGetTextInfo\\fR is a pointer to\na structure that is shared between Tk and all the items that display\ntext.\nThe structure has the following form:\n.CS\ntypedef struct {\n Tk_3DBorder \\fIselBorder\\fR;\n int \\fIselBorderWidth\\fR;\n XColor *\\fIselFgColorPtr\\fR;\n Tk_Item *\\fIselItemPtr\\fR;\n Tcl_Size \\fIselectFirst\\fR;\n Tcl_Size \\fIselectLast\\fR;\n Tk_Item *\\fIanchorItemPtr\\fR;\n Tcl_Size \\fIselectAnchor\\fR;\n Tk_3DBorder \\fIinsertBorder\\fR;\n int \\fIinsertWidth\\fR;\n int \\fIinsertBorderWidth\\fR;\n Tk_Item *\\fIfocusItemPtr\\fR;\n int \\fIgotFocus\\fR;\n int \\fIcursorOn\\fR;\n Tcl_Obj *\\fIinsertBorderWidthObj\\fR;\n Tcl_Obj *\\fIinsertWidthObj\\fR;\n Tcl_Obj *\\fIselBorderWidthObj\\fR;\n} \\fBTk_CanvasTextInfo\\fR;\n.CE\nThe \\fBselBorder\\fR field identifies a Tk_3DBorder that should be\nused for drawing the background under selected text.\n\\fIselBorderWidth\\fR gives the width of the raised border around\nselected text, in pixels. \\fIselBorderWidthObj\\fR contains the\nsame information, but the original Tcl_Obj * value;\n\\fIselFgColorPtr\\fR points to an XColor that describes the foreground\ncolor to be used when drawing selected text.\n\\fIselItemPtr\\fR points to the item that is currently selected, or\nNULL if there is no item selected or if the canvas does not have the\nselection.\n\\fIselectFirst\\fR and \\fIselectLast\\fR give the indices of the first\nand last selected characters in \\fIselItemPtr\\fR, as returned by the\n\\fIindexProc\\fR for that item.\n\\fIanchorItemPtr\\fR points to the item that currently has the selection\nanchor; this is not necessarily the same as \\fIselItemPtr\\fR.\n\\fIselectAnchor\\fR is an index that identifies the anchor position\nwithin \\fIanchorItemPtr\\fR.\n\\fIinsertBorder\\fR contains a Tk_3DBorder to use when drawing the\ninsertion cursor; \\fIinsertWidth\\fR gives the total width of the\ninsertion cursor in pixels, and \\fIinsertBorderWidth\\fR gives the\nwidth of the raised border around the insertion cursor.\n\\fIinsertWidthObj\\fR and \\fIinsertBorderWidthObj\\fR contain the\nsame information, but the original Tcl_Obj * value.\n\\fIfocusItemPtr\\fR identifies the item that currently has the input\nfocus, or NULL if there is no such item.\n\\fIgotFocus\\fR is 1 if the canvas widget has the input focus and\n0 otherwise.\n\\fIcursorOn\\fR is 1 if the insertion cursor should be drawn in\n\\fIfocusItemPtr\\fR and 0 if it should not be drawn; this field\nis toggled on and off by Tk to make the cursor blink.\n.PP\nThe structure returned by \\fBTk_CanvasGetTextInfo\\fR\nis shared between Tk and the type managers; typically the type manager\ncalls \\fBTk_CanvasGetTextInfo\\fR once when an item is created and\nthen saves the pointer in the item's record.\nTk will update information in the Tk_CanvasTextInfo; for example,\na \\fBconfigure\\fR widget command might change the \\fIselBorder\\fR\nfield, or a \\fBselect\\fR widget command might change the \\fIselectFirst\\fR\nfield, or Tk might change \\fIcursorOn\\fR in order to make the insertion\ncursor flash on and off during successive redisplays.\n.PP\nType managers should treat all of the fields of the Tk_CanvasTextInfo\nstructure as read-only, except for \\fIselItemPtr\\fR, \\fIselectFirst\\fR,\n\\fIselectLast\\fR, and \\fIselectAnchor\\fR.\nType managers may change \\fIselectFirst\\fR, \\fIselectLast\\fR, and\n\\fIselectAnchor\\fR to adjust for insertions and deletions in the\nitem (but only if the item is the current owner of the selection or\nanchor, as determined by \\fIselItemPtr\\fR or \\fIanchorItemPtr\\fR).\nIf all of the selected text in the item is deleted, the item should\nset \\fIselItemPtr\\fR to NULL to indicate that there is no longer a\nselection.\n.SH KEYWORDS\ncanvas, focus, insertion cursor, selection, selection anchor, text\n" }, { "path": "doc/Clipboard.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_ClipboardClear 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_ClipboardClear, Tk_ClipboardAppend \\- Manage the clipboard\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_ClipboardClear\\fR(\\fIinterp, tkwin\\fR)\n.sp\nint\n\\fBTk_ClipboardAppend\\fR(\\fIinterp, tkwin, target, format, buffer\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_ClipboardClear tkwin\n.AP Tcl_Interp *interp in\nInterpreter to use for reporting errors.\n.AP Tk_Window tkwin in\nWindow that determines which display's clipboard to manipulate.\n.AP Atom target in\nConversion type for this clipboard item; has same meaning as\n\\fItarget\\fR argument to \\fBTk_CreateSelHandler\\fR.\n.AP Atom format in\nRepresentation to use when data is retrieved; has same meaning as\n\\fIformat\\fR argument to \\fBTk_CreateSelHandler\\fR.\n.AP \"const char\" *buffer in\nNull terminated string containing the data to be appended to the clipboard.\n.BE\n.SH DESCRIPTION\n.PP\nThese two procedures manage the clipboard for Tk.\nThe clipboard is typically managed by calling \\fBTk_ClipboardClear\\fR\nonce, then calling \\fBTk_ClipboardAppend\\fR to add data for any\nnumber of targets.\n.PP\n\\fBTk_ClipboardClear\\fR claims the CLIPBOARD selection and frees any\ndata items previously stored on the clipboard in this application.\nIt normally returns \\fBTCL_OK\\fR, but if an error occurs it returns\n\\fBTCL_ERROR\\fR and leaves an error message in interpreter\n\\fIinterp\\fR's result.\n\\fBTk_ClipboardClear\\fR must be called before a sequence of\n\\fBTk_ClipboardAppend\\fR calls can be issued.\n.PP\n\\fBTk_ClipboardAppend\\fR appends a buffer of data to the clipboard.\nThe first buffer for a given \\fItarget\\fR determines the \\fIformat\\fR\nfor that \\fItarget\\fR.\nAny successive appends for that \\fItarget\\fR must have\nthe same format or an error will be returned.\n\\fBTk_ClipboardAppend\\fR returns \\fBTCL_OK\\fR if the buffer is\nsuccessfully copied onto the clipboard. If the clipboard is not\ncurrently owned by the application, either\nbecause \\fBTk_ClipboardClear\\fR has not been called or because\nownership of the clipboard has changed since the last call to\n\\fBTk_ClipboardClear\\fR,\n\\fBTk_ClipboardAppend\\fR returns \\fBTCL_ERROR\\fR and leaves an error\nmessage in the result of interpreter \\fIinterp\\fR.\n.PP\nIn order to guarantee atomicity, no event handling should occur\nbetween \\fBTk_ClipboardClear\\fR and the following\n\\fBTk_ClipboardAppend\\fR calls (otherwise someone could retrieve\na partially completed clipboard or claim ownership away from\nthis application).\n.PP\n\\fBTk_ClipboardClear\\fR may invoke callbacks, including arbitrary\nTcl scripts, as a result of losing the CLIPBOARD selection, so\nany calling function should take care to be re-entrant at the point\n\\fBTk_ClipboardClear\\fR is invoked.\n.SH KEYWORDS\nappend, clipboard, clear, format, type\n" }, { "path": "doc/ClrSelect.3", "content": "'\\\"\n'\\\" Copyright (c) 1992-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_ClearSelection 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_ClearSelection \\- Deselect a selection\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_ClearSelection\\fR(\\fItkwin, selection\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window tkwin\n.AP Tk_Window tkwin in\nThe selection will be cleared from the display containing this\nwindow.\n.AP Atom selection in\nThe name of selection to be cleared.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_ClearSelection\\fR cancels the selection specified by the atom\n\\fIselection\\fR for the display containing \\fItkwin\\fR.\nThe selection need not be in \\fItkwin\\fR itself or even in\n\\fItkwin\\fR's application.\nIf there is a window anywhere on \\fItkwin\\fR's display that\nowns \\fIselection\\fR, the window will be notified and the\nselection will be cleared.\nIf there is no owner for \\fIselection\\fR on the display, then the\nprocedure has no effect.\n.SH KEYWORDS\nclear, selection\n" }, { "path": "doc/ConfigWidg.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_ConfigureWidget 3 4.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \\- process configuration options for widgets\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_ConfigureWidget\\fR(\\fIinterp, tkwin, specs, objc, objv, widgRec, flags\\fR)\n.sp\nint\n\\fBTk_ConfigureInfo\\fR(\\fIinterp, tkwin, specs, widgRec, argvName, flags\\fR)\n.sp\nint\n\\fBTk_ConfigureValue\\fR(\\fIinterp, tkwin, specs, widgRec, argvName, flags\\fR)\n.sp\n\\fBTk_FreeOptions\\fR(\\fIspecs, widgRec, display, flags\\fR)\n.fi\n.SH ARGUMENTS\n.AS void *widgRec in/out\n.AP Tcl_Interp *interp in\nInterpreter to use for returning error messages.\n.AP Tk_Window tkwin in\nWindow used to represent widget (needed to set up X resources).\n.AP \"const Tk_ConfigSpec\" *specs in\nPointer to table specifying legal configuration options for this\nwidget.\n.AP Tcl_Size objc in\nNumber of arguments in \\fIobjv\\fR.\n.AP \"Tcl_Obj *const *\" objv in\nCommand-line options for configuring widget.\n.AP char *widgRec in/out\nPoints to widget record structure. Fields in this structure get\nmodified by \\fBTk_ConfigureWidget\\fR to hold configuration information.\n.AP int flags in\nIf non-zero, then it specifies an OR-ed combination of flags that\ncontrol the processing of configuration information.\n\\fBTK_CONFIG_ARGV_ONLY\\fR causes the option database and defaults to be\nignored, and flag bits \\fBTK_CONFIG_USER_BIT\\fR and higher are used to\nselectively disable entries in \\fIspecs\\fR.\n.AP \"type name\" type in\nThe name of the type of a widget record.\n.AP \"field name\" field in\nThe name of a field in records of type \\fItype\\fR.\n.AP \"const char\" *argvName in\nThe name used on Tcl command lines to refer to a particular option\n(e.g. when creating a widget or invoking the \\fBconfigure\\fR widget\ncommand). If non-NULL, then information is returned only for this\noption. If NULL, then information is returned for all available\noptions.\n.AP Display *display in\nDisplay containing widget whose record is being freed; needed in\norder to free up resources.\n.BE\n.SH DESCRIPTION\n.PP\nNote that \\fBTk_ConfigureWidget\\fR should be replaced with the new\n\\fBTcl_Obj\\fR based API, \\fBTk_SetOptions\\fR. The old interface is\nretained for backward compatibility.\n.PP\n\\fBTk_ConfigureWidget\\fR is called to configure various aspects of a\nwidget, such as colors, fonts, border width, etc.\nIt is intended as a convenience procedure to reduce the amount\nof code that must be written in individual widget managers to\nhandle configuration information.\nIt is typically\ninvoked when widgets are created, and again when the \\fBconfigure\\fR\ncommand is invoked for a widget.\nAlthough intended primarily for widgets, \\fBTk_ConfigureWidget\\fR\ncan be used in other situations where \\fIobjc-objv\\fR information\nis to be used to fill in a record structure, such as configuring\ngraphical elements for a canvas widget or entries of a menu.\n.PP\n\\fBTk_ConfigureWidget\\fR processes\na table specifying the configuration options that are supported\n(\\fIspecs\\fR) and a collection of command-line arguments (\\fIobjc\\fR and\n\\fIobjv\\fR) to fill in fields of a record (\\fIwidgRec\\fR).\nIt uses the option database and defaults specified in \\fIspecs\\fR\nto fill in fields of \\fIwidgRec\\fR that are not specified in \\fIobjv\\fR.\n\\fBTk_ConfigureWidget\\fR normally returns the value \\fBTCL_OK\\fR; in this\ncase it does not modify \\fIinterp\\fR.\nIf an error\noccurs then \\fBTCL_ERROR\\fR is returned and \\fBTk_ConfigureWidget\\fR will\nleave an error message in interpreter \\fIinterp\\fR's result in the standard Tcl\nfashion.\nIn the event of an error return, some of the fields of \\fIwidgRec\\fR\ncould already have been set, if configuration information for them\nwas successfully processed before the error occurred.\nThe other fields will be set to reasonable initial values so that\n\\fBTk_FreeOptions\\fR can be called for cleanup.\n.PP\nThe \\fIspecs\\fR array specifies the kinds of configuration options\nexpected by the widget. Each of its entries specifies one configuration\noption and has the following structure:\n.CS\ntypedef struct {\n int \\fItype\\fR;\n const char *\\fIargvName\\fR;\n const char *\\fIdbName\\fR;\n const char *\\fIdbClass\\fR;\n const char *\\fIdefValue\\fR;\n Tcl_Size \\fIoffset\\fR;\n int \\fIspecFlags\\fR;\n const Tk_CustomOption *\\fIcustomPtr\\fR;\n} \\fBTk_ConfigSpec\\fR;\n.CE\nThe \\fItype\\fR field indicates what type of configuration option this is\n(e.g. \\fBTK_CONFIG_COLOR\\fR for a color value, or \\fBTK_CONFIG_INT\\fR for\nan integer value). The \\fItype\\fR field indicates how to use the\nvalue of the option (more on this below).\nThe \\fIargvName\\fR field is a string such as\n.QW \\-font\nor\n.QW \\-bg ,\nwhich is compared with the values in \\fIobjv\\fR (if \\fIargvName\\fR is\nNULL it means this is a grouped entry; see \\fBGROUPED ENTRIES\\fR below). The\n\\fIdbName\\fR and \\fIdbClass\\fR fields are used to look up a value\nfor this option in the option database. The \\fIdefValue\\fR field\nspecifies a default value for this configuration option if no\nvalue is specified in either \\fIobjv\\fR or the option database.\n\\fIOffset\\fR indicates where in \\fIwidgRec\\fR to store information\nabout this option, and \\fIspecFlags\\fR contains additional information\nto control the processing of this configuration option (see FLAGS\nbelow).\nThe last field, \\fIcustomPtr\\fR, is only used if \\fItype\\fR is\n\\fBTK_CONFIG_CUSTOM\\fR; see CUSTOM OPTION TYPES below.\n.PP\n\\fBTk_ConfigureWidget\\fR first processes \\fIobjv\\fR to see which\n(if any) configuration options are specified there. \\fIArgv\\fR\nmust contain an even number of fields; the first of each pair\nof fields must match the \\fIargvName\\fR of some entry in \\fIspecs\\fR\n(unique abbreviations are acceptable),\nand the second field of the pair contains the value for that\nconfiguration option. If there are entries in \\fIspec\\fR for which\nthere were no matching entries in \\fIobjv\\fR,\n\\fBTk_ConfigureWidget\\fR uses the \\fIdbName\\fR and \\fIdbClass\\fR\nfields of the \\fIspecs\\fR entry to probe the option database; if\na value is found, then it is used as the value for the option.\nFinally, if no entry is found in the option database, the\n\\fIdefValue\\fR field of the \\fIspecs\\fR entry is used as the\nvalue for the configuration option. If the \\fIdefValue\\fR is\nNULL, or if the \\fBTK_CONFIG_DONT_SET_DEFAULT\\fR bit is set in\n\\fIflags\\fR, then there is no default value and this \\fIspecs\\fR entry\nwill be ignored if no value is specified in \\fIobjv\\fR or the\noption database.\n.PP\nOnce a string value has been determined for a configuration option,\n\\fBTk_ConfigureWidget\\fR translates the string value into a more useful\nform, such as a color if \\fItype\\fR is \\fBTK_CONFIG_COLOR\\fR or an integer\nif \\fItype\\fR is \\fBTK_CONFIG_INT\\fR. This value is then stored in the\nrecord pointed to by \\fIwidgRec\\fR. This record is assumed to\ncontain information relevant to the manager of the widget; its exact\ntype is unknown to \\fBTk_ConfigureWidget\\fR. The \\fIoffset\\fR field\nof each \\fIspecs\\fR entry indicates where in \\fIwidgRec\\fR to store\nthe information about this configuration option. You should use the\n\\fBoffsetof\\fR macro to generate \\fIoffset\\fR values. The location\nindicated by \\fIwidgRec\\fR and \\fIoffset\\fR will be referred to as the\n.QW target\nin the descriptions below.\n.PP\nThe \\fItype\\fR field of each entry in \\fIspecs\\fR determines what\nto do with the string value of that configuration option. The\nlegal values for \\fItype\\fR, and the corresponding actions, are:\n.TP\n\\fBTK_CONFIG_ACTIVE_CURSOR\\fR\n.\nThe value\nmust be an ASCII string identifying a cursor in a form\nsuitable for passing to \\fBTk_GetCursor\\fR.\nThe value is converted to a \\fBTk_Cursor\\fR by calling\n\\fBTk_GetCursor\\fR and the result is stored in the target.\nIn addition, the resulting cursor is made the active cursor\nfor \\fItkwin\\fR by calling \\fBXDefineCursor\\fR.\nIf \\fBTK_CONFIG_NULL_OK\\fR is specified in \\fIspecFlags\\fR then the value\nmay be an empty string, in which case the target and \\fItkwin\\fR's\nactive cursor will be set to \\fBNone\\fR.\nIf the previous value of the target\nwas not \\fBNone\\fR, then it is freed by passing it to \\fBTk_FreeCursor\\fR.\n.TP\n\\fBTK_CONFIG_ANCHOR\\fR\n.\nThe value must be an ASCII string identifying an anchor point in one of the ways\naccepted by \\fBTk_GetAnchor\\fR.\nThe string is converted to a \\fBTk_Anchor\\fR by calling\n\\fBTk_GetAnchor\\fR and the result is stored in the target.\n.TP\n\\fBTK_CONFIG_BITMAP\\fR\n.\nThe value must be an ASCII string identifying a bitmap in a form\nsuitable for passing to \\fBTk_GetBitmap\\fR. The value is converted\nto a \\fBPixmap\\fR by calling \\fBTk_GetBitmap\\fR and the result\nis stored in the target.\nIf \\fBTK_CONFIG_NULL_OK\\fR is specified in \\fIspecFlags\\fR then the value\nmay be an empty string, in which case the target is set to \\fBNone\\fR.\nIf the previous value of the target\nwas not \\fBNone\\fR, then it is freed by passing it to \\fBTk_FreeBitmap\\fR.\n.TP\n\\fBTK_CONFIG_BOOLEAN\\fR\n.\nThe value must be an ASCII string specifying a boolean value. Any\nof the values\n.QW true ,\n.QW yes ,\n.QW on ,\nor\n.QW 1 ,\nor an abbreviation of one of these values, means true;\nany of the values\n.QW false ,\n.QW no ,\n.QW off ,\nor\n.QW 0 ,\nor an abbreviation of one of these values, means false.\nThe target is expected to be an integer; for true values it will\nbe set to 1 and for false values it will be set to 0.\n.TP\n\\fBTK_CONFIG_BORDER\\fR\n.\nThe value must be an ASCII string identifying a border color in a form\nsuitable for passing to \\fBTk_Get3DBorder\\fR. The value is converted\nto a (\\fBTk_3DBorder *\\fR) by calling \\fBTk_Get3DBorder\\fR and the result\nis stored in the target.\nIf \\fBTK_CONFIG_NULL_OK\\fR is specified in \\fIspecFlags\\fR then the value\nmay be an empty string, in which case the target will be set to NULL.\nIf the previous value of the target\nwas not NULL, then it is freed by passing it to \\fBTk_Free3DBorder\\fR.\n.TP\n\\fBTK_CONFIG_CAP_STYLE\\fR\n.\nThe value must be\nan ASCII string identifying a cap style in one of the ways\naccepted by \\fBTk_GetCapStyle\\fR.\nThe string is converted to an integer value corresponding\nto the cap style by calling\n\\fBTk_GetCapStyle\\fR and the result is stored in the target.\n.TP\n\\fBTK_CONFIG_COLOR\\fR\n.\nThe value must be an ASCII string identifying a color in a form\nsuitable for passing to \\fBTk_GetColor\\fR. The value is converted\nto an (\\fBXColor *\\fR) by calling \\fBTk_GetColor\\fR and the result\nis stored in the target.\nIf \\fBTK_CONFIG_NULL_OK\\fR is specified in \\fIspecFlags\\fR then the value\nmay be an empty string, in which case the target will be set to \\fBNone\\fR.\nIf the previous value of the target\nwas not NULL, then it is freed by passing it to \\fBTk_FreeColor\\fR.\n.TP\n\\fBTK_CONFIG_CURSOR\\fR\n.\nThis option is identical to \\fBTK_CONFIG_ACTIVE_CURSOR\\fR except\nthat the new cursor is not made the active one for \\fItkwin\\fR.\n.TP\n\\fBTK_CONFIG_CUSTOM\\fR\n.\nThis option allows applications to define new option types.\nThe \\fIcustomPtr\\fR field of the entry points to a structure\ndefining the new option type.\nSee the section \\fBCUSTOM OPTION TYPES\\fR below for details.\n.TP\n\\fBTK_CONFIG_DOUBLE\\fR\n.\nThe value must be an ASCII floating-point number in\nthe format accepted by \\fBstrtol\\fR. The string is converted\nto a \\fBdouble\\fR value, and the value is stored in the\ntarget.\n.TP\n\\fBTK_CONFIG_END\\fR\n.\nMarks the end of the table. The last entry in \\fIspecs\\fR\nmust have this type; all of its other fields are ignored and it\nwill never match any arguments.\n.TP\n\\fBTK_CONFIG_FONT\\fR\n.\nThe value must be an ASCII string identifying a font in a form\nsuitable for passing to \\fBTk_GetFont\\fR. The value is converted\nto a \\fBTk_Font\\fR by calling \\fBTk_GetFont\\fR and the result\nis stored in the target.\nIf \\fBTK_CONFIG_NULL_OK\\fR is specified in \\fIspecFlags\\fR then the value\nmay be an empty string, in which case the target will be set to NULL.\nIf the previous value of the target\nwas not NULL, then it is freed by passing it to \\fBTk_FreeFont\\fR.\n.TP\n\\fBTK_CONFIG_INT\\fR\n.\nThe value must be an ASCII integer string\nin the format accepted by \\fBstrtol\\fR (e.g.\n.QW 0\nand\n.QW 0x\nprefixes may be used to specify octal or hexadecimal\nnumbers, respectively). The string is converted to an integer\nvalue and the integer is stored in the target.\n.TP\n\\fBTK_CONFIG_JOIN_STYLE\\fR\n.\nThe value must be\nan ASCII string identifying a join style in one of the ways\naccepted by \\fBTk_GetJoinStyle\\fR.\nThe string is converted to an integer value corresponding\nto the join style by calling\n\\fBTk_GetJoinStyle\\fR and the result is stored in the target.\n.TP\n\\fBTK_CONFIG_JUSTIFY\\fR\n.\nThe value must be\nan ASCII string identifying a justification method in one of the\nways accepted by \\fBTk_GetJustify\\fR.\nThe string is converted to a \\fBTk_Justify\\fR by calling\n\\fBTk_GetJustify\\fR and the result is stored in the target.\n.TP\n\\fBTK_CONFIG_MM\\fR\n.\nThe value must specify a screen distance in one of the forms acceptable\nto \\fBTk_GetScreenMM\\fR.\nThe string is converted to double-precision floating-point distance\nin millimeters and the value is stored in the target.\n.TP\n\\fBTK_CONFIG_PIXELS\\fR\n.\nThe value must specify screen units in one of the forms acceptable\nto \\fBTk_GetPixels\\fR.\nThe string is converted to an integer distance in pixels and the\nvalue is stored in the target.\n.TP\n\\fBTK_CONFIG_RELIEF\\fR\n.\nThe value must be an ASCII string identifying a relief in a form\nsuitable for passing to \\fBTk_GetRelief\\fR. The value is converted\nto an integer relief value by calling \\fBTk_GetRelief\\fR and the result\nis stored in the target.\n.TP\n\\fBTK_CONFIG_STRING\\fR\n.\nA copy of the value is made by allocating memory space with\n\\fBTcl_Alloc\\fR and copying the value into the dynamically-allocated\nspace. A pointer to the new string is stored in the target.\nIf \\fBTK_CONFIG_NULL_OK\\fR is specified in \\fIspecFlags\\fR then the value\nmay be an empty string, in which case the target will be set to NULL.\nIf the previous value of the target was not NULL, then it is\nfreed by passing it to \\fBTcl_Free\\fR.\n.TP\n\\fBTK_CONFIG_SYNONYM\\fR\n.\nThis \\fItype\\fR value identifies special entries in \\fIspecs\\fR that\nare synonyms for other entries. If an \\fIobjv\\fR value matches the\n\\fIargvName\\fR of a \\fBTK_CONFIG_SYNONYM\\fR entry, the entry is not used\ndirectly. Instead, \\fBTk_ConfigureWidget\\fR searches \\fIspecs\\fR\nfor another entry whose \\fIargvName\\fR is the same as the \\fIdbName\\fR\nfield in the \\fBTK_CONFIG_SYNONYM\\fR entry; this new entry is used just\nas if its \\fIargvName\\fR had matched the \\fIobjv\\fR value. The\nsynonym mechanism allows multiple \\fIobjv\\fR values to be used for\na single configuration option, such as\n.QW \\-background\nand\n.QW \\-bg .\n.TP\n\\fBTK_CONFIG_UID\\fR\n.\nThe value is translated to a \\fBTk_Uid\\fR\n(by passing it to \\fBTk_GetUid\\fR). The resulting value\nis stored in the target.\nIf \\fBTK_CONFIG_NULL_OK\\fR is specified in \\fIspecFlags\\fR and the value\nis an empty string then the target will be set to NULL.\n.TP\n\\fBTK_CONFIG_WINDOW\\fR\n.\nThe value must be a window path name. It is translated to a\n\\fBTk_Window\\fR token and the token is stored in the target.\n.SH \"GROUPED ENTRIES\"\n.PP\nIn some cases it is useful to generate multiple resources from\na single configuration value. For example, a color name might\nbe used both to generate the background color for a widget (using\n\\fBTK_CONFIG_COLOR\\fR) and to generate a 3-D border to draw around the\nwidget (using \\fBTK_CONFIG_BORDER\\fR). In cases like this it is possible\nto specify that several consecutive entries in \\fIspecs\\fR are to\nbe treated as a group. The first entry is used to determine a value\n(using its \\fIargvName\\fR, \\fIdbName\\fR,\n\\fIdbClass\\fR, and \\fIdefValue\\fR fields). The value will be processed\nseveral times (one for each entry in the group), generating multiple\ndifferent resources and modifying multiple targets within \\fIwidgRec\\fR.\nEach of the entries after the first must have a NULL value in its\n\\fIargvName\\fR field; this indicates that the entry is to be grouped\nwith the entry that precedes it. Only the \\fItype\\fR and \\fIoffset\\fR\nfields are used from these follow-on entries.\n.SH \"FLAGS\"\n.PP\nThe \\fIflags\\fR argument passed to \\fBTk_ConfigureWidget\\fR is used\nin conjunction with the \\fIspecFlags\\fR fields in the entries of \\fIspecs\\fR\nto provide additional control over the processing of configuration\noptions. These values are used in three different ways as\ndescribed below.\n.PP\nFirst, if the \\fIflags\\fR argument to \\fBTk_ConfigureWidget\\fR has\nthe \\fBTK_CONFIG_ARGV_ONLY\\fR bit set\n(i.e., \\fIflags\\fR | \\fBTK_CONFIG_ARGV_ONLY\\fR != 0),\nthen the option database and\n\\fIdefValue\\fR fields are not used. In this case, if an entry in\n\\fIspecs\\fR does not match a field in \\fIobjv\\fR then nothing happens:\nthe corresponding target is not modified. This feature is useful\nwhen the goal is to modify certain configuration options while\nleaving others in their current state, such as when a \\fBconfigure\\fR\nwidget command is being processed.\n.PP\nSecond, the \\fIspecFlags\\fR field of an entry in \\fIspecs\\fR may be used\nto control the processing of that entry. Each \\fIspecFlags\\fR\nfield may consists of an OR-ed combination of the following values:\n.TP\n\\fBTK_CONFIG_COLOR_ONLY\\fR\n.\nIf this bit is set then the entry will only be considered if the\ndisplay for \\fItkwin\\fR has more than one bit plane. If the display\nis monochromatic then this \\fIspecs\\fR entry will be ignored.\n.TP\n\\fBTK_CONFIG_MONO_ONLY\\fR\n.\nIf this bit is set then the entry will only be considered if the\ndisplay for \\fItkwin\\fR has exactly one bit plane. If the display\nis not monochromatic then this \\fIspecs\\fR entry will be ignored.\n.TP\n\\fBTK_CONFIG_NULL_OK\\fR\n.\nThis bit is only relevant for some types of entries (see the\ndescriptions of the various entry types above).\nIf this bit is set, it indicates that an empty string value\nfor the field is acceptable and if it occurs then the\ntarget should be set to NULL or \\fBNone\\fR, depending\non the type of the target.\nThis flag is typically used to allow a\nfeature to be turned off entirely, e.g. set a cursor value to\n\\fBNone\\fR so that a window simply inherits its parent's cursor.\nIf this bit is not set then empty strings are processed as strings,\nwhich generally results in an error.\n.TP\n\\fBTK_CONFIG_DONT_SET_DEFAULT\\fR\n.\nIf this bit is one, it means that the \\fIdefValue\\fR field of the\nentry should only be used for returning the default value in\n\\fBTk_ConfigureInfo\\fR.\nIn calls to \\fBTk_ConfigureWidget\\fR no default will be supplied\nfor entries with this flag set; it is assumed that the\ncaller has already supplied a default value in the target location.\nThis flag provides a performance optimization where it is expensive\nto process the default string: the client can compute the default\nonce, save the value, and provide it before calling\n\\fBTk_ConfigureWidget\\fR.\n.PP\nThe \\fBTK_CONFIG_MONO_ONLY\\fR and \\fBTK_CONFIG_COLOR_ONLY\\fR flags are typically\nused to specify different default values for\nmonochrome and color displays. This is done by creating two\nentries in \\fIspecs\\fR that are identical except for their\n\\fIdefValue\\fR and \\fIspecFlags\\fR fields. One entry should have\nthe value \\fBTK_CONFIG_MONO_ONLY\\fR in its \\fIspecFlags\\fR and the\ndefault value for monochrome displays in its \\fIdefValue\\fR; the\nother entry should have the value \\fBTK_CONFIG_COLOR_ONLY\\fR in\nits \\fIspecFlags\\fR and the appropriate \\fIdefValue\\fR for\ncolor displays.\n.PP\nThird, it is possible to use \\fIflags\\fR and \\fIspecFlags\\fR\ntogether to selectively disable some entries. This feature is\nnot needed very often. It is useful in cases where several\nsimilar kinds of widgets are implemented in one place. It allows\na single \\fIspecs\\fR table to be created with all the configuration\noptions for all the widget types. When processing a particular\nwidget type, only entries relevant to that type will be used. This\neffect is achieved by setting the high-order bits (those in positions\nequal to or greater than \\fBTK_CONFIG_USER_BIT\\fR) in \\fIspecFlags\\fR\nvalues or in \\fIflags\\fR. In order for a particular entry in\n\\fIspecs\\fR to be used, its high-order bits must match exactly\nthe high-order bits of the \\fIflags\\fR value passed to\n\\fBTk_ConfigureWidget\\fR. If a \\fIspecs\\fR table is being used\nfor N different widget types, then N of the high-order bits will\nbe used. Each \\fIspecs\\fR entry will have one of more of those\nbits set in its \\fIspecFlags\\fR field to indicate the widget types\nfor which this entry is valid. When calling \\fBTk_ConfigureWidget\\fR,\n\\fIflags\\fR will have a single one of these bits set to select the\nentries for the desired widget type. For a working example of\nthis feature, see the code in tkButton.c.\n.SH TK_CONFIGUREINFO\n.PP\nThe \\fBTk_ConfigureInfo\\fR procedure may be used to obtain\ninformation about one or all of the options for a given widget.\nGiven a token for a window (\\fItkwin\\fR), a table describing the\nconfiguration options for a class of widgets (\\fIspecs\\fR), a\npointer to a widget record containing the current information for\na widget (\\fIwidgRec\\fR), and a NULL \\fIargvName\\fR argument,\n\\fBTk_ConfigureInfo\\fR generates a string describing all of the\nconfiguration options for the window. The string is placed\nin interpreter \\fIinterp\\fR's result. Under normal circumstances\nit returns \\fBTCL_OK\\fR; if an error occurs then it returns \\fBTCL_ERROR\\fR\nand the interpreter's result will contain an error message.\n.PP\nIf \\fIargvName\\fR is NULL, then the value left in\nthe interpreter's result by \\fBTk_ConfigureInfo\\fR\nconsists of a list of one or more entries, each of which describes\none configuration option (i.e. one entry in \\fIspecs\\fR). Each\nentry in the list will contain either two or five values. If the\ncorresponding entry in \\fIspecs\\fR has type \\fBTK_CONFIG_SYNONYM\\fR, then\nthe list will contain two values: the \\fIargvName\\fR for the entry\nand the \\fIdbName\\fR (synonym name). Otherwise the list will contain\nfive values: \\fIargvName\\fR, \\fIdbName\\fR, \\fIdbClass\\fR, \\fIdefValue\\fR,\nand current value. The current value is computed from the appropriate\nfield of \\fIwidgRec\\fR by calling procedures like \\fBTk_NameOfColor\\fR.\n.PP\nIf the \\fIargvName\\fR argument to \\fBTk_ConfigureInfo\\fR is non-NULL,\nthen it indicates a single option, and information is returned only\nfor that option. The string placed in the interpreter's result will be\na list containing two or five values as described above; this will\nbe identical to the corresponding sublist that would have been returned\nif \\fIargvName\\fR had been NULL.\n.PP\nThe \\fIflags\\fR argument to \\fBTk_ConfigureInfo\\fR is used to restrict\nthe \\fIspecs\\fR entries to consider, just as for \\fBTk_ConfigureWidget\\fR.\n.SH TK_CONFIGUREVALUE\n.PP\n\\fBTk_ConfigureValue\\fR takes arguments similar to \\fBTk_ConfigureInfo\\fR;\ninstead of returning a list of values, it just returns the current value\nof the option given by \\fIargvName\\fR (\\fIargvName\\fR must not be NULL).\nThe value is returned in interpreter \\fIinterp\\fR's result and \\fBTCL_OK\\fR is\nnormally returned as the procedure's result.\nIf an error occurs in \\fBTk_ConfigureValue\\fR (e.g., \\fIargvName\\fR is\nnot a valid option name), \\fBTCL_ERROR\\fR is returned and an error message\nis left in the interpreter's result.\nThis procedure is typically called to implement \\fBcget\\fR widget\ncommands.\n.SH TK_FREEOPTIONS\n.PP\nThe \\fBTk_FreeOptions\\fR procedure may be invoked during widget cleanup\nto release all of the resources associated with configuration options.\nIt scans through \\fIspecs\\fR and for each entry corresponding to a\nresource that must be explicitly freed (e.g. those with\ntype \\fBTK_CONFIG_COLOR\\fR), it frees the resource in the widget record.\nIf the field in the widget record does not refer to a resource (e.g.\nit contains a null pointer) then no resource is freed for that\nentry.\nAfter freeing a resource, \\fBTk_FreeOptions\\fR sets the\ncorresponding field of the widget record to null.\n.SH \"CUSTOM OPTION TYPES\"\n.PP\nApplications can extend the built-in configuration types with additional\nconfiguration types by writing procedures to parse and print options\nof the a type and creating a structure pointing to those procedures:\n.CS\ntypedef struct {\n Tk_OptionParseProc *\\fIparseProc\\fR;\n Tk_OptionPrintProc *\\fIprintProc\\fR;\n void *\\fIclientData\\fR;\n} \\fBTk_CustomOption\\fR;\n\ntypedef int \\fBTk_OptionParseProc\\fR(\n void *\\fIclientData\\fR,\n Tcl_Interp *\\fIinterp\\fR,\n Tk_Window \\fItkwin\\fR,\n const char *\\fIvalue\\fR,\n char *\\fIwidgRec\\fR,\n Tcl_Size \\fIoffset\\fR);\n\ntypedef const char *\\fBTk_OptionPrintProc\\fR(\n void *\\fIclientData\\fR,\n Tk_Window \\fItkwin\\fR,\n char *\\fIwidgRec\\fR,\n Tcl_Size \\fIoffset\\fR,\n Tcl_FreeProc **\\fIfreeProcPtr\\fR);\n.CE\nThe Tk_CustomOption structure contains three fields, which are pointers\nto the two procedures and a \\fIclientData\\fR value to be passed to those\nprocedures when they are invoked. The \\fIclientData\\fR value typically\npoints to a structure containing information that is needed by the\nprocedures when they are parsing and printing options.\n.PP\nThe \\fIparseProc\\fR procedure is invoked by\n\\fBTk_ConfigureWidget\\fR to parse a string and store the resulting\nvalue in the widget record.\nThe \\fIclientData\\fR argument is a copy of the \\fIclientData\\fR\nfield in the Tk_CustomOption structure.\nThe \\fIinterp\\fR argument points to a Tcl interpreter used for\nerror reporting. \\fITkwin\\fR is a copy of the \\fItkwin\\fR argument\nto \\fBTk_ConfigureWidget\\fR. The \\fIvalue\\fR argument is a string\ndescribing the value for the option; it could have been specified\nexplicitly in the call to \\fBTk_ConfigureWidget\\fR or it could\ncome from the option database or a default.\n\\fIValue\\fR will never be a null pointer but it may point to\nan empty string.\n\\fIRecordPtr\\fR is the same as the \\fIwidgRec\\fR argument to\n\\fBTk_ConfigureWidget\\fR; it points to the start of the widget\nrecord to modify.\nThe last argument, \\fIoffset\\fR, gives the offset in bytes from the start\nof the widget record to the location where the option value is to\nbe placed. The procedure should translate the string to whatever\nform is appropriate for the option and store the value in the widget\nrecord. It should normally return \\fBTCL_OK\\fR, but if an error occurs\nin translating the string to a value then it should return \\fBTCL_ERROR\\fR\nand store an error message in interpreter \\fIinterp\\fR's result.\n.PP\nThe \\fIprintProc\\fR procedure is called\nby \\fBTk_ConfigureInfo\\fR to produce a string value describing an\nexisting option.\nIts \\fIclientData\\fR, \\fItkwin\\fR, \\fIwidgRec\\fR, and \\fIoffset\\fR\narguments all have the same meaning as for Tk_OptionParseProc\nprocedures.\nThe \\fIprintProc\\fR procedure should examine the option whose value\nis stored at \\fIoffset\\fR in \\fIwidgRec\\fR, produce a string describing\nthat option, and return a pointer to the string.\nIf the string is stored in dynamically-allocated memory, then\nthe procedure must set \\fI*freeProcPtr\\fR to the address of\na procedure to call to free the string's memory; \\fBTk_ConfigureInfo\\fR\nwill call this procedure when it is finished with the string.\nIf the result string is stored in static memory then \\fIprintProc\\fR\nneed not do anything with the \\fIfreeProcPtr\\fR argument.\n.PP\nOnce \\fIparseProc\\fR and \\fIprintProc\\fR have been defined and a\nTk_CustomOption structure has been created for them, options of this\nnew type may be manipulated with Tk_ConfigSpec entries whose \\fItype\\fR\nfields are \\fBTK_CONFIG_CUSTOM\\fR and whose \\fIcustomPtr\\fR fields point\nto the Tk_CustomOption structure.\n.SH EXAMPLES\n.PP\nAlthough the explanation of \\fBTk_ConfigureWidget\\fR is fairly\ncomplicated, its actual use is pretty straightforward.\nThe easiest way to get started is to copy the code\nfrom an existing widget.\nThe library implementation of frames\n(tkFrame.c) has a simple configuration table, and the library\nimplementation of buttons (tkButton.c) has a much more complex\ntable that uses many of the fancy \\fIspecFlags\\fR mechanisms.\n.SH \"SEE ALSO\"\nTk_SetOptions(3)\n.SH KEYWORDS\nanchor, bitmap, boolean, border, cap style, color, configuration options,\ncursor, custom, double, font, integer, join style, justify, millimeters,\npixels, relief, synonym, uid\n" }, { "path": "doc/ConfigWind.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1993 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_ConfigureWindow 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor \\- change window configuration or attributes\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_ConfigureWindow\\fR(\\fItkwin, valueMask, valuePtr\\fR)\n.sp\n\\fBTk_MoveWindow\\fR(\\fItkwin, x, y\\fR)\n.sp\n\\fBTk_ResizeWindow\\fR(\\fItkwin, width, height\\fR)\n.sp\n\\fBTk_MoveResizeWindow\\fR(\\fItkwin, x, y, width, height\\fR)\n.sp\n\\fBTk_SetWindowBorderWidth\\fR(\\fItkwin, borderWidth\\fR)\n.sp\n\\fBTk_ChangeWindowAttributes\\fR(\\fItkwin, valueMask, attsPtr\\fR)\n.sp\n\\fBTk_SetWindowBackground\\fR(\\fItkwin, pixel\\fR)\n.sp\n\\fBTk_SetWindowBackgroundPixmap\\fR(\\fItkwin, pixmap\\fR)\n.sp\n\\fBTk_SetWindowBorder\\fR(\\fItkwin, pixel\\fR)\n.sp\n\\fBTk_SetWindowBorderPixmap\\fR(\\fItkwin, pixmap\\fR)\n.sp\n\\fBTk_SetWindowColormap\\fR(\\fItkwin, colormap\\fR)\n.sp\n\\fBTk_DefineCursor\\fR(\\fItkwin, cursor\\fR)\n.sp\n\\fBTk_UndefineCursor\\fR(\\fItkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AS XSetWindowAttributes borderWidth\n.AP Tk_Window tkwin in\nToken for window.\n.AP \"unsigned int\" valueMask in\nOR-ed mask of values like \\fBCWX\\fR or \\fBCWBorderPixel\\fR,\nindicating which fields of \\fI*valuePtr\\fR or \\fI*attsPtr\\fR to use.\n.AP XWindowChanges *valuePtr in\nPoints to a structure containing new values for the configuration\nparameters selected by \\fIvalueMask\\fR. Fields not selected\nby \\fIvalueMask\\fR are ignored.\n.AP int x in\nNew x-coordinate for \\fItkwin\\fR's top left pixel (including\nborder, if any) within tkwin's parent.\n.AP int y in\nNew y-coordinate for \\fItkwin\\fR's top left pixel (including\nborder, if any) within tkwin's parent.\n.AP \"int\" width in\nNew width for \\fItkwin\\fR (interior, not including border).\n.AP \"int\" height in\nNew height for \\fItkwin\\fR (interior, not including border).\n.AP \"int\" borderWidth in\nNew width for \\fItkwin\\fR's border.\n.AP XSetWindowAttributes *attsPtr in\nPoints to a structure containing new values for the attributes\ngiven by the \\fIvalueMask\\fR argument. Attributes not selected\nby \\fIvalueMask\\fR are ignored.\n.AP \"unsigned long\" pixel in\nNew background or border color for window.\n.AP Pixmap pixmap in\nNew pixmap to use for background or border of \\fItkwin\\fR. WARNING:\ncannot necessarily be deleted immediately, as for Xlib calls. See\nnote below.\n.AP Colormap colormap in\nNew colormap to use for \\fItkwin\\fR.\n.AP Tk_Cursor cursor in\nNew cursor to use for \\fItkwin\\fR. If \\fBNone\\fR is specified, then\n\\fItkwin\\fR will not have its own cursor; it will use the cursor\nof its parent.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures are analogous to the X library procedures\nwith similar names, such as \\fBXConfigureWindow\\fR. Each\none of the above procedures calls the corresponding X procedure\nand also saves the configuration information in Tk's local\nstructure for the window. This allows the information to\nbe retrieved quickly by the application (using macros such\nas \\fBTk_X\\fR and \\fBTk_Height\\fR) without having to contact\nthe X server. In addition, if no X window has actually been\ncreated for \\fItkwin\\fR yet, these procedures do not issue\nX operations or cause event handlers to be invoked; they save\nthe information in Tk's local\nstructure for the window; when the window is created later,\nthe saved information will be used to configure the window.\n.PP\nSee the X library documentation for details on what these\nprocedures do and how they use their arguments.\n.PP\nIn the procedures \\fBTk_ConfigureWindow\\fR, \\fBTk_MoveWindow\\fR,\n\\fBTk_ResizeWindow\\fR, \\fBTk_MoveResizeWindow\\fR, and\n\\fBTk_SetWindowBorderWidth\\fR,\nif \\fItkwin\\fR is an internal window then event handlers interested\nin configure events are invoked immediately, before the procedure\nreturns. If \\fItkwin\\fR is a top-level window\nthen the event handlers will be invoked later, after X has seen\nthe request and returned an event for it.\n.PP\nApplications using Tk should never call procedures like\n\\fBXConfigureWindow\\fR directly; they should always use the\ncorresponding Tk procedures.\n.PP\nThe size and location of a window should only be modified by the\nappropriate geometry manager for that window and never by a window\nitself (but see \\fBTk_MoveToplevelWindow\\fR for moving a top-level\nwindow).\n.PP\nYou may not use \\fBTk_ConfigureWindow\\fR to change the\nstacking order of a window (\\fIvalueMask\\fR may not contain the\n\\fBCWSibling\\fR or \\fBCWStackMode\\fR bits).\nTo change the stacking order, use the procedure \\fBTk_RestackWindow\\fR.\n.PP\nThe procedure \\fBTk_SetWindowColormap\\fR will automatically add\n\\fItkwin\\fR to the \\fBTK_COLORMAP_WINDOWS\\fR property of its\nnearest top-level ancestor if the new colormap is different from\nthat of \\fItkwin\\fR's parent and \\fItkwin\\fR is not already in\nthe \\fBTK_COLORMAP_WINDOWS\\fR property.\n.SH BUGS\n.PP\n\\fBTk_SetWindowBackgroundPixmap\\fR and \\fBTk_SetWindowBorderPixmap\\fR\ndiffer slightly from their Xlib counterparts in that the \\fIpixmap\\fR\nargument may not necessarily be deleted immediately after calling\none of these procedures. This is because \\fItkwin\\fR's window\nmay not exist yet at the time of the call, in which case \\fIpixmap\\fR\nis merely saved and used later when \\fItkwin\\fR's window is actually\ncreated. If you wish to delete \\fIpixmap\\fR, then call\n\\fBTk_MakeWindowExist\\fR first to be sure that \\fItkwin\\fR's window exists\nand \\fIpixmap\\fR has been passed to the X server.\n.PP\nA similar problem occurs for the \\fIcursor\\fR argument passed to\n\\fBTk_DefineCursor\\fR. The solution is the same as for pixmaps above:\ncall \\fBTk_MakeWindowExist\\fR before freeing the cursor.\n.SH \"SEE ALSO\"\nTk_MoveToplevelWindow, Tk_RestackWindow\n.SH KEYWORDS\nattributes, border, color, configure, height, pixel, pixmap, width, window, x, y\n" }, { "path": "doc/CoordToWin.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1993 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CoordsToWindow 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CoordsToWindow \\- Find window containing a point\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Window\n\\fBTk_CoordsToWindow\\fR(\\fIrootX, rootY, tkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window tkwin\n.AP int rootX in\nX-coordinate (in root window coordinates).\n.AP int rootY in\nY-coordinate (in root window coordinates).\n.AP Tk_Window tkwin in\nToken for window that identifies application.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_CoordsToWindow\\fR locates the window that contains a given point.\nThe point is specified in root coordinates with \\fIrootX\\fR and\n\\fIrootY\\fR (if a virtual-root window manager is in use then\n\\fIrootX\\fR and \\fIrootY\\fR are in the coordinate system of the\nvirtual root window).\nThe return value from the procedure is a token for the window that\ncontains the given point.\nIf the point is not in any window, or if the containing window\nis not in the same application as \\fItkwin\\fR, then NULL is\nreturned.\n.PP\nThe containing window is decided using the same rules that determine\nwhich window contains the mouse cursor: if a parent and a child both\ncontain the point then the child gets preference, and if two siblings\nboth contain the point then the highest one in the stacking order\n(i.e. the one that's visible on the screen) gets preference.\n.SH KEYWORDS\ncontaining, coordinates, root window\n" }, { "path": "doc/CrtCmHdlr.3", "content": "'\\\"\n'\\\" Copyright (c) 2000 Ajuba Solutions.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CreateClientMessageHandler 3 \"8.4\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreateClientMessageHandler, Tk_DeleteClientMessageHandler \\- associate procedure callback with ClientMessage type X events\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_CreateClientMessageHandler\\fR(\\fIproc\\fR)\n.sp\n\\fBTk_DeleteClientMessageHandler\\fR(\\fIproc\\fR)\n.fi\n.SH ARGUMENTS\n.AP Tk_ClientMessageProc *proc in\nProcedure to invoke whenever a ClientMessage X event occurs on any display.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_CreateClientMessageHandler\\fR arranges for \\fIproc\\fR to be invoked\nin the future whenever a ClientMessage X event occurs that is not handled by\n\\fBWM_PROTOCOL\\fR. \\fBTk_CreateClientMessageHandler\\fR is intended for use\nby applications which need to watch X ClientMessage events, such as drag and\ndrop applications.\n.PP\nThe callback to \\fIproc\\fR will be made by \\fBTk_HandleEvent\\fR;\nthis mechanism only works in programs that dispatch events\nthrough \\fBTk_HandleEvent\\fR (or through other Tk procedures that\ncall \\fBTk_HandleEvent\\fR, such as \\fBTcl_DoOneEvent\\fR or\n\\fBTk_MainLoop\\fR).\n.PP\n\\fIProc\\fR should have arguments and result that match the\ntype \\fBTk_ClientMessageProc\\fR:\n.CS\ntypedef int \\fBTk_ClientMessageProc\\fR(\n Tk_Window \\fItkwin\\fR,\n XEvent *\\fIeventPtr\\fR);\n.CE\nThe \\fItkwin\\fR parameter to \\fIproc\\fR is the Tk window which is\nassociated with this event. \\fIEventPtr\\fR is a pointer to the X event.\n.PP\nWhenever an X ClientMessage event is processed by \\fBTk_HandleEvent\\fR,\nthe \\fIproc\\fR is called if it was not handled as a \\fBWM_PROTOCOL\\fR.\nThe return value from \\fIproc\\fR is normally 0.\nA non-zero return value indicates that the event is not to be handled\nfurther; that is, \\fIproc\\fR has done all processing that is to be\nallowed for the event.\n.PP\nIf there are multiple ClientMessage event handlers, each one is called\nfor each event, in the order in which they were established.\n.PP\n\\fBTk_DeleteClientMessageHandler\\fR may be called to delete a\npreviously-created ClientMessage event handler: it deletes each handler it\nfinds that matches the \\fIproc\\fR argument. If no such handler exists,\nthen \\fBTk_DeleteClientMessageHandler\\fR returns without doing anything.\nAlthough Tk supports it, it's probably a bad idea to have more than one\ncallback with the same \\fIproc\\fR argument.\n.SH KEYWORDS\nbind, callback, event, handler\n" }, { "path": "doc/CrtConsoleChan.3", "content": "'\\\"\n'\\\" Copyright (c) 2007 ActiveState Software Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_InitConsoleChannels 3 8.5 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_InitConsoleChannels \\- Install the console channels as standard channels\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_InitConsoleChannels\\fR(\\fIinterp\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tcl_Interp *interp in\n.AP Tcl_Interp *interp in\nInterpreter in which the console channels are created.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_InitConsoleChannels\\fR is invoked to create a set of console\nchannels and install them as the standard channels. All I/O on these\nchannels will be discarded until \\fBTk_CreateConsoleWindow\\fR is\ncalled to attach the console to a text widget.\n.PP\nThis function is for use by shell applications based on Tk, like\n\\fBwish\\fR, on platforms which have no standard channels in graphical\nmode, like Win32.\n.PP\nThe \\fIinterp\\fR argument is the interpreter in which to create and\ninstall the console channels.\n.PP\n\\fBNOTE:\\fR If this function is used it has to be called before the\nfirst call to \\fBTcl_RegisterChannel\\fR, directly, or indirectly\nthrough other channel functions. Because otherwise the standard\nchannels will be already initialized to the system defaults, which will\nbe nonsensical for the case \\fBTk_InitConsoleChannels\\fR is for.\n.SH \"SEE ALSO\"\nconsole(n)\n.SH KEYWORDS\nstandard channels, console\n" }, { "path": "doc/CrtErrHdlr.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CreateErrorHandler 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreateErrorHandler, Tk_DeleteErrorHandler \\- handle X protocol errors\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_ErrorHandler\n\\fBTk_CreateErrorHandler\\fR(\\fIdisplay, error, request, minor, proc, clientData\\fR)\n.sp\n\\fBTk_DeleteErrorHandler\\fR(\\fIhandler\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tk_ErrorHandler\" clientData\n.AP Display *display in\nDisplay whose errors are to be handled.\n.AP int error in\nMatch only error events with this value in the \\fIerror_code\\fR\nfield. If \\-1, then match any \\fIerror_code\\fR value.\n.AP int request in\nMatch only error events with this value in the \\fIrequest_code\\fR\nfield. If \\-1, then match any \\fIrequest_code\\fR value.\n.AP int minor in\nMatch only error events with this value in the \\fIminor_code\\fR\nfield. If \\-1, then match any \\fIminor_code\\fR value.\n.AP Tk_ErrorProc *proc in\nProcedure to invoke whenever an error event is received for\n\\fIdisplay\\fR and matches \\fIerror\\fR, \\fIrequest\\fR, and \\fIminor\\fR.\nNULL means ignore any matching errors.\n.AP void *clientData in\nArbitrary one-word value to pass to \\fIproc\\fR.\n.AP Tk_ErrorHandler handler in\nToken for error handler to delete (return value from a previous\ncall to \\fBTk_CreateErrorHandler\\fR).\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_CreateErrorHandler\\fR arranges for a particular procedure\n(\\fIproc\\fR) to be called whenever certain protocol errors occur on a\nparticular display (\\fIdisplay\\fR). Protocol errors occur when\nthe X protocol is used incorrectly, such as attempting to map a window\nthat does not exist. See the Xlib documentation for \\fBXSetErrorHandler\\fR\nfor more information on the kinds of errors that can occur.\nFor \\fIproc\\fR to be invoked\nto handle a particular error, five things must occur:\n.IP [1]\nThe error must pertain to \\fIdisplay\\fR.\n.IP [2]\nEither the \\fIerror\\fR argument to \\fBTk_CreateErrorHandler\\fR\nmust have been \\-1, or the \\fIerror\\fR argument must match\nthe \\fIerror_code\\fR field from the error event.\n.IP [3]\nEither the \\fIrequest\\fR argument to \\fBTk_CreateErrorHandler\\fR\nmust have been \\-1, or the \\fIrequest\\fR argument must match\nthe \\fIrequest_code\\fR field from the error event.\n.IP [4]\nEither the \\fIminor\\fR argument to \\fBTk_CreateErrorHandler\\fR\nmust have been \\-1, or the \\fIminor\\fR argument must match\nthe \\fIminor_code\\fR field from the error event.\n.IP [5]\nThe protocol request to which the error pertains must have been\nmade when the handler was active (see below for more information).\n.PP\n\\fIProc\\fR should have arguments and result that match the\nfollowing type:\n.CS\ntypedef int \\fBTk_ErrorProc\\fR(\n void *\\fIclientData\\fR,\n XErrorEvent *\\fIerrEventPtr\\fR);\n.CE\nThe \\fIclientData\\fR parameter to \\fIproc\\fR is a copy of the \\fIclientData\\fR\nargument given to \\fBTcl_CreateErrorHandler\\fR when the callback\nwas created. Typically, \\fIclientData\\fR points to a data\nstructure containing application-specific information that is\nneeded to deal with the error. \\fIErrEventPtr\\fR is\na pointer to the X error event.\nThe procedure \\fIproc\\fR should return an integer value. If it\nreturns 0 it means that \\fIproc\\fR handled the error completely and there\nis no need to take any other action for the error. If it returns\nnon-zero it means \\fIproc\\fR was unable to handle the error.\n.PP\nIf a value of NULL is specified for \\fIproc\\fR, all matching errors\nwill be ignored: this will produce the same result as if a procedure\nhad been specified that always returns 0.\n.PP\nIf more than more than one handler matches a particular error, then\nthey are invoked in turn. The handlers will be invoked in reverse\norder of creation: most recently declared handler first.\nIf any handler returns 0, then subsequent (older) handlers will\nnot be invoked. If no handler returns 0, then Tk invokes X's\ndefault error handler, which prints an error message and aborts the\nprogram. If you wish to have a default handler that deals with errors\nthat no other handler can deal with, then declare it first.\n.PP\nThe X documentation states that\n.QW \"the error handler should not call any functions (directly or indirectly) on the display that will generate protocol requests or that will look for input events.\"\nThis restriction applies to handlers declared by \\fBTk_CreateErrorHandler\\fR;\ndisobey it at your own risk.\n.PP\n\\fBTk_DeleteErrorHandler\\fR may be called to delete a\npreviously-created error handler. The \\fIhandler\\fR argument\nidentifies the error handler, and should be a value returned by\na previous call to \\fBTk_CreateEventHandler\\fR.\n.PP\nA particular error handler applies to errors resulting\nfrom protocol requests generated between\nthe call to \\fBTk_CreateErrorHandler\\fR and the call to\n\\fBTk_DeleteErrorHandler\\fR. However, the actual callback\nto \\fIproc\\fR may not occur until after the \\fBTk_DeleteErrorHandler\\fR\ncall, due to buffering in the client and server.\nIf an error event pertains to\na protocol request made just before calling \\fBTk_DeleteErrorHandler\\fR,\nthen the error event may not have been processed\nbefore the \\fBTk_DeleteErrorHandler\\fR\ncall. When this situation arises, Tk will save information about\nthe handler and\ninvoke the handler's \\fIproc\\fR later when the error event\nfinally arrives.\nIf an application wishes to delete an error handler and know\nfor certain that all relevant errors have been processed,\nit should first call \\fBTk_DeleteErrorHandler\\fR and then\ncall \\fBXSync\\fR; this will flush out any buffered requests and errors,\nbut will result in a performance penalty because\nit requires communication to and from the X server. After the\n\\fBXSync\\fR call Tk is guaranteed not to call any error\nhandlers deleted before the \\fBXSync\\fR call.\n.PP\nFor the Tk error handling mechanism to work properly, it is essential\nthat application code never calls \\fBXSetErrorHandler\\fR directly;\napplications should use only \\fBTk_CreateErrorHandler\\fR.\n.SH KEYWORDS\ncallback, error, event, handler\n" }, { "path": "doc/CrtGenHdlr.3", "content": "'\\\"\n'\\\" Copyright (c) 1992-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CreateGenericHandler 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreateGenericHandler, Tk_DeleteGenericHandler \\- associate procedure callback with all X events\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_CreateGenericHandler\\fR(\\fIproc, clientData\\fR)\n.sp\n\\fBTk_DeleteGenericHandler\\fR(\\fIproc, clientData\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tk_GenericProc\" clientData\n.AP Tk_GenericProc *proc in\nProcedure to invoke whenever any X event occurs on any display.\n.AP void *clientData in\nArbitrary one-word value to pass to \\fIproc\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_CreateGenericHandler\\fR arranges for \\fIproc\\fR to be\ninvoked in the future whenever any X event occurs. This mechanism is\n\\fInot\\fR intended for dispatching X events on windows managed by Tk\n(you should use \\fBTk_CreateEventHandler\\fR for this purpose).\n\\fBTk_CreateGenericHandler\\fR is intended for other purposes, such\nas tracing X events, monitoring events on windows not owned by Tk,\naccessing X-related libraries that were not originally designed for\nuse with Tk, and so on.\n.PP\nThe callback to \\fIproc\\fR will be made by \\fBTk_HandleEvent\\fR;\nthis mechanism only works in programs that dispatch events\nthrough \\fBTk_HandleEvent\\fR (or through other Tk procedures that\ncall \\fBTk_HandleEvent\\fR, such as \\fBTcl_DoOneEvent\\fR or\n\\fBTk_MainLoop\\fR).\n.PP\n\\fIProc\\fR should have arguments and result that match the\ntype \\fBTk_GenericProc\\fR:\n.CS\ntypedef int \\fBTk_GenericProc\\fR(\n void *\\fIclientData\\fR,\n XEvent *\\fIeventPtr\\fR);\n.CE\nThe \\fIclientData\\fR parameter to \\fIproc\\fR is a copy of the \\fIclientData\\fR\nargument given to \\fBTk_CreateGenericHandler\\fR when the callback\nwas created. Typically, \\fIclientData\\fR points to a data\nstructure containing application-specific information about\nhow to handle events.\n\\fIEventPtr\\fR is a pointer to the X event.\n.PP\nWhenever an X event is processed by \\fBTk_HandleEvent\\fR, \\fIproc\\fR\nis called. The return value from \\fIproc\\fR is normally 0.\nA non-zero return value indicates that the event is not to be handled\nfurther; that is, \\fIproc\\fR has done all processing that is to be\nallowed for the event.\n.PP\nIf there are multiple generic event handlers, each one is called\nfor each event, in the order in which they were established.\n.PP\n\\fBTk_DeleteGenericHandler\\fR may be called to delete a\npreviously-created generic event handler: it deletes each handler\nit finds that matches the \\fIproc\\fR and \\fIclientData\\fR arguments. If\nno such handler exists, then \\fBTk_DeleteGenericHandler\\fR returns\nwithout doing anything. Although Tk supports it, it's probably\na bad idea to have more than one callback with the same\n\\fIproc\\fR and \\fIclientData\\fR arguments.\n.PP\nEstablishing a generic event handler does nothing to ensure that the\nprocess will actually receive the X events that the handler wants to\nprocess.\nFor example, it is the caller's responsibility to invoke\n\\fBXSelectInput\\fR to select the desired events, if that is necessary.\n.SH KEYWORDS\nbind, callback, event, handler\n" }, { "path": "doc/CrtImgType.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1997 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CreateImageType 3 8.5 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreateImageType, Tk_GetImageModelData \\- define new kind of image\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_CreateImageType\\fR(\\fItypePtr\\fR)\n.sp\nvoid *\n\\fBTk_GetImageModelData\\fR(\\fIinterp, name, typePtrPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"const Tk_ImageType\" *typePtrPtr\n.AP \"const Tk_ImageType\" *typePtr in\nStructure that defines the new type of image.\nFor Tk 8.4 and earlier this must be static: a\npointer to this structure is retained by the image code.\nIn Tk 8.5, this limitation was relaxed.\n.AP Tcl_Interp *interp in\nInterpreter in which image was created.\n.AP \"const char\" *name in\nName of existing image.\n.AP Tk_ImageType **typePtrPtr out\nPoints to word in which to store a pointer to type information for\nthe given image, if it exists.\n.AP char ***argvPtr in/out\nPointer to argument list\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_CreateImageType\\fR is invoked to define a new kind of image.\nAn image type corresponds to a particular value of the \\fItype\\fR\nargument for the \\fBimage create\\fR command. There may exist\nany number of different image types, and new types may be defined\ndynamically by calling \\fBTk_CreateImageType\\fR.\nFor example, there might be one type for 2-color bitmaps,\nanother for multi-color images, another for dithered images,\nanother for video, and so on.\n.PP\nThe code that implements a new image type is called an\n\\fIimage manager\\fR.\nIt consists of a collection of procedures plus three different\nkinds of data structures.\nThe first data structure is a Tk_ImageType structure, which contains\nthe name of the image type and pointers to five procedures provided\nby the image manager to deal with images of this type:\n.CS\ntypedef struct {\n const char *\\fIname\\fR;\n Tk_ImageCreateProc *\\fIcreateProc\\fR;\n Tk_ImageGetProc *\\fIgetProc\\fR;\n Tk_ImageDisplayProc *\\fIdisplayProc\\fR;\n Tk_ImageFreeProc *\\fIfreeProc\\fR;\n Tk_ImageDeleteProc *\\fIdeleteProc\\fR;\n} \\fBTk_ImageType\\fR;\n.CE\nThe fields of this structure will be described in later subsections\nof this entry.\n.PP\nThe second major data structure manipulated by an image manager\nis called an \\fIimage model\\fR; it contains overall information\nabout a particular image, such as the values of the configuration\noptions specified in an \\fBimage create\\fR command.\nThere will usually be one of these structures for each\ninvocation of the \\fBimage create\\fR command.\n.PP\nThe third data structure related to images is an \\fIimage instance\\fR.\nThere will usually be one of these structures for each usage of an\nimage in a particular widget.\nIt is possible for a single image to appear simultaneously\nin multiple widgets, or even multiple times in the same widget.\nFurthermore, different instances may be on different screens\nor displays.\nThe image instance data structure describes things that may\nvary from instance to instance, such as colors and graphics\ncontexts for redisplay.\nThere is usually one instance structure for each \\fB\\-image\\fR\noption specified for a widget or canvas item.\n.PP\nThe following subsections describe the fields of a Tk_ImageType\nin more detail.\n.SS NAME\n.PP\n\\fItypePtr->name\\fR provides a name for the image type.\nOnce \\fBTk_CreateImageType\\fR returns, this name may be used\nin \\fBimage create\\fR commands to create images of the new\ntype.\nIf there already existed an image type by this name then\nthe new image type replaces the old one.\n.SS CREATEPROC\n.PP\n\\fItypePtr->createProc\\fR provides the address of a procedure for\nTk to call whenever \\fBimage create\\fR is invoked to create\nan image of the new type.\n\\fItypePtr->createProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageCreateProc\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n const char *\\fIname\\fR,\n int \\fIobjc\\fR,\n Tcl_Obj *const *\\fIobjv\\fR,\n const Tk_ImageType *\\fItypePtr\\fR,\n Tk_ImageModel \\fImodel\\fR,\n void **\\fImodelDataPtr\\fR);\n.CE\nThe \\fIinterp\\fR argument is the interpreter in which the \\fBimage\\fR\ncommand was invoked, and \\fIname\\fR is the name for the new image,\nwhich was either specified explicitly in the \\fBimage\\fR command\nor generated automatically by the \\fBimage\\fR command.\nThe \\fIobjc\\fR and \\fIobjv\\fR arguments describe all the configuration\noptions for the new image (everything after the name argument to\n\\fBimage\\fR).\nThe \\fImodel\\fR argument is a token that refers to Tk's information\nabout this image; the image manager must return this token to\nTk when invoking the \\fBTk_ImageChanged\\fR procedure.\nTypically \\fIcreateProc\\fR will parse \\fIobjc\\fR and \\fIobjv\\fR\nand create an image model data structure for the new image.\n\\fIcreateProc\\fR may store an arbitrary one-word value at\n*\\fImodelDataPtr\\fR, which will be passed back to the\nimage manager when other callbacks are invoked.\nTypically the value is a pointer to the model data\nstructure for the image.\n.PP\nIf \\fIcreateProc\\fR encounters an error, it should leave an error\nmessage in the interpreter result and return \\fBTCL_ERROR\\fR; otherwise\nit should return \\fBTCL_OK\\fR.\n.PP\n\\fIcreateProc\\fR should call \\fBTk_ImageChanged\\fR in order to set the\nsize of the image and request an initial redisplay.\n.SS GETPROC\n.PP\n\\fItypePtr->getProc\\fR is invoked by Tk whenever a widget\ncalls \\fBTk_GetImage\\fR to use a particular image.\nThis procedure must match the following prototype:\n.CS\ntypedef void *\\fBTk_ImageGetProc\\fR(\n Tk_Window \\fItkwin\\fR,\n void *\\fImodelData\\fR);\n.CE\nThe \\fItkwin\\fR argument identifies the window in which the\nimage will be used and \\fImodelData\\fR is the value\nreturned by \\fIcreateProc\\fR when the image model was created.\n\\fIgetProc\\fR will usually create a data structure for the new\ninstance, including such things as the resources needed to\ndisplay the image in the given window.\n\\fIgetProc\\fR returns a one-word token for the instance, which\nis typically the address of the instance data structure.\nTk will pass this value back to the image manager when invoking\nits \\fIdisplayProc\\fR and \\fIfreeProc\\fR procedures.\n.SS DISPLAYPROC\n.PP\n\\fItypePtr->displayProc\\fR is invoked by Tk whenever an image needs\nto be displayed (i.e., whenever a widget calls \\fBTk_RedrawImage\\fR).\n\\fIdisplayProc\\fR must match the following prototype:\n.CS\ntypedef void \\fBTk_ImageDisplayProc\\fR(\n void *\\fIinstanceData\\fR,\n Display *\\fIdisplay\\fR,\n Drawable \\fIdrawable\\fR,\n int \\fIimageX\\fR,\n int \\fIimageY\\fR,\n int \\fIwidth\\fR,\n int \\fIheight\\fR,\n int \\fIdrawableX\\fR,\n int \\fIdrawableY\\fR);\n.CE\nThe \\fIinstanceData\\fR will be the same as the value returned by\n\\fIgetProc\\fR when the instance was created.\n\\fIdisplay\\fR and \\fIdrawable\\fR indicate where to display the\nimage; \\fIdrawable\\fR may be a pixmap rather than\nthe window specified to \\fIgetProc\\fR (this is usually the case,\nsince most widgets double-buffer their redisplay to get smoother\nvisual effects).\n\\fIimageX\\fR, \\fIimageY\\fR, \\fIwidth\\fR, and \\fIheight\\fR\nidentify the region of the image that must be redisplayed.\nThis region will always be within the size of the image\nas specified in the most recent call to \\fBTk_ImageChanged\\fR.\n\\fIdrawableX\\fR and \\fIdrawableY\\fR indicate where in \\fIdrawable\\fR\nthe image should be displayed; \\fIdisplayProc\\fR should display\nthe given region of the image so that point (\\fIimageX\\fR, \\fIimageY\\fR)\nin the image appears at (\\fIdrawableX\\fR, \\fIdrawableY\\fR) in \\fIdrawable\\fR.\n.SS FREEPROC\n.PP\n\\fItypePtr->freeProc\\fR contains the address of a procedure that\nTk will invoke when an image instance is released (i.e., when\n\\fBTk_FreeImage\\fR is invoked).\nThis can happen, for example, when a widget is deleted or a image item\nin a canvas is deleted, or when the image displayed in a widget or\ncanvas item is changed.\n\\fIfreeProc\\fR must match the following prototype:\n.CS\ntypedef void \\fBTk_ImageFreeProc\\fR(\n void *\\fIinstanceData\\fR,\n Display *\\fIdisplay\\fR);\n.CE\nThe \\fIinstanceData\\fR will be the same as the value returned by\n\\fIgetProc\\fR when the instance was created, and \\fIdisplay\\fR\nis the display containing the window for the instance.\n\\fIfreeProc\\fR should release any resources associated with the\nimage instance, since the instance will never be used again.\n.SS DELETEPROC\n.PP\n\\fItypePtr->deleteProc\\fR is a procedure that Tk invokes when an\nimage is being deleted (i.e. when the \\fBimage delete\\fR command\nis invoked).\nBefore invoking \\fIdeleteProc\\fR Tk will invoke \\fIfreeProc\\fR for\neach of the image's instances.\n\\fIdeleteProc\\fR must match the following prototype:\n.CS\ntypedef void \\fBTk_ImageDeleteProc\\fR(\n void *\\fImodelData\\fR);\n.CE\nThe \\fImodelData\\fR argument will be the same as the value\nstored in \\fI*modelDataPtr\\fR by \\fIcreateProc\\fR when the\nimage was created.\n\\fIdeleteProc\\fR should release any resources associated with\nthe image.\n.SH TK_GETIMAGEMODELDATA\n.PP\nThe procedure \\fBTk_GetImageModelData\\fR may be invoked to retrieve\ninformation about an image. For example, an image manager can use this\nprocedure to locate its image model data for an image.\nIf there exists an image named \\fIname\\fR\nin the interpreter given by \\fIinterp\\fR, then \\fI*typePtrPtr\\fR is\nfilled in with type information for the image (the \\fItypePtr\\fR value\npassed to \\fBTk_CreateImageType\\fR when the image type was registered)\nand the return value is the clientData value returned by the\n\\fIcreateProc\\fR when the image was created (this is typically a\npointer to the image model data structure). If no such image exists\nthen NULL is returned and NULL is stored at \\fI*typePtrPtr\\fR.\n.SH \"SEE ALSO\"\nTk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage\n.SH KEYWORDS\nimage manager, image type, instance, model\n" }, { "path": "doc/CrtItemType.3", "content": "'\\\"\n'\\\" Copyright (c) 1994-1995 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CreateItemType 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreateItemType, Tk_GetItemTypes \\- define new kind of canvas item\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_CreateItemType\\fR(\\fItypePtr\\fR)\n.sp\nTk_ItemType *\n\\fBTk_GetItemTypes\\fR()\n.fi\n.SH ARGUMENTS\n.AS Tk_ItemType *typePtr\n.AP Tk_ItemType *typePtr in\nStructure that defines the new type of canvas item.\nNote that this is not \\fIconst\\fR; Tk may write to these structures.\n.BE\n.SH INTRODUCTION\n.PP\n\\fBTk_CreateItemType\\fR is invoked to define a new kind of canvas item\ndescribed by the \\fItypePtr\\fR argument.\nAn item type corresponds to a particular value of the \\fItype\\fR\nargument to the \\fBcreate\\fR widget command for canvases, and\nthe code that implements a canvas item type is called a \\fItype manager\\fR.\nTk defines several built-in item types, such as \\fBrectangle\\fR\nand \\fBtext\\fR and \\fBimage\\fR, but \\fBTk_CreateItemType\\fR\nallows additional item types to be defined.\nOnce \\fBTk_CreateItemType\\fR returns, the new item type may be used\nin new or existing canvas widgets just like the built-in item\ntypes.\n.PP\n\\fBTk_GetItemTypes\\fR returns a pointer to the first in the list\nof all item types currently defined for canvases.\nThe entries in the list are linked together through their\n\\fInextPtr\\fR fields, with the end of the list marked by a\nNULL \\fInextPtr\\fR.\n.PP\nYou may find it easier to understand the rest of this manual entry\nby looking at the code for an existing canvas item type such as\nbitmap (in the file tkCanvBmap.c) or text (tkCanvText.c).\nThe easiest way to create a new type manager is to copy the code\nfor an existing type and modify it for the new type.\n.PP\nTk provides a number of utility procedures for the use of canvas\ntype managers, such as \\fBTk_CanvasCoords\\fR and \\fBTk_CanvasPsColor\\fR;\nthese are described in separate manual entries.\n.SH \"DATA STRUCTURES\"\n.PP\nA type manager consists of a collection of procedures that provide a\nstandard set of operations on items of that type.\nThe type manager deals with three kinds of data\nstructures.\nThe first data structure is a Tk_ItemType; it contains\ninformation such as the name of the type and pointers to\nthe standard procedures implemented by the type manager:\n.PP\n.CS\ntypedef struct Tk_ItemType {\n const char *\\fIname\\fR;\n Tcl_Size \\fIitemSize\\fR;\n Tk_ItemCreateProc *\\fIcreateProc\\fR;\n const Tk_ConfigSpec *\\fIconfigSpecs\\fR;\n Tk_ItemConfigureProc *\\fIconfigProc\\fR;\n Tk_ItemCoordProc *\\fIcoordProc\\fR;\n Tk_ItemDeleteProc *\\fIdeleteProc\\fR;\n Tk_ItemDisplayProc *\\fIdisplayProc\\fR;\n int \\fIflags\\fR;\n Tk_ItemPointProc *\\fIpointProc\\fR;\n Tk_ItemAreaProc *\\fIareaProc\\fR;\n Tk_ItemPostscriptProc *\\fIpostscriptProc\\fR;\n Tk_ItemScaleProc *\\fIscaleProc\\fR;\n Tk_ItemTranslateProc *\\fItranslateProc\\fR;\n Tk_ItemIndexProc *\\fIindexProc\\fR;\n Tk_ItemCursorProc *\\fIicursorProc\\fR;\n Tk_ItemSelectionProc *\\fIselectionProc\\fR;\n Tk_ItemInsertProc *\\fIinsertProc\\fR;\n Tk_ItemDCharsProc *\\fIdCharsProc\\fR;\n struct Tk_ItemType *\\fInextPtr\\fR;\n.VS \"9.0, TIP164\"\n Tk_ItemRotateProc *\\fIrotateProc\\fR;\n.VE \"9.0, TIP164\"\n} \\fBTk_ItemType\\fR;\n.CE\n.PP\nThe fields of a Tk_ItemType structure are described in more detail\nlater in this manual entry.\nWhen \\fBTk_CreateItemType\\fR is called, its \\fItypePtr\\fR\nargument must point to a structure with all of the fields initialized\nexcept \\fInextPtr\\fR, which Tk sets to link all the types together\ninto a list.\nThe structure must be in permanent memory (either statically\nallocated or dynamically allocated but never freed); Tk retains\na pointer to this structure.\n.PP\nThe second data structure manipulated by a type manager is an\n\\fIitem record\\fR.\nFor each item in a canvas there exists one item record.\nAll of the items of a given type generally have item records with\nthe same structure, but different types usually have different\nformats for their item records.\nThe first part of each item record is a header with a standard structure\ndefined by Tk via the type Tk_Item; the rest of the item\nrecord is defined by the type manager.\nA type manager must define its item records with a Tk_Item as\nthe first field.\nFor example, the item record for bitmap items is defined as follows:\n.PP\n.CS\ntypedef struct {\n Tk_Item \\fIheader\\fR;\n double \\fIx\\fR, \\fIy\\fR;\n Tk_Anchor \\fIanchor\\fR;\n Pixmap \\fIbitmap\\fR;\n XColor *\\fIfgColor\\fR;\n XColor *\\fIbgColor\\fR;\n GC \\fIgc\\fR;\n} \\fBBitmapItem\\fR;\n.CE\n.PP\nThe \\fIheader\\fR substructure contains information used by Tk\nto manage the item, such as its identifier, its tags, its type,\nand its bounding box.\nThe fields starting with \\fIx\\fR belong to the type manager:\nTk will never read or write them.\nThe type manager should not need to read or write any of the\nfields in the header except for four fields\nwhose names are \\fIx1\\fR, \\fIy1\\fR, \\fIx2\\fR, and \\fIy2\\fR.\nThese fields give a bounding box for the items using integer\ncanvas coordinates: the item should not cover any pixels\nwith x-coordinate lower than \\fIx1\\fR or y-coordinate\nlower than \\fIy1\\fR, nor should it cover any pixels with\nx-coordinate greater than or equal to \\fIx2\\fR or y-coordinate\ngreater than or equal to \\fIy2\\fR.\nIt is up to the type manager to keep the bounding box up to\ndate as the item is moved and reconfigured.\n.PP\nWhenever Tk calls a procedure in a type manager it passes in a pointer\nto an item record.\nThe argument is always passed as a pointer to a Tk_Item; the type\nmanager will typically cast this into a pointer to its own specific\ntype, such as BitmapItem.\n.PP\nThe third data structure used by type managers has type\nTk_Canvas; it serves as an opaque handle for the canvas widget\nas a whole.\nType managers need not know anything about the contents of this\nstructure.\nA Tk_Canvas handle is typically passed in to the\nprocedures of a type manager, and the type manager can pass the\nhandle back to library procedures such as Tk_CanvasTkwin\nto fetch information about the canvas.\n.SH \"TK_ITEMTYPE FIELDS\"\n.SS NAME\n.PP\nThis section and the ones that follow describe each of the fields\nin a Tk_ItemType structure in detail.\nThe \\fIname\\fR field provides a string name for the item type.\nOnce \\fBTk_CreateImageType\\fR returns, this name may be used\nin \\fBcreate\\fR widget commands to create items of the new\ntype.\nIf there already existed an item type by this name then\nthe new item type replaces the old one.\n.SS \"FLAGS (IN ALWAYSREDRAW)\"\n.PP\nThe \\fItypePtr\\->flags\\fR field\ncontains a collection of flag bits that modify how the canvas core interacts\nwith the item. The following bits are defined:\n.TP\n\\fBTK_ALWAYS_REDRAW\\fR\n.\nIndicates that the item should always be redrawn when any part of the canvas\nis redrawn, rather than only when the bounding box of the item overlaps the\narea being redrawn. This is used by window items, for example, which need to\nunmap subwindows that are not on the screen.\n.TP\n\\fBTK_MOVABLE_POINTS\\fR\n.VS 8.6\nIndicates that the item supports the \\fIdCharsProc\\fR, \\fIindexProc\\fR and\n\\fIinsertProc\\fR with the same semantics as Tk's built-in line and polygon\ntypes, and that hence individual coordinate points can be moved. Must not be\nset if any of the above methods is NULL.\n.VE 8.6\n.SS ITEMSIZE\n.PP\n\\fItypePtr\\->itemSize\\fR gives the size in bytes of item records\nof this type, including the Tk_Item header.\nTk uses this size to allocate memory space for items of the type.\nAll of the item records for a given type must have the same size.\nIf variable length fields are needed for an item (such as a list\nof points for a polygon), the type manager can allocate a separate\nobject of variable length and keep a pointer to it in the item record.\n.SS CREATEPROC\n.PP\n\\fItypePtr\\->createProc\\fR points to a procedure for\nTk to call whenever a new item of this type is created.\n\\fItypePtr\\->createProc\\fR must match the following prototype:\n.PP\n.CS\ntypedef int \\fBTk_ItemCreateProc\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n int \\fIobjc\\fR,\n Tcl_Obj *const *\\fIobjv\\fR);\n.CE\n.PP\nThe \\fIinterp\\fR argument is the interpreter in which the canvas's\n\\fBcreate\\fR widget command was invoked, and \\fIcanvas\\fR is a\nhandle for the canvas widget.\n\\fIitemPtr\\fR is a pointer to a newly-allocated item of\nsize \\fItypePtr\\->itemSize\\fR.\nTk has already initialized the item's header (the first\n\\fBsizeof(Tk_ItemType)\\fR bytes).\nThe \\fIobjc\\fR and \\fIobjv\\fR arguments describe all of the\narguments to the \\fBcreate\\fR command after the \\fItype\\fR\nargument.\nFor example, in the widget command:\n.PP\n.CS\n\\fB\\&.c create rectangle 10 20 50 50 \\-fill black\\fR\n.CE\n.PP\n\\fIobjc\\fR will be \\fB6\\fR and \\fIobjv\\fR[0] will contain the\ninteger object \\fB10\\fR.\n.PP\n\\fIcreateProc\\fR should use \\fIobjc\\fR and \\fIobjv\\fR to initialize\nthe type-specific parts of the item record and set an initial value\nfor the bounding box in the item's header.\nIt should return a standard Tcl completion code and leave an\nerror message in the interpreter result if an error occurs.\nIf an error occurs Tk will free the item record, so \\fIcreateProc\\fR\nmust be sure to leave the item record in a clean state if it returns an error\n(e.g., it must free any additional memory that it allocated for\nthe item).\n.SS CONFIGSPECS\n.PP\nEach type manager must provide a standard table describing its\nconfiguration options, in a form suitable for use with\n\\fBTk_ConfigureWidget\\fR.\nThis table will normally be used by \\fItypePtr\\->createProc\\fR\nand \\fItypePtr\\->configProc\\fR, but Tk also uses it directly\nto retrieve option information in the \\fBitemcget\\fR and\n\\fBitemconfigure\\fR widget commands.\n\\fItypePtr\\->configSpecs\\fR must point to the configuration table\nfor this type.\n.PP\nNote that Tk provides a custom option type \\fBtk_CanvasTagsOption\\fR\nfor implementing the \\fB\\-tags\\fR option; see an existing type\nmanager for an example of how to use it in \\fIconfigSpecs\\fR.\n.SS CONFIGPROC\n.PP\n\\fItypePtr\\->configProc\\fR is called by Tk whenever the\n\\fBitemconfigure\\fR widget command is invoked to change the\nconfiguration options for a canvas item.\nThis procedure must match the following prototype:\n.PP\n.CS\ntypedef int \\fBTk_ItemConfigureProc\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n int \\fIobjc\\fR,\n Tcl_Obj *const *\\fIobjv\\fR,\n int \\fIflags\\fR);\n.CE\n.PP\nThe \\fIinterp\\fR argument identifies the interpreter in which the\nwidget command was invoked, \\fIcanvas\\fR is a handle for the canvas\nwidget, and \\fIitemPtr\\fR is a pointer to the item being configured.\n\\fIobjc\\fR and \\fIobjv\\fR contain the configuration options.\nFor example, if the following command is invoked:\n.PP\n.CS\n\\fB\\&.c itemconfigure 2 \\-fill red \\-outline black\\fR\n.CE\n.PP\n\\fIobjc\\fR is \\fB4\\fR and \\fIobjv\\fR contains the string objects \\fB\\-fill\\fR\nthrough \\fBblack\\fR.\n\\fIobjc\\fR will always be an even value.\nThe \\fIflags\\fR argument contains flags to pass to \\fBTk_ConfigureWidget\\fR;\ncurrently this value is always \\fBTK_CONFIG_ARGV_ONLY\\fR when Tk\ninvokes \\fItypePtr\\->configProc\\fR, but the type manager's \\fIcreateProc\\fR\nprocedure will usually invoke \\fIconfigProc\\fR with different flag values.\n.PP\n\\fItypePtr\\->configProc\\fR returns a standard Tcl completion code and\nleaves an error message in the interpreter result if an error occurs.\nIt must update the item's bounding box to reflect the new configuration\noptions.\n.SS COORDPROC\n.PP\n\\fItypePtr\\->coordProc\\fR is invoked by Tk to implement the \\fBcoords\\fR\nwidget command for an item.\nIt must match the following prototype:\n.PP\n.CS\ntypedef int \\fBTk_ItemCoordProc\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n int \\fIobjc\\fR,\n Tcl_Obj *const *\\fIobjv\\fR);\n.CE\n.PP\nThe arguments \\fIinterp\\fR, \\fIcanvas\\fR, and \\fIitemPtr\\fR\nall have the standard meanings, and \\fIobjc\\fR and \\fIobjv\\fR\ndescribe the coordinate arguments.\nFor example, if the following widget command is invoked:\n.PP\n.CS\n\\fB\\&.c coords 2 30 90\\fR\n.CE\n.PP\n\\fIobjc\\fR will be \\fB2\\fR and \\fBobjv\\fR will contain the integer objects\n\\fB30\\fR and \\fB90\\fR.\n.PP\nThe \\fIcoordProc\\fR procedure should process the new coordinates,\nupdate the item appropriately (e.g., it must reset the bounding\nbox in the item's header), and return a standard Tcl completion\ncode.\nIf an error occurs, \\fIcoordProc\\fR must leave an error message in\nthe interpreter result.\n.SS DELETEPROC\n.PP\n\\fItypePtr\\->deleteProc\\fR is invoked by Tk to delete an item\nand free any resources allocated to it.\nIt must match the following prototype:\n.PP\n.CS\ntypedef void \\fBTk_ItemDeleteProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n Display *\\fIdisplay\\fR);\n.CE\n.PP\nThe \\fIcanvas\\fR and \\fIitemPtr\\fR arguments have the usual\ninterpretations, and \\fIdisplay\\fR identifies the X display containing\nthe canvas.\n\\fIdeleteProc\\fR must free up any resources allocated for the item,\nso that Tk can free the item record.\n\\fIdeleteProc\\fR should not actually free the item record; this will\nbe done by Tk when \\fIdeleteProc\\fR returns.\n.SS \"DISPLAYPROC\"\n.PP\n\\fItypePtr\\->displayProc\\fR is invoked by Tk to redraw an item\non the screen.\nIt must match the following prototype:\n.PP\n.CS\ntypedef void \\fBTk_ItemDisplayProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n Display *\\fIdisplay\\fR,\n Drawable \\fIdst\\fR,\n int \\fIx\\fR,\n int \\fIy\\fR,\n int \\fIwidth\\fR,\n int \\fIheight\\fR);\n.CE\n.PP\nThe \\fIcanvas\\fR and \\fIitemPtr\\fR arguments have the usual meaning.\n\\fIdisplay\\fR identifies the display containing the canvas, and\n\\fIdst\\fR specifies a drawable in which the item should be rendered;\ntypically this is an off-screen pixmap, which Tk will copy into\nthe canvas's window once all relevant items have been drawn.\n\\fIx\\fR, \\fIy\\fR, \\fIwidth\\fR, and \\fIheight\\fR specify a rectangular\nregion in canvas coordinates, which is the area to be redrawn;\nonly information that overlaps this area needs to be redrawn.\nTk will not call \\fIdisplayProc\\fR unless the item's bounding box\noverlaps the redraw area, but the type manager may wish to use\nthe redraw area to optimize the redisplay of the item.\n.PP\nBecause of scrolling and the use of off-screen pixmaps for\ndouble-buffered redisplay, the item's coordinates in \\fIdst\\fR\nwill not necessarily be the same as those in the canvas.\n\\fIdisplayProc\\fR should call \\fBTk_CanvasDrawableCoords\\fR\nto transform coordinates from those of the canvas to those\nof \\fIdst\\fR.\n.PP\nNormally an item's \\fIdisplayProc\\fR is only invoked if the item\noverlaps the area being displayed.\nHowever, if bit zero of \\fItypePtr\\->flags\\fR is 1,\n(i.e.\\|\n.QW \"\\fItypePtr\\->flags & 1 == 1\\fR\" )\nthen \\fIdisplayProc\\fR is invoked during every redisplay operation,\neven if the item does not overlap the area of redisplay; this is useful for\ncases such as window items, where the subwindow needs to be unmapped when it\nis off the screen.\n.SS POINTPROC\n.PP\n\\fItypePtr\\->pointProc\\fR is invoked by Tk to find out how close\na given point is to a canvas item.\nTk uses this procedure for purposes such as locating the item\nunder the mouse or finding the closest item to a given point.\nThe procedure must match the following prototype:\n.PP\n.CS\ntypedef double \\fBTk_ItemPointProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n double *\\fIpointPtr\\fR);\n.CE\n.PP\n\\fIcanvas\\fR and \\fIitemPtr\\fR have the usual meaning.\n\\fIpointPtr\\fR points to an array of two numbers giving\nthe x and y coordinates of a point.\n\\fIpointProc\\fR must return a real value giving the distance\nfrom the point to the item, or 0 if the point lies inside\nthe item.\n.SS AREAPROC\n.PP\n\\fItypePtr\\->areaProc\\fR is invoked by Tk to find out the relationship\nbetween an item and a rectangular area.\nIt must match the following prototype:\n.PP\n.CS\ntypedef int \\fBTk_ItemAreaProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n double *\\fIrectPtr\\fR);\n.CE\n.PP\n\\fIcanvas\\fR and \\fIitemPtr\\fR have the usual meaning.\n\\fIrectPtr\\fR points to an array of four real numbers;\nthe first two give the x and y coordinates of the upper left\ncorner of a rectangle, and the second two give the x and y\ncoordinates of the lower right corner.\n\\fIareaProc\\fR must return \\-1 if the item lies entirely outside\nthe given area, 0 if it lies partially inside and partially\noutside the area, and 1 if it lies entirely inside the area.\n.SS POSTSCRIPTPROC\n.PP\n\\fItypePtr\\->postscriptProc\\fR is invoked by Tk to generate\nPostscript for an item during the \\fBpostscript\\fR widget command.\nIf the type manager is not capable of generating Postscript then\n\\fItypePtr\\->postscriptProc\\fR should be NULL.\nThe procedure must match the following prototype:\n.PP\n.CS\ntypedef int \\fBTk_ItemPostscriptProc\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n int \\fIprepass\\fR);\n.CE\n.PP\nThe \\fIinterp\\fR, \\fIcanvas\\fR, and \\fIitemPtr\\fR arguments all have\nstandard meanings; \\fIprepass\\fR will be described below.\nIf \\fIpostscriptProc\\fR completes successfully, it should append\nPostscript for the item to the information in the interpreter result\n(e.g. by calling \\fBTcl_AppendResult\\fR, not \\fBTcl_SetResult\\fR)\nand return \\fBTCL_OK\\fR.\nIf an error occurs, \\fIpostscriptProc\\fR should clear the result\nand replace its contents with an error message; then it should\nreturn \\fBTCL_ERROR\\fR.\n.PP\nTk provides a collection of utility procedures to simplify\n\\fIpostscriptProc\\fR.\nFor example, \\fBTk_CanvasPsColor\\fR will generate Postscript to set\nthe current color to a given Tk color and \\fBTk_CanvasPsFont\\fR will\nset up font information.\nWhen generating Postscript, the type manager is free to change the\ngraphics state of the Postscript interpreter, since Tk places\n\\fBgsave\\fR and \\fBgrestore\\fR commands around the Postscript for\nthe item.\nThe type manager can use canvas x coordinates directly in its Postscript,\nbut it must call \\fBTk_CanvasPsY\\fR to convert y coordinates from\nthe space of the canvas (where the origin is at the\nupper left) to the space of Postscript (where the origin is at the\nlower left).\n.PP\nIn order to generate Postscript that complies with the Adobe Document\nStructuring Conventions, Tk actually generates Postscript in two passes.\nIt calls each item's \\fIpostscriptProc\\fR in each pass.\nThe only purpose of the first pass is to collect font information\n(which is done by \\fBTk_CanvasPsFont\\fR); the actual Postscript is\ndiscarded.\nTk sets the \\fIprepass\\fR argument to \\fIpostscriptProc\\fR to 1\nduring the first pass; the type manager can use \\fIprepass\\fR to skip\nall Postscript generation except for calls to \\fBTk_CanvasPsFont\\fR.\nDuring the second pass \\fIprepass\\fR will be 0, so the type manager\nmust generate complete Postscript.\n.SS SCALEPROC\n.PP\n\\fItypePtr\\->scaleProc\\fR is invoked by Tk to rescale a canvas item\nduring the \\fBscale\\fR widget command.\nThe procedure must match the following prototype:\n.PP\n.CS\ntypedef void \\fBTk_ItemScaleProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n double \\fIoriginX\\fR,\n double \\fIoriginY\\fR,\n double \\fIscaleX\\fR,\n double \\fIscaleY\\fR);\n.CE\n.PP\nThe \\fIcanvas\\fR and \\fIitemPtr\\fR arguments have the usual meaning.\n\\fIoriginX\\fR and \\fIoriginY\\fR specify an origin relative to which\nthe item is to be scaled, and \\fIscaleX\\fR and \\fIscaleY\\fR give the\nx and y scale factors.\nThe item should adjust its coordinates so that a point in the item\nthat used to have coordinates \\fIx\\fR and \\fIy\\fR will have new\ncoordinates \\fIx\\(fm\\fR and \\fIy\\(fm\\fR, where\n.PP\n.CS\n\\fIx\\(fm\\fR = \\fIoriginX\\fR + \\fIscaleX\\fR \\(mu (\\fIx\\fR \\(mi \\fIoriginX\\fR)\n\\fIy\\(fm\\fR = \\fIoriginY\\fR + \\fIscaleY\\fR \\(mu (\\fIy\\fR \\(mi \\fIoriginY\\fR)\n.CE\n.PP\n\\fIscaleProc\\fR must also update the bounding box in the item's\nheader.\n.SS TRANSLATEPROC\n.PP\n\\fItypePtr\\->translateProc\\fR is invoked by Tk to translate a canvas item\nduring the \\fBmove\\fR widget command.\nThe procedure must match the following prototype:\n.PP\n.CS\ntypedef void \\fBTk_ItemTranslateProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n double \\fIdeltaX\\fR,\n double \\fIdeltaY\\fR);\n.CE\n.PP\nThe \\fIcanvas\\fR and \\fIitemPtr\\fR arguments have the usual meaning,\nand \\fIdeltaX\\fR and \\fIdeltaY\\fR give the amounts that should be\nadded to each x and y coordinate within the item.\nThe type manager should adjust the item's coordinates and\nupdate the bounding box in the item's header.\n.SS ROTATEPROC\n.VS \"9.0, TIP164\"\n.PP\n\\fItypePtr\\->rotateProc\\fR is invoked by Tk to rotate a canvas item\nduring the \\fBrotate\\fR widget command.\nThe procedure must match the following prototype:\n.PP\n.CS\ntypedef void \\fBTk_ItemRotateProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n double \\fIoriginX\\fR,\n double \\fIoriginY\\fR,\n double \\fIangleRad\\fR);\n.CE\n.PP\nThe \\fIcanvas\\fR and \\fIitemPtr\\fR arguments have the usual meaning.\n\\fIoriginX\\fR and \\fIoriginY\\fR specify an origin relative to which\nthe item is to be rotated, and \\fIangleRad\\fR gives the anticlockwise\nrotation to be applied in radians.\nThe item should adjust the coordinates of its control points so that where\nthey used to have coordinates \\fIx\\fR and \\fIy\\fR, they will have new\ncoordinates \\fIx\\(fm\\fR and \\fIy\\(fm\\fR, where\n.PP\n.CS\n\\fIrelX\\fR = \\fIx\\fR \\(mi \\fIoriginX\\fR\n\\fIrelY\\fR = \\fIy\\fR \\(mi \\fIoriginY\\fR\n\\fIx\\(fm\\fR = \\fIoriginX\\fR + \\fIrelX\\fR \\(mu cos(\\fIangleRad\\fR) + \\fIrelY\\fR \\(mu sin(\\fIangleRad\\fR)\n\\fIy\\(fm\\fR = \\fIoriginY\\fR \\(mi \\fIrelX\\fR \\(mu sin(\\fIangleRad\\fR) + \\fIrelY\\fR \\(mu cos(\\fIangleRad\\fR)\n.CE\n.PP\nThe control points for an item are not necessarily the coordinates provided to\nthe item when it is created (or via the \\fItypePtr\\->coordProc\\fR), but could\ninstead be derived from them.\n\\fIrotateProc\\fR must also update the bounding box in the item's header.\n.PP\nItem types do not need to provide a \\fItypePtr\\->rotateProc\\fR. If the\n\\fItypePtr\\->rotateProc\\fR is NULL, the \\fItypePtr\\->coordProc\\fR will be\nused instead to retrieve and update the list of coordinates.\n.VE \"9.0, TIP164\"\n.SS INDEXPROC\n.PP\n\\fItypePtr\\->indexProc\\fR is invoked by Tk to translate a string\nindex specification into a numerical index, for example during the\n\\fBindex\\fR widget command.\nIt is only relevant for item types that support indexable text or coordinates;\n\\fItypePtr\\->indexProc\\fR may be specified as NULL for non-textual\nitem types if they do not support detailed coordinate addressing.\nThe procedure must match the following prototype:\n.PP\n.CS\ntypedef int \\fBTk_ItemIndexProc\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n Tcl_Obj *\\fIindexObj\\fR,\n int *\\fIindexPtr\\fR);\n.CE\n.PP\nThe \\fIinterp\\fR, \\fIcanvas\\fR, and \\fIitemPtr\\fR arguments all\nhave the usual meaning.\n\\fIindexObj\\fR contains a textual description of an index,\nand \\fIindexPtr\\fR points to an integer value that should be\nfilled in with a numerical index.\nIt is up to the type manager to decide what forms of index\nare supported (e.g., numbers, \\fBinsert\\fR, \\fBsel.first\\fR,\n\\fBend\\fR, etc.).\n\\fIindexProc\\fR should return a Tcl completion code and set\nthe interpreter result in the event of an error.\n.SS ICURSORPROC\n.PP\n\\fItypePtr\\->icursorProc\\fR is invoked by Tk during\nthe \\fBicursor\\fR widget command to set the position of the\ninsertion cursor in a textual item.\nIt is only relevant for item types that support an insertion cursor;\n\\fItypePtr\\->icursorProc\\fR may be specified as NULL for item types\nthat do not support an insertion cursor.\nThe procedure must match the following prototype:\n.PP\n.CS\ntypedef void \\fBTk_ItemCursorProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n int \\fIindex\\fR);\n.CE\n.PP\n\\fIcanvas\\fR and \\fIitemPtr\\fR have the usual meanings, and\n\\fIindex\\fR is an index into the item's text, as returned by a\nprevious call to \\fItypePtr\\->insertProc\\fR.\nThe type manager should position the insertion cursor in the\nitem just before the character given by \\fIindex\\fR.\nWhether or not to actually display the insertion cursor is\ndetermined by other information provided by \\fBTk_CanvasGetTextInfo\\fR.\n.SS SELECTIONPROC\n.PP\n\\fItypePtr\\->selectionProc\\fR is invoked by Tk during selection\nretrievals; it must return part or all of the selected text in\nthe item (if any).\nIt is only relevant for item types that support text;\n\\fItypePtr\\->selectionProc\\fR may be specified as NULL for non-textual\nitem types.\nThe procedure must match the following prototype:\n.PP\n.CS\ntypedef int \\fBTk_ItemSelectionProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n int \\fIoffset\\fR,\n char *\\fIbuffer\\fR,\n int \\fImaxBytes\\fR);\n.CE\n.PP\n\\fIcanvas\\fR and \\fIitemPtr\\fR have the usual meanings.\n\\fIoffset\\fR is an offset in bytes into the selection where 0 refers\nto the first byte of the selection; it identifies\nthe first character that is to be returned in this call.\n\\fIbuffer\\fR points to an area of memory in which to store the\nrequested bytes, and \\fImaxBytes\\fR specifies the maximum number\nof bytes to return.\n\\fIselectionProc\\fR should extract up to \\fImaxBytes\\fR characters\nfrom the selection and copy them to \\fImaxBytes\\fR; it should\nreturn a count of the number of bytes actually copied, which may\nbe less than \\fImaxBytes\\fR if there are not \\fIoffset+maxBytes\\fR bytes\nin the selection.\n.SS INSERTPROC\n.PP\n\\fItypePtr\\->insertProc\\fR is invoked by Tk during\nthe \\fBinsert\\fR widget command to insert new text or coordinates into a\ncanvas item.\nIt is only relevant for item types that support the \\fBinsert\\fR method;\n\\fItypePtr\\->insertProc\\fR may be specified as NULL for other\nitem types.\nThe procedure must match the following prototype:\n.PP\n.CS\ntypedef void \\fBTk_ItemInsertProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n int \\fIindex\\fR,\n Tcl_Obj *\\fIobj\\fR);\n.CE\n.PP\n\\fIcanvas\\fR and \\fIitemPtr\\fR have the usual meanings.\n\\fIindex\\fR is an index into the item's text, as returned by a\nprevious call to \\fItypePtr\\->insertProc\\fR, and \\fIobj\\fR\ncontains new text to insert just before the character given\nby \\fIindex\\fR.\nIf the item supports modification of the coordinates list by this\n.PP\nThe type manager should insert the text and recompute the bounding\nbox in the item's header.\n.SS DCHARSPROC\n.PP\n\\fItypePtr\\->dCharsProc\\fR is invoked by Tk during the \\fBdchars\\fR\nwidget command to delete a range of text from a canvas item or a range of\ncoordinates from a pathed item.\nIt is only relevant for item types that support text;\n\\fItypePtr\\->dCharsProc\\fR may be specified as NULL for non-textual\nitem types that do not want to support coordinate deletion.\nThe procedure must match the following prototype:\n.PP\n.CS\ntypedef void \\fBTk_ItemDCharsProc\\fR(\n Tk_Canvas \\fIcanvas\\fR,\n Tk_Item *\\fIitemPtr\\fR,\n int \\fIfirst\\fR,\n int \\fIlast\\fR);\n.CE\n.PP\n\\fIcanvas\\fR and \\fIitemPtr\\fR have the usual meanings.\n\\fIfirst\\fR and \\fIlast\\fR give the indices of the first and last bytes\nto be deleted, as returned by previous calls to \\fItypePtr\\->indexProc\\fR.\nThe type manager should delete the specified characters and update\nthe bounding box in the item's header.\n.SH \"SEE ALSO\"\nTk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin\n.SH KEYWORDS\ncanvas, focus, item type, selection, type manager\n" }, { "path": "doc/CrtPhImgFmt.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Australian National University\n'\\\" Copyright (c) 1994-1997 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n'\\\" Author: Paul Mackerras (paulus@cs.anu.edu.au),\n'\\\"\t Department of Computer Science,\n'\\\"\t Australian National University.\n'\\\"\n.TH Tk_CreatePhotoImageFormat 3 9.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreatePhotoImageFormat \\- define new file format for photo images\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n.VS 9.0\n\\fBTk_CreatePhotoImageFormatVersion3\\fR(\\fIformatVersion3Ptr\\fR)\n.VE 9.0\n.sp\n\\fBTk_CreatePhotoImageFormat\\fR(\\fIformatPtr\\fR)\n.SH ARGUMENTS\n.AS \"const Tk_PhotoImageFormatVersion3\" *formatVersion3Ptr\n.VS 9.0\n.AP \"const Tk_PhotoImageFormatVersion3\" *formatVersion3Ptr in\nStructure that defines the new file format including metadata functionality.\n.VE 9.0\n.AP \"const Tk_PhotoImageFormat\" *formatPtr in\nStructure that defines the new file format.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_CreatePhotoImageFormatVersion3\\fR is invoked to define a new file format\nfor image data for use with photo images. The code that implements an\nimage file format is called an image file format handler, or\nhandler for short. The photo image code\nmaintains a list of handlers that can be used to read and\nwrite data to or from a file. Some handlers may also\nsupport reading image data from a string or converting image data to a\nstring format.\nThe user can specify which handler to use with the \\fB\\-format\\fR\nimage configuration option or the \\fB\\-format\\fR option to the\n\\fBread\\fR and \\fBwrite\\fR photo image subcommands.\n.PP\nThe alternate version 2 function \\fBTk_CreatePhotoImageFormat\\fR has\nidentical functionality, but does not allow the handler to get or return\nthe metadata dictionary of the image.\nIt is described in section \\fBVERSION 2 INTERFACE\\fR below.\n.PP\nAn image file format handler consists of a collection of procedures\nplus a \\fBTk_PhotoImageFormatVersion3\\fR structure, which contains the\nname of the image file format and pointers to six procedures provided\nby the handler to deal with files and strings in this format. The\nTk_PhotoImageFormatVersion3 structure contains the following fields:\n.VS 9.0\n.CS\ntypedef struct {\n const char *\\fIname\\fR;\n Tk_ImageFileMatchProcVersion3 *\\fIfileMatchProc\\fR;\n Tk_ImageStringMatchProcVersion3 *\\fIstringMatchProc\\fR;\n Tk_ImageFileReadProcVersion3 *\\fIfileReadProc\\fR;\n Tk_ImageStringReadProcVersion3 *\\fIstringReadProc\\fR;\n Tk_ImageFileWriteProcVersion3 *\\fIfileWriteProc\\fR;\n Tk_ImageStringWriteProcVersion3 *\\fIstringWriteProc\\fR;\n} \\fBTk_PhotoImageFormatVersion3\\fR;\n.CE\n.VE 9.0\n.PP\nThe handler need not provide implementations of all six procedures.\nFor example, the procedures that handle string data would not be\nprovided for a format in which the image data are stored in binary,\nand could therefore contain null characters. If any procedure is not\nimplemented, the corresponding pointer in the Tk_PhotoImageFormat\nstructure should be set to NULL. The handler must provide the\n\\fIfileMatchProc\\fR procedure if it provides the \\fIfileReadProc\\fR\nprocedure, and the \\fIstringMatchProc\\fR procedure if it provides the\n\\fIstringReadProc\\fR procedure.\n.SS NAME\n.PP\n\\fIformatPtr->name\\fR provides a name for the image type.\nOnce \\fBTk_CreatePhotoImageFormatVersion3\\fR returns, this name may be\nused in the \\fB\\-format\\fR photo image configuration and subcommand\noption.\nThe manual page for the photo image (photo(n)) describes how image\nfile formats are chosen based on their names and the value given to\nthe \\fB\\-format\\fR option. The first character of \\fIformatPtr->name\\fR\nmust not be an uppercase character from the ASCII character set\n(that is, one of the characters \\fBA\\fR-\\fBZ\\fR). Such names are used\nonly for legacy interface support (see below).\n.VS 9.0\n.SS FILEMATCHPROC\n.PP\n\\fIformatPtr->fileMatchProc\\fR provides the address of a procedure for\nTk to call when it is searching for an image file format handler\nsuitable for reading data in a given file.\n\\fIformatPtr->fileMatchProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageFileMatchProcVersion3\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tcl_Channel \\fIchan\\fR,\n const char *\\fIfileName\\fR,\n Tcl_Obj *\\fIformat\\fR,\n Tcl_Obj *\\fImetadataIn\\fR,\n int *\\fIwidthPtr\\fR,\n int *\\fIheightPtr\\fR,\n Tcl_Obj *\\fImetadataOut\\fR);\n.CE\nThe \\fIfileName\\fR argument is the name of the file containing the\nimage data, which is open for reading as \\fIchan\\fR. The\n\\fIformat\\fR argument contains the value given for the\n\\fB\\-format\\fR option, or NULL if the option was not specified.\n\\fBmetadataIn\\fR and \\fBmetadataOut\\fR inputs and returns a metadata\ndictionary as described in section \\fBMETADATA INTERFACE\\fR below.\nIf the data in the file appears to be in the format supported by this\nhandler, the \\fIformatPtr->fileMatchProc\\fR procedure should store the\nwidth and height of the image in *\\fIwidthPtr\\fR and *\\fIheightPtr\\fR\nrespectively, and return 1. Otherwise it should return 0.\n.SS STRINGMATCHPROC\n.PP\n\\fIformatPtr->stringMatchProc\\fR provides the address of a procedure\nfor Tk to call when it is searching for an image file format handler\nsuitable for reading data from a given string.\n\\fIformatPtr->stringMatchProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageStringMatchProcVersion3\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tcl_Obj *\\fIdata\\fR,\n Tcl_Obj *\\fIformat\\fR,\n Tcl_Obj *\\fImetadataIn\\fR,\n int *\\fIwidthPtr\\fR,\n int *\\fIheightPtr\\fR,\n Tcl_Obj *\\fImetadataOut\\fR);\n.CE\nThe \\fIdata\\fR argument points to the object containing the image\ndata. The \\fIformat\\fR argument contains the value given for\nthe \\fB\\-format\\fR option, or NULL if the option was not specified.\n\\fBmetadataIn\\fR and \\fBmetadataOut\\fR inputs and returns a metadata\ndictionary as described in section \\fBMETADATA INTERFACE\\fR below.\nIf the data in the string appears to be in the format supported by\nthis handler, the \\fIformatPtr->stringMatchProc\\fR procedure should\nstore the width and height of the image in *\\fIwidthPtr\\fR and\n*\\fIheightPtr\\fR respectively, and return 1. Otherwise it should\nreturn 0.\n.SS FILEREADPROC\n.PP\n\\fIformatPtr->fileReadProc\\fR provides the address of a procedure for\nTk to call to read data from an image file into a photo image.\n\\fIformatPtr->fileReadProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageFileReadProcVersion3\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tcl_Channel \\fIchan\\fR,\n const char *\\fIfileName\\fR,\n Tcl_Obj *\\fIformat\\fR,\n Tcl_Obj *\\fImetadataIn\\fR,\n PhotoHandle \\fIimageHandle\\fR,\n int \\fIdestX\\fR, int \\fIdestY\\fR,\n int \\fIwidth\\fR, int \\fIheight\\fR,\n int \\fIsrcX\\fR, int \\fIsrcY\\fR,\n Tcl_Obj *\\fImetadataOut\\fR);\n.CE\nThe \\fIinterp\\fR argument is the interpreter in which the command was\ninvoked to read the image; it should be used for reporting errors.\nThe image data is in the file named \\fIfileName\\fR, which is open for\nreading as \\fIchan\\fR. The \\fIformat\\fR argument contains the\nvalue given for the \\fB\\-format\\fR option, or NULL if the option was\nnot specified. The image data in the file, or a subimage of it, is to\nbe read into the photo image identified by the handle\n\\fIimageHandle\\fR. The subimage of the data in the file is of\ndimensions \\fIwidth\\fR x \\fIheight\\fR and has its top-left corner at\ncoordinates (\\fIsrcX\\fR,\\fIsrcY\\fR). It is to be stored in the photo\nimage with its top-left corner at coordinates\n(\\fIdestX\\fR,\\fIdestY\\fR) using the \\fBTk_PhotoPutBlock\\fR procedure.\n\\fBmetadataIn\\fR and \\fBmetadataOut\\fR inputs and returns a metadata\ndictionary as described in section \\fBMETADATA INTERFACE\\fR below.\nThe return value is a standard Tcl return value.\n.SS STRINGREADPROC\n.PP\n\\fIformatPtr->stringReadProc\\fR provides the address of a procedure\nfor Tk to call to read data from a string into a photo image.\n\\fIformatPtr->stringReadProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageStringReadProcVersion3\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tcl_Obj *\\fIdata\\fR,\n Tcl_Obj *\\fIformat\\fR,\n Tcl_Obj *\\fImetadataIn\\fR,\n PhotoHandle \\fIimageHandle\\fR,\n int \\fIdestX\\fR, int \\fIdestY\\fR,\n int \\fIwidth\\fR, int \\fIheight\\fR,\n int \\fIsrcX\\fR, int \\fIsrcY\\fR,\n Tcl_Obj *\\fImetadataOut\\fR);\n.CE\nThe \\fIinterp\\fR argument is the interpreter in which the command was\ninvoked to read the image; it should be used for reporting errors.\nThe \\fIdata\\fR argument points to the image data in object form.\nThe \\fIformat\\fR argument contains the\nvalue given for the \\fB\\-format\\fR option, or NULL if the option was\nnot specified. The image data in the string, or a subimage of it, is\nto be read into the photo image identified by the handle\n\\fIimageHandle\\fR. The subimage of the data in the string is of\ndimensions \\fIwidth\\fR x \\fIheight\\fR and has its top-left corner at\ncoordinates (\\fIsrcX\\fR,\\fIsrcY\\fR). It is to be stored in the photo\nimage with its top-left corner at coordinates\n(\\fIdestX\\fR,\\fIdestY\\fR) using the \\fBTk_PhotoPutBlock\\fR procedure.\n\\fBmetadataIn\\fR and \\fBmetadataOut\\fR inputs and returns a metadata\ndictionary as described in section \\fBMETADATA INTERFACE\\fR below.\nThe return value is a standard Tcl return value.\n.SS FILEWRITEPROC\n.PP\n\\fIformatPtr->fileWriteProc\\fR provides the address of a procedure for\nTk to call to write data from a photo image to a file.\n\\fIformatPtr->fileWriteProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageFileWriteProcVersion3\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n const char *\\fIfileName\\fR,\n Tcl_Obj *\\fIformat\\fR,\n Tcl_Obj *\\fImetadataIn\\fR,\n Tk_PhotoImageBlock *\\fIblockPtr\\fR);\n.CE\nThe \\fIinterp\\fR argument is the interpreter in which the command was\ninvoked to write the image; it should be used for reporting errors.\nThe image data to be written are in memory and are described by the\nTk_PhotoImageBlock structure pointed to by \\fIblockPtr\\fR; see the\nmanual page FindPhoto(3) for details. The \\fIfileName\\fR argument\npoints to the string giving the name of the file in which to write the\nimage data. The \\fIformat\\fR argument contains the\nvalue given for the \\fB\\-format\\fR option, or NULL if the option was\nnot specified. The format string can contain extra characters\nafter the name of the format. If appropriate, the\n\\fIformatPtr->fileWriteProc\\fR procedure may interpret these\ncharacters to specify further details about the image file.\n\\fBmetadataIn\\fR may contain metadata keys that a driver may include\ninto the output data.\nThe return value is a standard Tcl return value.\n.SS STRINGWRITEPROC\n.PP\n\\fIformatPtr->stringWriteProc\\fR provides the address of a procedure\nfor Tk to call to translate image data from a photo image into a\nstring.\n\\fIformatPtr->stringWriteProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageStringWriteProcVersion3\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tcl_Obj *\\fIformat\\fR,\n Tcl_Obj *\\fImetadataIn\\fR,\n Tk_PhotoImageBlock *\\fIblockPtr\\fR);\n.CE\nThe \\fIinterp\\fR argument is the interpreter in which the command was\ninvoked to convert the image; it should be used for reporting errors.\nThe image data to be converted are in memory and are described by the\nTk_PhotoImageBlock structure pointed to by \\fIblockPtr\\fR; see the\nmanual page FindPhoto(3) for details. The data for the string\nshould be put in the interpreter \\fIinterp\\fR result.\nThe \\fIformat\\fR argument contains the\nvalue given for the \\fB\\-format\\fR option, or NULL if the option was\nnot specified. The format string can contain extra characters\nafter the name of the format. If appropriate, the\n\\fIformatPtr->stringWriteProc\\fR procedure may interpret these\ncharacters to specify further details about the image file.\n\\fBmetadataIn\\fR may contain metadata keys that a driver may include\ninto the output data.\nThe return value is a standard Tcl return value.\n.PP\n.SH \"METADATA INTERFACE\"\n.PP\nImage formats contain a description of the image bitmap and may\ncontain additional information like image resolution or comments.\nImage metadata may be read from image files and passed to the script\nlevel by including dictionary keys into the metadata property of the\nimage. Image metadata may be written to image data on file write or\nimage data output.\n.PP\n.SS \"METADATA KEYS\"\n.PP\nThe metadata may contain any key.\nA driver will handle only a set of dictionary keys documented in the\ndocumentation. See the photo image manual page for currently defined\nkeys for the system drivers.\n.PP\nThe following rules may give guidance to name metadata keys:\n.IP \\(bu\nAbbreviations are in upper case.\n.IP \\(bu\nWords are in US English in small case (except proper nouns)\n.IP \\(bu\nVertical DPI is expressed as DPI/aspect. The reason is, that some\nimage formats may feature aspect and no resolution value.\n.SS \"METADATA INPUT\"\n.PP\nEach driver function gets a Tcl object pointer \\fBmetadataIn\\fR as\nparameter. This parameter serves to input a metadata dict to the\ndriver function.\nIt may be NULL to flag that the metadata dict is empty.\n.PP\nA typical driver code snipped to check for a metadata key is:\n.CS\nif (NULL != metadataIn) {\n Tcl_Obj *itemData;\n Tcl_DictObjGet(interp, metadataIn, Tcl_NewStringObj(\"Comment\",-1),\n &itemData));\n // use value reference in itemData\n}\n.CE\n.PP\nThe \\fB\\-metadata\\fR command option data of the following commands is passed\nto the driver: \\fBimage create\\fR, \\fBconfigure\\fR, \\fBput\\fR,\n\\fBread\\fR, \\fBdata\\fR and \\fBwrite\\fR.\nIf no \\fB\\-metadata\\fR command option available or not given, the metadata\nproperty of the image is passed to the driver using the following\ncommands: \\fBcget\\fR, \\fBconfigure\\fR, \\fBdata\\fR and \\fBwrite\\fR.\n.PP\nNote that setting the \\fB\\-metadata\\fR property of an image using\n\\fBconfigure\\fR without any other option does not invoke any driver\nfunction.\n.PP\nThe metadata dictionary is not suited to pass options to the driver\nrelated to the bitmap representation, as the image bitmap is not\nrecreated on a metadata change. The format string should be used for\nthis purpose.\n.PP\n.SS \"METADATA OUTPUT\"\n.PP\nThe image match and read driver functions may set keys in a prepared\nmetadata dict to return them.\nThose functions get a Tcl object pointer \\fImetadataOut\\fR as\nparameter.\n\\fImetadataOut\\fR may be NULL to indicate, that no metadata return is\nrequired (\\fBput\\fR, \\fBread\\fR subcommands). The variable pointed to\nby \\fImetadataOut\\fR is initialized to an empty unshared dict object if\nmetadata return is attended (\\fBimage create\\fR command, \\fBconfigure\\fR\nsubcommand). The driver may set dict keys in this object to return\nmetadata.\nIf a match function succeeds, the metadataOut pointer is passed to the\ncorresponding read function.\n.PP\nA sample driver code snippet is:\n.CS\nif (NULL != metadataOut) {\n Tcl_DictObjPut(NULL, metadataOut, Tcl_NewStringObj(\"XMP\",-1),\n Tcl_NewStringObj(xmpMetadata));\n}\n.CE\n.PP\nThe metadata keys returned by the driver are merged into the present\nmetadata property of the image or into the metadata dict given by the\n\\fB\\-metadata\\fR command line option.\nAt the script level, the command \\fBimage create\\fR and the\n\\fBconfigure\\fR method may return metadata from the driver.\n.PP\nFormat string options or metadata keys may influence the creation of\nmetadata within the driver.\nFor example, the creation of an expensive metadata key may depend on a\nformat string option or on a metadata input key.\n.PP\n.VE 9.0\n.SH \"VERSION 2 INTERFACE\"\n.PP\nVersion 2 Interface does not include the possibility for the driver to\nuse the metadata dict for input or output.\n.SS SYNOPSIS\n\\fB#include \\fR\n.sp\n\\fBTk_CreatePhotoImageFormat\\fR(\\fIformatPtr\\fR)\n.SS ARGUMENTS\n.AS \"const Tk_PhotoImageFormat\" *formatPtr\n.AP \"const Tk_PhotoImageFormat\" *formatPtr in\nStructure that defines the new file format.\n.BE\n.SS DESCRIPTION\nA driver using the version 2 interface invokes \\fBTk_CreatePhotoImageFormat\\fR\nfor driver registration. The Tk_PhotoImageFormat structure\ncontains the following fields:\n.CS\ntypedef struct {\n const char *\\fIname\\fR;\n Tk_ImageFileMatchProc *\\fIfileMatchProc\\fR;\n Tk_ImageStringMatchProc *\\fIstringMatchProc\\fR;\n Tk_ImageFileReadProc *\\fIfileReadProc\\fR;\n Tk_ImageStringReadProc *\\fIstringReadProc\\fR;\n Tk_ImageFileWriteProc *\\fIfileWriteProc\\fR;\n Tk_ImageStringWriteProc *\\fIstringWriteProc\\fR;\n} \\fBTk_PhotoImageFormat\\fR;\n.CE\n.PP\n.SS FILEMATCHPROC\n.PP\n\\fIformatPtr->fileMatchProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageFileMatchProc\\fR(\n Tcl_Channel \\fIchan\\fR,\n const char *\\fIfileName\\fR,\n Tcl_Obj *\\fIformat\\fR,\n int *\\fIwidthPtr\\fR,\n int *\\fIheightPtr\\fR,\n Tcl_Interp *\\fIinterp\\fR);\n.CE\n.PP\n.SS STRINGMATCHPROC\n.PP\n\\fIformatPtr->stringMatchProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageStringMatchProc\\fR(\n Tcl_Obj *\\fIdata\\fR,\n Tcl_Obj *\\fIformat\\fR,\n int *\\fIwidthPtr\\fR,\n int *\\fIheightPtr\\fR,\n Tcl_Interp *\\fIinterp\\fR);\n.CE\n.SS FILEREADPROC\n.PP\n\\fIformatPtr->fileReadProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageFileReadProc\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tcl_Channel \\fIchan\\fR,\n const char *\\fIfileName\\fR,\n Tcl_Obj *\\fIformat\\fR,\n PhotoHandle \\fIimageHandle\\fR,\n int \\fIdestX\\fR, int \\fIdestY\\fR,\n int \\fIwidth\\fR, int \\fIheight\\fR,\n int \\fIsrcX\\fR, int \\fIsrcY\\fR);\n.CE\n.SS STRINGREADPROC\n.PP\n\\fIformatPtr->stringReadProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageStringReadProc\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tcl_Obj *\\fIdata\\fR,\n Tcl_Obj *\\fIformat\\fR,\n PhotoHandle \\fIimageHandle\\fR,\n int \\fIdestX\\fR, int \\fIdestY\\fR,\n int \\fIwidth\\fR, int \\fIheight\\fR,\n int \\fIsrcX\\fR, int \\fIsrcY\\fR);\n.CE\n.SS FILEWRITEPROC\n.PP\n\\fIformatPtr->fileWriteProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageFileWriteProc\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n const char *\\fIfileName\\fR,\n Tcl_Obj *\\fIformat\\fR,\n Tk_PhotoImageBlock *\\fIblockPtr\\fR);\n.CE\n.SS STRINGWRITEPROC\n.PP\n\\fIformatPtr->stringWriteProc\\fR must match the following prototype:\n.CS\ntypedef int \\fBTk_ImageStringWriteProc\\fR(\n Tcl_Interp *\\fIinterp\\fR,\n Tcl_Obj *\\fIformat\\fR,\n Tk_PhotoImageBlock *\\fIblockPtr\\fR);\n.CE\n.SH \"SEE ALSO\"\nTk_FindPhoto, Tk_PhotoPutBlock\n.SH KEYWORDS\nphoto image, image file\n" }, { "path": "doc/CrtSelHdlr.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CreateSelHandler 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreateSelHandler, Tk_DeleteSelHandler \\- arrange to handle requests for a selection\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_CreateSelHandler\\fR(\\fItkwin, selection, target, proc, clientData, format\\fR)\n.sp\n\\fBTk_DeleteSelHandler\\fR(\\fItkwin, selection, target\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_SelectionProc clientData\n.AP Tk_Window tkwin in\nWindow for which \\fIproc\\fR will provide selection information.\n.AP Atom selection in\nThe name of the selection for which \\fIproc\\fR will provide\nselection information.\n.AP Atom target in\nForm in which \\fIproc\\fR can provide the selection (e.g. STRING\nor FILE_NAME). Corresponds to \\fItype\\fR arguments in \\fBselection\\fR\ncommands.\n.AP Tk_SelectionProc *proc in\nProcedure to invoke whenever the selection is owned by \\fItkwin\\fR\nand the selection contents are requested in the format given by\n\\fItarget\\fR.\n.AP void *clientData in\nArbitrary one-word value to pass to \\fIproc\\fR.\n.AP Atom format in\nIf the selection requestor is not in this process, \\fIformat\\fR determines\nthe representation used to transmit the selection to its\nrequestor.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_CreateSelHandler\\fR arranges for a particular procedure\n(\\fIproc\\fR) to be called whenever \\fIselection\\fR is owned by\n\\fItkwin\\fR and the selection contents are requested in the\nform given by \\fItarget\\fR.\n\\fITarget\\fR should be one of\nthe entries defined in the left column of Table 2 of the\nX Inter-Client Communication Conventions Manual (ICCCM) or\nany other form in which an application is willing to present\nthe selection. The most common form is STRING.\n.PP\n\\fIProc\\fR should have arguments and result that match the\ntype \\fBTk_SelectionProc\\fR:\n.CS\ntypedef Tcl_Size \\fBTk_SelectionProc\\fR(\n void *\\fIclientData\\fR,\n Tcl_Size \\fIoffset\\fR,\n char *\\fIbuffer\\fR,\n Tcl_Size \\fImaxBytes\\fR);\n.CE\nThe \\fIclientData\\fR parameter to \\fIproc\\fR is a copy of the\n\\fIclientData\\fR argument given to \\fBTk_CreateSelHandler\\fR.\nTypically, \\fIclientData\\fR points to a data\nstructure containing application-specific information that is\nneeded to retrieve the selection. \\fIOffset\\fR specifies an\noffset position into the selection, \\fIbuffer\\fR specifies a\nlocation at which to copy information about the selection, and\n\\fImaxBytes\\fR specifies the amount of space available at\n\\fIbuffer\\fR. \\fIProc\\fR should place a NULL-terminated string\nat \\fIbuffer\\fR containing \\fImaxBytes\\fR or fewer characters\n(not including the terminating NULL), and it should return a\ncount of the number of non-NULL characters stored at\n\\fIbuffer\\fR. If the selection no longer exists (e.g. it once\nexisted but the user deleted the range of characters containing\nit), then \\fIproc\\fR should return \\-1.\n.PP\nWhen transferring large selections, Tk will break them up into\nsmaller pieces (typically a few thousand bytes each) for more\nefficient transmission. It will do this by calling \\fIproc\\fR\none or more times, using successively higher values of \\fIoffset\\fR\nto retrieve successive portions of the selection. If \\fIproc\\fR\nreturns a count less than \\fImaxBytes\\fR it means that the entire\nremainder of the selection has been returned. If \\fIproc\\fR's return\nvalue is \\fImaxBytes\\fR it means there may be additional information\nin the selection, so Tk must make another call to \\fIproc\\fR to\nretrieve the next portion.\n.PP\n\\fIProc\\fR always returns selection information in the form of a\ncharacter string. However, the ICCCM allows for information to\nbe transmitted from the selection owner to the selection requestor\nin any of several formats, such as a string, an array of atoms, an\narray of integers, etc. The \\fIformat\\fR argument to\n\\fBTk_CreateSelHandler\\fR indicates what format should be used to\ntransmit the selection to its requestor (see the middle column of\nTable 2 of the ICCCM for examples). If \\fIformat\\fR is not\nSTRING, then Tk will take the value returned by \\fIproc\\fR and divided\nit into fields separated by white space. If \\fIformat\\fR is ATOM,\nthen Tk will return the selection as an array of atoms, with each\nfield in \\fIproc\\fR's result treated as the name of one atom. For\nany other value of \\fIformat\\fR, Tk will return the selection as an\narray of 32-bit values where each field of \\fIproc\\fR's result is\ntreated as a number and translated to a 32-bit value. In any event,\nthe \\fIformat\\fR atom is returned to the selection requestor along\nwith the contents of the selection.\n.PP\nIf \\fBTk_CreateSelHandler\\fR is called when there already exists a\nhandler for \\fIselection\\fR and \\fItarget\\fR on \\fItkwin\\fR, then the\nexisting handler is replaced with a new one.\n.PP\n\\fBTk_DeleteSelHandler\\fR removes the handler given by \\fItkwin\\fR,\n\\fIselection\\fR, and \\fItarget\\fR, if such a handler exists.\nIf there is no such handler then it has no effect.\n.SH KEYWORDS\nformat, handler, selection, target\n" }, { "path": "doc/CrtWindow.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CreateWindow 3 4.2 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \\- create or delete window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Window\n\\fBTk_CreateWindow\\fR(\\fIinterp, parent, name, topLevScreen\\fR)\n.sp\nTk_Window\n\\fBTk_CreateAnonymousWindow\\fR(\\fIinterp, parent, topLevScreen\\fR)\n.sp\nTk_Window\n\\fBTk_CreateWindowFromPath\\fR(\\fIinterp, tkwin, pathName, topLevScreen\\fR)\n.sp\n\\fBTk_DestroyWindow\\fR(\\fItkwin\\fR)\n.sp\n\\fBTk_MakeWindowExist\\fR(\\fItkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tcl_Interp *topLevScreen\n.AP Tcl_Interp *interp out\nTcl interpreter to use for error reporting. If no error occurs,\nthen \\fI*interp\\fR is not modified.\n.AP Tk_Window parent in\nToken for the window that is to serve as the logical parent of\nthe new window.\n.AP \"const char\" *name in\nName to use for this window. Must be unique among all children of\nthe same \\fIparent\\fR.\n.AP \"const char\" *topLevScreen in\nHas same format as \\fIscreenName\\fR. If NULL, then new window is\ncreated as an internal window. If non-NULL, new window is created as\na top-level window on screen \\fItopLevScreen\\fR. If \\fItopLevScreen\\fR\nis an empty string\n.PQ \"\"\nthen new window is created as top-level window of \\fIparent\\fR's screen.\n.AP Tk_Window tkwin in\nToken for window.\n.AP \"const char\" *pathName in\nName of new window, specified as path name within application\n(e.g. \\fB.a.b.c\\fR).\n.BE\n.SH DESCRIPTION\n.PP\nThe procedures \\fBTk_CreateWindow\\fR,\n\\fBTk_CreateAnonymousWindow\\fR, and \\fBTk_CreateWindowFromPath\\fR\nare used to create new windows for\nuse in Tk-based applications. Each of the procedures returns a token\nthat can be used to manipulate the window in other calls to the Tk\nlibrary. If the window could not be created successfully, then NULL\nis returned and the result of interpreter \\fIinterp\\fR is modified to\nhold an error message.\n.PP\nTk supports two different kinds of windows: internal\nwindows and top-level windows.\nAn internal window is an interior window of a Tk application, such as a\nscrollbar or menu bar or button. A top-level window is one that is\ncreated as a child of a screen's root window, rather than as an\ninterior window, but which is logically part of some existing main\nwindow. Examples of top-level windows are pop-up menus and dialog boxes.\n.PP\nNew windows may be created by calling\n\\fBTk_CreateWindow\\fR. If the \\fItopLevScreen\\fR argument is\nNULL, then the new window will be an internal window. If\n\\fItopLevScreen\\fR is non-NULL, then the new window will be a\ntop-level window: \\fItopLevScreen\\fR indicates the name of\na screen and the new window will be created as a child of the\nroot window of \\fItopLevScreen\\fR. In either case Tk will\nconsider the new window to be the logical child of \\fIparent\\fR:\nthe new window's path name will reflect this fact, options may\nbe specified for the new window under this assumption, and so on.\nThe only difference is that new X window for a top-level window\nwill not be a child of \\fIparent\\fR's X window. For example, a pull-down\nmenu's \\fIparent\\fR would be the button-like window used to invoke it,\nwhich would in turn be a child of the menu bar window. A dialog box might\nhave the application's main window as its parent.\n.PP\n\\fBTk_CreateAnonymousWindow\\fR differs from \\fBTk_CreateWindow\\fR in\nthat it creates an unnamed window. This window will be manipulatable\nonly using C interfaces, and will not be visible to Tcl scripts. Both\ninterior windows and top-level windows may be created with\n\\fBTk_CreateAnonymousWindow\\fR.\n.PP\n\\fBTk_CreateWindowFromPath\\fR offers an alternate way of specifying\nnew windows. In \\fBTk_CreateWindowFromPath\\fR the new\nwindow is specified with a token for any window in the target\napplication (\\fItkwin\\fR), plus a path name for the new window.\nIt produces the same effect as \\fBTk_CreateWindow\\fR and allows\nboth top-level and internal windows to be created, depending on\nthe value of \\fItopLevScreen\\fR. In calls to \\fBTk_CreateWindowFromPath\\fR,\nas in calls to \\fBTk_CreateWindow\\fR, the parent of the new window\nmust exist at the time of the call, but the new window must not\nalready exist.\n.PP\nThe window creation procedures do not\nactually issue the command to X to create a window.\nInstead, they create a local data structure associated with\nthe window and defer the creation of the X window.\nThe window will actually be created by the first call to\n\\fBTk_MapWindow\\fR. Deferred window creation allows various\naspects of the window (such as its size, background color,\netc.) to be modified after its creation without incurring\nany overhead in the X server. When the window is finally\nmapped all of the window attributes can be set while creating\nthe window.\n.PP\nThe value returned by a window-creation procedure is not the\nX token for the window (it cannot be, since X has not been\nasked to create the window yet). Instead, it is a token\nfor Tk's local data structure for the window. Most\nof the Tk library procedures take Tk_Window tokens, rather\nthan X identifiers. The actual\nX window identifier can be retrieved from the local\ndata structure using the \\fBTk_WindowId\\fR macro; see\nthe manual entry for \\fBTk_WindowId\\fR for details.\n.PP\n\\fBTk_DestroyWindow\\fR deletes a window and all the data\nstructures associated with it, including any event handlers\ncreated with \\fBTk_CreateEventHandler\\fR. In addition,\n\\fBTk_DestroyWindow\\fR will delete any children of \\fItkwin\\fR\nrecursively (where children are defined in the Tk sense, consisting\nof all windows that were created with the given window as \\fIparent\\fR).\nIf \\fItkwin\\fR is an internal window, then event\nhandlers interested in destroy events\nare invoked immediately. If \\fItkwin\\fR is a top-level or main window,\nthen the event handlers will be invoked later, after X has seen\nthe request and returned an event for it.\n.PP\nIf a window has been created\nbut has not been mapped, so no X window exists, it is\npossible to force the creation of the X window by\ncalling \\fBTk_MakeWindowExist\\fR. This procedure issues\nthe X commands to instantiate the window given by \\fItkwin\\fR.\n.SH KEYWORDS\ncreate, deferred creation, destroy, display, internal window,\nscreen, top-level window, window\n" }, { "path": "doc/DeleteImg.3", "content": "'\\\"\n'\\\" Copyright (c) 1995-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_DeleteImage 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_DeleteImage \\- Destroy an image.\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_DeleteImage\\fR(\\fIinterp, name\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tcl_Interp *interp\n.AP Tcl_Interp *interp in\nInterpreter for which the image was created.\n.AP \"const char\" *name in\nName of the image.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_DeleteImage\\fR deletes the image given by \\fIinterp\\fR\nand \\fIname\\fR, if there is one. All instances of that image\nwill redisplay as empty regions. If the given image does not\nexist then the procedure has no effect.\n.SH KEYWORDS\ndelete image, image manager\n" }, { "path": "doc/DrawFocHlt.3", "content": "'\\\"\n'\\\" Copyright (c) 1995-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_DrawFocusHighlight 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_DrawFocusHighlight \\- draw the traversal highlight ring for a widget\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_DrawFocusHighlight\\fR(\\fItkwin, gc, width, drawable\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tcl_Interp\" *joinPtr\n.AP Tk_Window tkwin in\nWindow for which the highlight is being drawn. Used to retrieve\nthe window's dimensions, among other things.\n.AP GC gc in\nGraphics context to use for drawing the highlight.\n.AP int width in\nWidth of the highlight ring, in pixels.\n.AP Drawable drawable in\nDrawable in which to draw the highlight; usually an offscreen\npixmap for double buffering.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_DrawFocusHighlight\\fR is a utility procedure that draws the\ntraversal highlight ring for a widget.\nIt is typically invoked by widgets during redisplay.\n.SH KEYWORDS\nfocus, traversal highlight\n" }, { "path": "doc/EventHndlr.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_CreateEventHandler 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreateEventHandler, Tk_DeleteEventHandler, Tk_GetButtonMask, Tk_SendVirtualEvent \\- associate procedure callback with an X event\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_CreateEventHandler\\fR(\\fItkwin, mask, proc, clientData\\fR)\n.sp\n\\fBTk_DeleteEventHandler\\fR(\\fItkwin, mask, proc, clientData\\fR)\n.sp\n\\fBTk_GetButtonMask\\fR(\\fIbutton\\fR)\n.sp\n\\fBTk_SendVirtualEvent\\fR(\\fItkwin, eventName, detail\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"unsigned long\" clientData\n.AP unsigned button in\nButton number.\n.AP \"const char\" *eventName in\nThe name of the virtual event.\n.AP Tcl_Obj *detail in\nDetail information for the virtual event. May be NULL.\n.AP Tk_Window tkwin in\nToken for window in which events may occur.\n.AP \"unsigned long\" mask in\nBit-mask of events (such as \\fBButtonPressMask\\fR)\nfor which \\fIproc\\fR should be called.\n.AP Tk_EventProc *proc in\nProcedure to invoke whenever an event in \\fImask\\fR occurs\nin the window given by \\fItkwin\\fR.\n.AP void *clientData in\nArbitrary one-word value to pass to \\fIproc\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_CreateEventHandler\\fR arranges for \\fIproc\\fR to be\ninvoked in the future whenever one of the event types specified\nby \\fImask\\fR occurs in the window specified by \\fItkwin\\fR.\nThe callback to \\fIproc\\fR will be made by \\fBTk_HandleEvent\\fR;\nthis mechanism only works in programs that dispatch events\nthrough \\fBTk_HandleEvent\\fR (or through other Tk procedures that\ncall \\fBTk_HandleEvent\\fR, such as \\fBTcl_DoOneEvent\\fR or\n\\fBTk_MainLoop\\fR).\n.PP\n\\fIProc\\fR should have arguments and result that match the\ntype \\fBTk_EventProc\\fR:\n.CS\ntypedef void \\fBTk_EventProc\\fR(\n void *\\fIclientData\\fR,\n XEvent *\\fIeventPtr\\fR);\n.CE\nThe \\fIclientData\\fR parameter to \\fIproc\\fR is a copy of the \\fIclientData\\fR\nargument given to \\fBTk_CreateEventHandler\\fR when the callback\nwas created. Typically, \\fIclientData\\fR points to a data\nstructure containing application-specific information about\nthe window in which the event occurred. \\fIEventPtr\\fR is\na pointer to the X event, which will be one of the ones\nspecified in the \\fImask\\fR argument to \\fBTk_CreateEventHandler\\fR.\n.PP\n\\fBTk_DeleteEventHandler\\fR may be called to delete a\npreviously-created event handler: it deletes the first handler\nit finds that is associated with \\fItkwin\\fR and matches the\n\\fImask\\fR, \\fIproc\\fR, and \\fIclientData\\fR arguments. If\nno such handler exists, then \\fBTk_HandleEvent\\fR returns\nwithout doing anything. Although Tk supports it, it's probably\na bad idea to have more than one callback with the same \\fImask\\fR,\n\\fIproc\\fR, and \\fIclientData\\fR arguments.\nWhen a window is deleted all of its handlers will be deleted\nautomatically; in this case there is no need to call\n\\fBTk_DeleteEventHandler\\fR.\n.PP\nIf multiple handlers are declared for the same type of X event\non the same window, then the handlers will be invoked in the\norder they were created.\n.PP\n\\fBTk_GetButtonMask\\fR returns the button mask corresponding to\nthe button. E.g it will return \\fIButton1Mask\\fR for button \\fIButton1\\fR.\n.PP\n\\fBTk_SendVirtualEvent\\fR sends a virtual event to Tk's event queue.\n.SH KEYWORDS\nbind, callback, event, handler\n" }, { "path": "doc/FindPhoto.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Australian National University\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n'\\\" Author: Paul Mackerras (paulus@cs.anu.edu.au),\n'\\\"\t Department of Computer Science,\n'\\\"\t Australian National University.\n'\\\"\n.TH Tk_FindPhoto 3 8.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize \\- manipulate the image data stored in a photo image.\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_PhotoHandle\n\\fBTk_FindPhoto\\fR(\\fIinterp, imageName\\fR)\n.sp\nint\n\\fBTk_PhotoPutBlock\\fR(\\fIinterp, handle, blockPtr, x, y, width, height,\\\ncompRule\\fR)\n.sp\nint\n\\fBTk_PhotoPutZoomedBlock\\fR(\\fIinterp, handle, blockPtr, x, y, width, height,\\\nzoomX, zoomY, subsampleX, subsampleY, compRule\\fR)\n.sp\nint\n\\fBTk_PhotoGetImage\\fR(\\fIhandle, blockPtr\\fR)\n.sp\n\\fBTk_PhotoBlank\\fR(\\fIhandle\\fR)\n.sp\nint\n\\fBTk_PhotoExpand\\fR(\\fIinterp, handle, width, height\\fR)\n.sp\n\\fBTk_PhotoGetSize\\fR(\\fIhandle, widthPtr, heightPtr\\fR)\n.sp\nint\n\\fBTk_PhotoSetSize\\fR(\\fIinterp. handle, width, height\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_PhotoImageBlock window_path\n.AP Tcl_Interp *interp in\nInterpreter in which image was created and in which error reporting is\nto be done.\n.AP \"const char\" *imageName in\nName of the photo image.\n.AP Tk_PhotoHandle handle in\nOpaque handle identifying the photo image to be affected.\n.AP Tk_PhotoImageBlock *blockPtr in\nSpecifies the address and storage layout of image data.\n.AP int x in\nSpecifies the X coordinate where the top-left corner of the block is\nto be placed within the image.\n.AP int y in\nSpecifies the Y coordinate where the top-left corner of the block is\nto be placed within the image.\n.AP int width in\nSpecifies the width of the image area to be affected (for\n\\fBTk_PhotoPutBlock\\fR) or the desired image width (for\n\\fBTk_PhotoExpand\\fR and \\fBTk_PhotoSetSize\\fR).\n.AP int compRule in\nSpecifies the compositing rule used when combining transparent pixels\nin a block of data with a photo image. Must be one of\n\\fBTK_PHOTO_COMPOSITE_OVERLAY\\fR (which puts the block of data over the top\nof the existing photo image, with the previous contents showing\nthrough in the transparent bits) or \\fBTK_PHOTO_COMPOSITE_SET\\fR (which\ndiscards the existing photo image contents in the rectangle covered by\nthe data block.)\n.AP int height in\nSpecifies the height of the image area to be affected (for\n\\fBTk_PhotoPutBlock\\fR) or the desired image height (for\n\\fBTk_PhotoExpand\\fR and \\fBTk_PhotoSetSize\\fR).\n.AP int *widthPtr out\nPointer to location in which to store the image width.\n.AP int *heightPtr out\nPointer to location in which to store the image height.\n.AP int subsampleX in\nSpecifies the subsampling factor in the X direction for input\nimage data.\n.AP int subsampleY in\nSpecifies the subsampling factor in the Y direction for input\nimage data.\n.AP int zoomX in\nSpecifies the zoom factor to be applied in the X direction to pixels\nbeing written to the photo image.\n.AP int zoomY in\nSpecifies the zoom factor to be applied in the Y direction to pixels\nbeing written to the photo image.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_FindPhoto\\fR returns an opaque handle that is used to identify a\nparticular photo image to the other procedures. The parameter is the\nname of the image, that is, the name specified to the \\fBimage create\nphoto\\fR command, or assigned by that command if no name was specified.\nIf \\fIimageName\\fR does not exist or is not a photo image,\n\\fBTk_FindPhoto\\fR returns NULL.\n.PP\n\\fBTk_PhotoPutBlock\\fR is used to supply blocks of image data to be\ndisplayed. The call affects an area of the image of size\n\\fIwidth\\fR x \\fIheight\\fR pixels, with its top-left corner at\ncoordinates (\\fIx\\fR,\\fIy\\fR). All of \\fIwidth\\fR, \\fIheight\\fR,\n\\fIx\\fR, and \\fIy\\fR must be non-negative.\nIf part of this area lies outside the\ncurrent bounds of the image, the image will be expanded to include the\narea, unless the user has specified an explicit image size with the\n\\fB\\-width\\fR and/or \\fB\\-height\\fR widget configuration options\n(see photo(n)); in that\ncase the area is silently clipped to the image boundaries.\n.PP\nThe \\fIblock\\fR parameter is a pointer to a\n\\fBTk_PhotoImageBlock\\fR structure, defined as follows:\n.CS\ntypedef struct {\n unsigned char *\\fIpixelPtr\\fR;\n int \\fIwidth\\fR;\n int \\fIheight\\fR;\n int \\fIpitch\\fR;\n int \\fIpixelSize\\fR;\n int \\fIoffset\\fR[4];\n} \\fBTk_PhotoImageBlock\\fR;\n.CE\nThe \\fIpixelPtr\\fR field points to the first pixel, that is, the\ntop-left pixel in the block.\nThe \\fIwidth\\fR and \\fIheight\\fR fields specify the dimensions of the\nblock of pixels. The \\fIpixelSize\\fR field specifies the address\ndifference between two horizontally adjacent pixels. It should be 4 for\nRGB and 2 for grayscale image data. Other values are possible, if the\noffsets in the \\fIoffset\\fR array are adjusted accordingly (e.g. for\nred, green and blue data stored in different planes). Using such a\nlayout is strongly discouraged, though. Due to a bug, it might not work\ncorrectly if an alpha channel is provided. (see the \\fBBUGS\\fR section\nbelow). The \\fIpitch\\fR field specifies the\naddress difference between two vertically adjacent pixels. The\n\\fIoffset\\fR array contains the offsets from the address of a pixel\nto the addresses of the bytes containing the red, green, blue and alpha\n(transparency) components. If the offsets for red, green and blue are\nequal, the image is interpreted as grayscale. If they differ, RGB data\nis assumed. Normally the offsets will be 0, 1, 2, 3 for RGB data\nand 0, 0, 0, 1 for grayscale. It is possible to provide image data\nwithout an alpha channel by setting the offset for alpha to a negative\nvalue and adjusting the \\fIpixelSize\\fR field accordingly. This use is\ndiscouraged, though (see the \\fBBUGS\\fR section below).\n.PP\nThe \\fIcompRule\\fR parameter to \\fBTk_PhotoPutBlock\\fR specifies a\ncompositing rule that says what to do with transparent pixels. The\nvalue \\fBTK_PHOTO_COMPOSITE_OVERLAY\\fR says that the previous contents of\nthe photo image should show through, and the value\n\\fBTK_PHOTO_COMPOSITE_SET\\fR says that the previous contents of the photo\nimage should be completely ignored, and the values from the block be\ncopied directly across. The behavior in Tk8.3 and earlier was\nequivalent to having \\fBTK_PHOTO_COMPOSITE_OVERLAY\\fR as a compositing rule.\n.PP\nThe value given for the \\fIwidth\\fR and \\fIheight\\fR parameters to\n\\fBTk_PhotoPutBlock\\fR do not have to correspond to the values specified\nin \\fIblock\\fR. If they are smaller, \\fBTk_PhotoPutBlock\\fR extracts a\nsub-block from the image data supplied. If they are larger, the data\ngiven are replicated (in a tiled fashion) to fill the specified area.\nThese rules operate independently in the horizontal and vertical\ndirections.\n.PP\n\\fBTk_PhotoPutBlock\\fR normally returns \\fBTCL_OK\\fR, though if it cannot\nallocate sufficient memory to hold the resulting image, \\fBTCL_ERROR\\fR is\nreturned instead and, if the \\fIinterp\\fR argument is non-NULL, an\nerror message is placed in the interpreter's result.\n.PP\n\\fBTk_PhotoPutZoomedBlock\\fR works like \\fBTk_PhotoPutBlock\\fR except that\nthe image can be reduced or enlarged for display. The\n\\fIsubsampleX\\fR and \\fIsubsampleY\\fR parameters allow the size of the\nimage to be reduced by subsampling.\n\\fBTk_PhotoPutZoomedBlock\\fR will use only pixels from the input image\nwhose X coordinates are multiples of \\fIsubsampleX\\fR, and whose Y\ncoordinates are multiples of \\fIsubsampleY\\fR. For example, an image\nof 512x512 pixels can be reduced to 256x256 by setting\n\\fIsubsampleX\\fR and \\fIsubsampleY\\fR to 2.\n.PP\nThe \\fIzoomX\\fR and \\fIzoomY\\fR parameters allow the image to be\nenlarged by pixel replication. Each pixel of the (possibly subsampled)\ninput image will be written to a block \\fIzoomX\\fR pixels wide and\n\\fIzoomY\\fR pixels high of the displayed image. Subsampling and\nzooming can be used together for special effects.\n.PP\n\\fBTk_PhotoGetImage\\fR can be used to retrieve image data from a photo\nimage. \\fBTk_PhotoGetImage\\fR fills\nin the structure pointed to by the \\fIblockPtr\\fR parameter with values\nthat describe the address and layout of the image data that the\nphoto image has stored internally. The values are valid\nuntil the image is destroyed or its size is changed.\n.PP\nIt is possible to modify an image by writing directly to the data\nthe \\fIpixelPtr\\fR field points to. The size of the image cannot be\nchanged this way, though.\nAlso, changes made by writing directly to \\fIpixelPtr\\fR will not be\nimmediately visible, but only after a call to\n\\fBTk_ImageChanged\\fR or after an event that causes the interested\nwidgets to redraw themselves.\nFor these reasons usually it is preferable to make changes to\na copy of the image data and write it back with\n\\fBTk_PhotoPutBlock\\fR or \\fBTk_PhotoPutZoomedBlock\\fR.\n.PP\n\\fBTk_PhotoGetImage\\fR returns 1 for compatibility with the\ncorresponding procedure in the old photo widget.\n.PP\n\\fBTk_PhotoBlank\\fR blanks the entire area of the\nphoto image. Blank areas of a photo image are transparent.\n.PP\n\\fBTk_PhotoExpand\\fR requests that the widget's image be expanded to be\nat least \\fIwidth\\fR x \\fIheight\\fR pixels in size. The width and/or\nheight are unchanged if the user has specified an explicit image width\nor height with the \\fB\\-width\\fR and/or \\fB\\-height\\fR configuration\noptions, respectively.\nIf the image data\nare being supplied in many small blocks, it is more efficient to use\n\\fBTk_PhotoExpand\\fR or \\fBTk_PhotoSetSize\\fR at the beginning rather than\nallowing the image to expand in many small increments as image blocks\nare supplied.\n.PP\n\\fBTk_PhotoExpand\\fR normally returns \\fBTCL_OK\\fR, though if it cannot\nallocate sufficient memory to hold the resulting image, \\fBTCL_ERROR\\fR is\nreturned instead and, if the \\fIinterp\\fR argument is non-NULL, an\nerror message is placed in the interpreter's result.\n.PP\n\\fBTk_PhotoSetSize\\fR specifies the size of the image, as if the user\nhad specified the given \\fIwidth\\fR and \\fIheight\\fR values to the\n\\fB\\-width\\fR and \\fB\\-height\\fR configuration options. A value of\nzero for \\fIwidth\\fR or \\fIheight\\fR does not change the image's width\nor height, but allows the width or height to be changed by subsequent\ncalls to \\fBTk_PhotoPutBlock\\fR, \\fBTk_PhotoPutZoomedBlock\\fR or\n\\fBTk_PhotoExpand\\fR.\n.PP\n\\fBTk_PhotoSetSize\\fR normally returns \\fBTCL_OK\\fR, though if it cannot\nallocate sufficient memory to hold the resulting image, \\fBTCL_ERROR\\fR is\nreturned instead and, if the \\fIinterp\\fR argument is non-NULL, an\nerror message is placed in the interpreter's result.\n.PP\n\\fBTk_PhotoGetSize\\fR returns the dimensions of the image in\n*\\fIwidthPtr\\fR and *\\fIheightPtr\\fR.\n.SH PORTABILITY\n.PP\nIn Tk 8.3 and earlier, \\fBTk_PhotoPutBlock\\fR and\n\\fBTk_PhotoPutZoomedBlock\\fR had different signatures. If you want to\ncompile code that uses the old interface against 8.4 without updating\nyour code, compile it with the flag\n-DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK. Code linked using Stubs against\nolder versions of Tk will continue to work.\n.PP\nIn Tk 8.4, \\fBTk_PhotoPutBlock\\fR, \\fBTk_PhotoPutZoomedBlock\\fR,\n\\fBTk_PhotoExpand\\fR and \\fBTk_PhotoSetSize\\fR did not take an\n\\fIinterp\\fR argument or return any result code. If insufficient\nmemory was available for an image, Tk would panic. This behaviour is\nstill supported if you compile your extension with the additional flag\n-DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE. Code linked using Stubs against\nolder versions of Tk will continue to work.\n.SH BUGS\nThe \\fBTk_PhotoImageBlock\\fR structure used to provide image data to\n\\fBTk_PhotoPutBlock\\fR promises great flexibility in the layout of the\ndata (e.g. separate planes for the red, green, blue and alpha\nchannels). Unfortunately, the implementation fails to hold this\npromise. The problem is that the \\fIpixelSize\\fR field is\n(incorrectly) used to determine whether the image has an alpha channel.\nCurrently, if the offset for the alpha channel is greater than or equal to\n\\fIpixelSize\\fR, \\fBtk_PhotoPutblock\\fR assumes no alpha data is\npresent and makes the image fully opaque. This means that for layouts\nwhere the channels are separate (or any other exotic layout where\n\\fIpixelSize\\fR has to be smaller than the alpha offset), the alpha\nchannel will not be read correctly. In order to be on the safe side\nif this issue will be corrected in a future release, it is strongly\nrecommended you always provide alpha data - even if the image has no\ntransparency - and only use the \"standard\" layout with a\n\\fIpixelSize\\fR of 2 for grayscale and 4 for RGB data with\n\\fIoffset\\fRs of 0, 0, 0, 1 or 0, 1, 2, 3 respectively.\n.SH CREDITS\n.PP\nThe code for the photo image type was developed by Paul Mackerras,\nbased on his earlier photo widget code.\n.SH KEYWORDS\nphoto, image\n" }, { "path": "doc/FontId.3", "content": "'\\\"\n'\\\" Copyright (c) 1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_FontId 3 8.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \\- accessor functions for\nfonts\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nFont\n\\fBTk_FontId\\fR(\\fItkfont\\fR)\n.sp\n\\fBTk_GetFontMetrics\\fR(\\fItkfont, fmPtr\\fR)\n.sp\nint\n\\fBTk_PostscriptFontName\\fR(\\fItkfont, dsPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_FontMetrics *dsPtr\n.AP Tk_Font tkfont in\nOpaque font token being queried. Must have been returned by a previous\ncall to \\fBTk_GetFont\\fR.\n.AP Tk_FontMetrics *fmPtr out\nPointer to structure in which the font metrics for \\fItkfont\\fR will\nbe stored. See \\fBDATA STRUCTURES\\fR below for details.\n.AP Tcl_DString *dsPtr out\nPointer to an initialized \\fBTcl_DString\\fR to which the name of the\nPostscript font that corresponds to \\fItkfont\\fR will be appended.\n.BE\n.SH DESCRIPTION\n.PP\nGiven a \\fItkfont\\fR, \\fBTk_FontId\\fR returns the token that should be\nselected into an XGCValues structure in order to construct a graphics\ncontext that can be used to draw text in the specified font.\n.PP\n\\fBTk_GetFontMetrics\\fR computes the ascent, descent, and linespace of the\n\\fItkfont\\fR in pixels and stores those values in the structure pointer to by\n\\fIfmPtr\\fR. These values can be used in computations such as to space\nmultiple lines of text, to align the baselines of text in different\nfonts, and to vertically align text in a given region. See the\ndocumentation for the \\fBfont\\fR command for definitions of the terms\nascent, descent, and linespace, used in font metrics.\n.PP\n\\fBTk_PostscriptFontName\\fR maps a \\fItkfont\\fR to the corresponding\nPostscript font name that should be used when printing. The return value\nis the size in points of the \\fItkfont\\fR and the Postscript font name is\nappended to \\fIdsPtr\\fR. \\fIDsPtr\\fR must refer to an initialized\n\\fBTcl_DString\\fR. Given a\n.QW reasonable\nPostscript printer, the\nfollowing screen font families should print correctly:\n.IP\n\\fBAvant Garde\\fR, \\fBArial\\fR, \\fBBookman\\fR, \\fBCourier\\fR,\n\\fBCourier New\\fR, \\fBGeneva\\fR, \\fBHelvetica\\fR, \\fBMonaco\\fR,\n\\fBNew Century Schoolbook\\fR, \\fBNew York\\fR, \\fBPalatino\\fR, \\fBSymbol\\fR,\n\\fBTimes\\fR, \\fBTimes New Roman\\fR, \\fBZapf Chancery\\fR, and\n\\fBZapf Dingbats\\fR.\n.PP\nAny other font families may not print correctly because the computed\nPostscript font name may be incorrect or not exist on the printer.\n.SH \"DATA STRUCTURES\"\n.PP\nThe \\fBTk_FontMetrics\\fR data structure is used by \\fBTk_GetFontMetrics\\fR to\nreturn information about a font and is defined as follows:\n.CS\ntypedef struct {\n int \\fIascent\\fR;\n int \\fIdescent\\fR;\n int \\fIlinespace\\fR;\n} \\fBTk_FontMetrics\\fR;\n.CE\n.PP\nThe \\fIascent\\fR field is the amount in pixels that the tallest\nletter sticks up above the baseline, plus any extra blank space added\nby the designer of the font.\n.PP\nThe \\fIdescent\\fR is the largest amount in pixels that any letter\nsticks below the baseline, plus any extra blank space added by the\ndesigner of the font.\n.PP\nThe \\fIlinespace\\fR is the sum of the ascent and descent. How far\napart two lines of text in the same font should be placed so that none\nof the characters in one line overlap any of the characters in the\nother line.\n.SH \"SEE ALSO\"\nfont(n), MeasureChar(3)\n.SH KEYWORDS\nfont, measurement, Postscript\n" }, { "path": "doc/GeomReq.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GeometryRequest 3 \"8.4\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GeometryRequest, Tk_SetMinimumRequestSize, Tk_SetInternalBorder, Tk_SetInternalBorderEx \\- specify desired geometry or internal border for a window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_GeometryRequest\\fR(\\fItkwin, reqWidth, reqHeight\\fR)\n.sp\n\\fBTk_SetMinimumRequestSize\\fR(\\fItkwin, minWidth, minHeight\\fR)\n.sp\n\\fBTk_SetInternalBorder\\fR(\\fItkwin, width\\fR)\n.sp\n\\fBTk_SetInternalBorderEx\\fR(\\fItkwin, left, right, top, bottom\\fR)\n.fi\n.SH ARGUMENTS\n.AS baseHeight clientData\n.AP Tk_Window tkwin in\nWindow for which geometry is being requested.\n.AP int reqWidth in\nDesired width for \\fItkwin\\fR, in pixel units.\n.AP int reqHeight in\nDesired height for \\fItkwin\\fR, in pixel units.\n.AP int minWidth in\nDesired minimum requested width for \\fItkwin\\fR, in pixel units.\n.AP int minHeight in\nDesired minimum requested height for \\fItkwin\\fR, in pixel units.\n.AP int width in\nSpace to leave for internal border for \\fItkwin\\fR, in pixel units.\n.AP int left in\nSpace to leave for left side of internal border for \\fItkwin\\fR,\nin pixel units.\n.AP int right in\nSpace to leave for right side of internal border for \\fItkwin\\fR,\nin pixel units.\n.AP int top in\nSpace to leave for top side of internal border for \\fItkwin\\fR,\nin pixel units.\n.AP int bottom in\nSpace to leave for bottom side of internal border for \\fItkwin\\fR,\nin pixel units.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GeometryRequest\\fR is called by widget code to indicate its\npreference for the dimensions of a particular window. The arguments\nto \\fBTk_GeometryRequest\\fR are made available to the geometry\nmanager for the window, which then decides on the actual geometry\nfor the window. Although geometry managers generally try to satisfy\nrequests made to \\fBTk_GeometryRequest\\fR, there is no guarantee that\nthis will always be possible. Widget code should not assume that\na geometry request will be satisfied until it receives a\n\\fBConfigureNotify\\fR event indicating that the geometry change has\noccurred. Widget code should never call procedures like\n\\fBTk_ResizeWindow\\fR directly. Instead, it should invoke\n\\fBTk_GeometryRequest\\fR and leave the final geometry decisions to\nthe geometry manager.\n.PP\nIf \\fItkwin\\fR is a top-level window, then the geometry information\nwill be passed to the window manager using the standard ICCCM protocol.\n.PP\n\\fBTk_SetInternalBorder\\fR is called by widget code to indicate that\nthe widget has an internal border. This means that the widget draws\na decorative border inside the window instead of using the standard\nX borders, which are external to the window's area. For example,\ninternal borders are used to draw 3-D effects. \\fIWidth\\fR\nspecifies the width of the border in pixels. Geometry managers will\nuse this information to avoid placing any children of \\fItkwin\\fR\noverlapping the outermost \\fIwidth\\fR pixels of \\fItkwin\\fR's area.\n.PP\n\\fBTk_SetInternalBorderEx\\fR works like \\fBTk_SetInternalBorder\\fR\nbut lets you specify different widths for different sides of the window.\n.PP\n\\fBTk_SetMinimumRequestSize\\fR is called by widget code to indicate\nthat a geometry manager should request at least this size for the\nwidget. This allows a widget to have some control over its size when\na propagating geometry manager is used inside it.\n.PP\nThe information specified in calls to \\fBTk_GeometryRequest\\fR,\n\\fBTk_SetMinimumRequestSize\\fR, \\fBTk_SetInternalBorder\\fR and\n\\fBTk_SetInternalBorderEx\\fR can be retrieved using the macros\n\\fBTk_ReqWidth\\fR, \\fBTk_ReqHeight\\fR, \\fBTk_MinReqWidth\\fR,\n\\fBTk_MinReqHeight\\fR, \\fBTk_MinReqWidth\\fR, \\fBTk_InternalBorderLeft\\fR,\n\\fBTk_InternalBorderRight\\fR, \\fBTk_InternalBorderTop\\fR and\n\\fBTk_InternalBorderBottom\\fR.\nSee the \\fBTk_WindowId\\fR manual entry for details.\n.SH KEYWORDS\ngeometry, request\n" }, { "path": "doc/GetAnchor.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1998 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetAnchorFromObj 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \\- translate between strings and anchor positions\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_GetAnchorFromObj\\fR(\\fIinterp, objPtr, anchorPtr\\fR)\n.sp\nint\n\\fBTk_GetAnchor\\fR(\\fIinterp, string, anchorPtr\\fR)\n.sp\nconst char *\n\\fBTk_NameOfAnchor\\fR(\\fIanchor\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tk_Anchor\" *anchorPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting, or NULL.\n.AP Tcl_Obj *objPtr in/out\nString value contains name of anchor point:\n.QW \\fBn\\fR ,\n.QW \\fBne\\fR ,\n.QW \\fBe\\fR ,\n.QW \\fBse\\fR ,\n.QW \\fBs\\fR ,\n.QW \\fBsw\\fR ,\n.QW \\fBw\\fR ,\n.QW \\fBnw\\fR ,\nor\n.QW \\fBcenter\\fR ;\ninternal rep will be modified to cache corresponding Tk_Anchor. In the\ncase of\n.QW \\fBcenter\\fR\non input, a non-empty abbreviation of it may also be used on input.\n.AP \"const char\" *string in\nSame as \\fIobjPtr\\fR except description of anchor point is passed as\na string.\n.AP int *anchorPtr out\nPointer to location in which to store anchor position corresponding to\n\\fIobjPtr\\fR or \\fIstring\\fR.\n.AP Tk_Anchor anchor in\nAnchor position, e.g. \\fBTCL_ANCHOR_CENTER\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetAnchorFromObj\\fR places in \\fI*anchorPtr\\fR an anchor position\n(enumerated type \\fBTk_Anchor\\fR)\ncorresponding to \\fIobjPtr\\fR's value. The result will be one of\n\\fBTK_ANCHOR_N\\fR, \\fBTK_ANCHOR_NE\\fR, \\fBTK_ANCHOR_E\\fR, \\fBTK_ANCHOR_SE\\fR,\n\\fBTK_ANCHOR_S\\fR, \\fBTK_ANCHOR_SW\\fR, \\fBTK_ANCHOR_W\\fR, \\fBTK_ANCHOR_NW\\fR,\nor \\fBTK_ANCHOR_CENTER\\fR.\nAnchor positions are typically used for indicating a point on an object\nthat will be used to position the object, e.g. \\fBTK_ANCHOR_N\\fR means\nposition the top center point of the object at a particular place.\n.PP\nUnder normal circumstances the return value is \\fBTCL_OK\\fR and\n\\fIinterp\\fR is unused.\nIf \\fIstring\\fR does not contain a valid anchor position\nor an abbreviation of one of these names, \\fBTCL_ERROR\\fR is returned,\n\\fI*anchorPtr\\fR is unmodified, and an error message is\nstored in \\fIinterp\\fR's result if \\fIinterp\\fR is not NULL.\n\\fBTk_GetAnchorFromObj\\fR caches information about the return\nvalue in \\fIobjPtr\\fR, which speeds up future calls to\n\\fBTk_GetAnchorFromObj\\fR with the same \\fIobjPtr\\fR.\n.PP\n\\fBTk_GetAnchor\\fR is identical to \\fBTk_GetAnchorFromObj\\fR except\nthat the description of the anchor is specified with a string instead\nof an object. This prevents \\fBTk_GetAnchor\\fR from caching the\nreturn value, so \\fBTk_GetAnchor\\fR is less efficient than\n\\fBTk_GetAnchorFromObj\\fR.\n.PP\n\\fBTk_NameOfAnchor\\fR is the logical inverse of \\fBTk_GetAnchor\\fR.\nGiven an anchor position such as \\fBTK_ANCHOR_N\\fR it returns a\nstatically-allocated string corresponding to \\fIanchor\\fR.\nIf \\fIanchor\\fR is not a legal anchor value, then\n.QW \"unknown anchor position\"\nis returned.\n.SH KEYWORDS\nanchor position\n" }, { "path": "doc/GetBitmap.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1998 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_AllocBitmapFromObj 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \\- maintain database of single-plane pixmaps\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nPixmap\n\\fBTk_AllocBitmapFromObj\\fR(\\fIinterp, tkwin, objPtr\\fR)\n.sp\nPixmap\n\\fBTk_GetBitmap\\fR(\\fIinterp, tkwin, info\\fR)\n.sp\nPixmap\n\\fBTk_GetBitmapFromObj\\fR(\\fItkwin, objPtr\\fR)\n.sp\nint\n\\fBTk_DefineBitmap\\fR(\\fIinterp, name, source, width, height\\fR)\n.sp\nconst char *\n\\fBTk_NameOfBitmap\\fR(\\fIdisplay, bitmap\\fR)\n.sp\n\\fBTk_SizeOfBitmap\\fR(\\fIdisplay, bitmap, widthPtr, heightPtr\\fR)\n.sp\n\\fBTk_FreeBitmapFromObj\\fR(\\fItkwin, objPtr\\fR)\n.sp\n\\fBTk_FreeBitmap\\fR(\\fIdisplay, bitmap\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"unsigned long\" *pixelPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting; if NULL then no error message\nis left after errors.\n.AP Tk_Window tkwin in\nToken for window in which the bitmap will be used.\n.AP Tcl_Obj *objPtr in/out\nString value describes desired bitmap; internal rep will be\nmodified to cache pointer to corresponding Pixmap.\n.AP \"const char\" *info in\nSame as \\fIobjPtr\\fR except description of bitmap is passed as a string and\nresulting Pixmap is not cached.\n.AP \"const char\" *name in\nName for new bitmap to be defined.\n.AP \"const void\" *source in\nData for bitmap, in standard bitmap format.\nMust be stored in static memory whose value will never change.\n.AP \"int\" width in\nWidth of bitmap.\n.AP \"int\" height in\nHeight of bitmap.\n.AP \"int\" *widthPtr out\nPointer to word to fill in with \\fIbitmap\\fR's width.\n.AP \"int\" *heightPtr out\nPointer to word to fill in with \\fIbitmap\\fR's height.\n.AP Display *display in\nDisplay for which \\fIbitmap\\fR was allocated.\n.AP Pixmap bitmap in\nIdentifier for a bitmap allocated by \\fBTk_AllocBitmapFromObj\\fR or\n\\fBTk_GetBitmap\\fR.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures manage a collection of bitmaps (one-plane pixmaps)\nbeing used by an application. The procedures allow bitmaps to be\nre-used efficiently, thereby avoiding server overhead, and also\nallow bitmaps to be named with character strings.\n.PP\n\\fBTk_AllocBitmapFromObj\\fR returns a Pixmap identifier for a bitmap\nthat matches the description in \\fIobjPtr\\fR and is suitable for use\nin \\fItkwin\\fR. It re-uses an existing bitmap, if possible, and\ncreates a new one otherwise. \\fIObjPtr\\fR's value must have one\nof the following forms:\n.TP 20\n\\fB@\\fIfileName\\fR\n.\n\\fIFileName\\fR must be the name of a file containing a bitmap\ndescription in the standard X11 format.\n.TP 20\n\\fIname\\fR\n.\n\\fIName\\fR must be the name of a bitmap defined previously with\na call to \\fBTk_DefineBitmap\\fR. The following names are pre-defined\nby Tk:\n.RS\n.IP \\fBerror\\fR 12\nThe international\n.QW don't\nsymbol: a circle with a diagonal line across it.\n.IP \\fBgray75\\fR 12\n75% gray: a checkerboard pattern where three out of four bits are on.\n.IP \\fBgray50\\fR 12\n50% gray: a checkerboard pattern where every other bit is on.\n.IP \\fBgray25\\fR 12\n25% gray: a checkerboard pattern where one out of every four bits is on.\n.IP \\fBgray12\\fR 12\n12.5% gray: a pattern where one-eighth of the bits are on, consisting of\nevery fourth pixel in every other row.\n.IP \\fBhourglass\\fR 12\nAn hourglass symbol.\n.IP \\fBinfo\\fR 12\nA large letter\n.QW i .\n.IP \\fBquesthead\\fR 12\nThe silhouette of a human head, with a question mark in it.\n.IP \\fBquestion\\fR 12\nA large question-mark.\n.IP \\fBwarning\\fR 12\nA large exclamation point.\n.PP\nIn addition, the following pre-defined names are available only on the\n\\fBMacintosh\\fR platform:\n.IP \\fBdocument\\fR 12\nA generic document.\n.IP \\fBstationery\\fR 12\nDocument stationery.\n.IP \\fBedition\\fR 12\nThe \\fIedition\\fR symbol.\n.IP \\fBapplication\\fR 12\nGeneric application icon.\n.IP \\fBaccessory\\fR 12\nA desk accessory.\n.IP \\fBfolder\\fR 12\nGeneric folder icon.\n.IP \\fBpfolder\\fR 12\nA locked folder.\n.IP \\fBtrash\\fR 12\nA trash can.\n.IP \\fBfloppy\\fR 12\nA floppy disk.\n.IP \\fBramdisk\\fR 12\nA floppy disk with chip.\n.IP \\fBcdrom\\fR 12\nA cd disk icon.\n.IP \\fBpreferences\\fR 12\nA folder with prefs symbol.\n.IP \\fBquerydoc\\fR 12\nA database document icon.\n.IP \\fBstop\\fR 12\nA stop sign.\n.IP \\fBnote\\fR 12\nA face with balloon words.\n.IP \\fBcaution\\fR 12\nA triangle with an exclamation point.\n.RE\n.LP\nUnder normal conditions, \\fBTk_AllocBitmapFromObj\\fR\nreturns an identifier for the requested bitmap. If an error\noccurs in creating the bitmap, such as when \\fIobjPtr\\fR refers\nto a non-existent file, then \\fBNone\\fR is returned and an error\nmessage is left in \\fIinterp\\fR's result if \\fIinterp\\fR is not\nNULL. \\fBTk_AllocBitmapFromObj\\fR caches information about the return\nvalue in \\fIobjPtr\\fR, which speeds up future calls to procedures\nsuch as \\fBTk_AllocBitmapFromObj\\fR and \\fBTk_GetBitmapFromObj\\fR.\n.PP\n\\fBTk_GetBitmap\\fR is identical to \\fBTk_AllocBitmapFromObj\\fR except\nthat the description of the bitmap is specified with a string instead\nof an object. This prevents \\fBTk_GetBitmap\\fR from caching the\nreturn value, so \\fBTk_GetBitmap\\fR is less efficient than\n\\fBTk_AllocBitmapFromObj\\fR.\n.PP\n\\fBTk_GetBitmapFromObj\\fR returns the token for an existing bitmap, given\nthe window and description used to create the bitmap.\n\\fBTk_GetBitmapFromObj\\fR does not actually create the bitmap; the bitmap\nmust already have been created with a previous call to\n\\fBTk_AllocBitmapFromObj\\fR or \\fBTk_GetBitmap\\fR. The return\nvalue is cached in \\fIobjPtr\\fR, which speeds up\nfuture calls to \\fBTk_GetBitmapFromObj\\fR with the same \\fIobjPtr\\fR\nand \\fItkwin\\fR.\n.PP\n\\fBTk_DefineBitmap\\fR associates a name with\nin-memory bitmap data so that the name can be used in later\ncalls to \\fBTk_AllocBitmapFromObj\\fR or \\fBTk_GetBitmap\\fR. The \\fInameId\\fR\nargument gives a name for the bitmap; it must not previously\nhave been used in a call to \\fBTk_DefineBitmap\\fR.\nThe arguments \\fIsource\\fR, \\fIwidth\\fR, and \\fIheight\\fR\ndescribe the bitmap.\n\\fBTk_DefineBitmap\\fR normally returns \\fBTCL_OK\\fR; if an error occurs\n(e.g. a bitmap named \\fInameId\\fR has already been defined) then\n\\fBTCL_ERROR\\fR is returned and an error message is left in\ninterpreter \\fIinterp\\fR's result.\nNote that \\fBTk_DefineBitmap\\fR expects the memory pointed to by\n\\fIsource\\fR to be static: \\fBTk_DefineBitmap\\fR does not make\na private copy of this memory, but uses the bytes pointed to\nby \\fIsource\\fR later in calls to \\fBTk_AllocBitmapFromObj\\fR or\n\\fBTk_GetBitmap\\fR.\n.PP\nTypically \\fBTk_DefineBitmap\\fR is used by \\fB#include\\fR-ing a\nbitmap file directly into a C program and then referencing\nthe variables defined by the file.\nFor example, suppose there exists a file \\fBstip.bitmap\\fR,\nwhich was created by the \\fBbitmap\\fR program and contains\na stipple pattern.\nThe following code uses \\fBTk_DefineBitmap\\fR to define a\nnew bitmap named \\fBfoo\\fR:\n.CS\nPixmap bitmap;\n#include \"stip.bitmap\"\nTk_DefineBitmap(interp, \"foo\", stip_bits,\n stip_width, stip_height);\n\\&...\nbitmap = Tk_GetBitmap(interp, tkwin, \"foo\");\n.CE\nThis code causes the bitmap file to be read\nat compile-time and incorporates the bitmap information into\nthe program's executable image. The same bitmap file could be\nread at run-time using \\fBTk_GetBitmap\\fR:\n.CS\nPixmap bitmap;\nbitmap = Tk_GetBitmap(interp, tkwin, \"@stip.bitmap\");\n.CE\nThe second form is a bit more flexible (the file could be modified\nafter the program has been compiled, or a different string could be\nprovided to read a different file), but it is a little slower and\nrequires the bitmap file to exist separately from the program.\n.PP\nTk maintains a database of all the bitmaps that are currently in use.\nWhenever possible, it will return an existing bitmap rather\nthan creating a new one.\nWhen a bitmap is no longer used, Tk will release it automatically.\nThis approach can substantially reduce server overhead, so\n\\fBTk_AllocBitmapFromObj\\fR and \\fBTk_GetBitmap\\fR should generally\nbe used in preference to Xlib procedures like \\fBXReadBitmapFile\\fR.\n.PP\nThe bitmaps returned by \\fBTk_AllocBitmapFromObj\\fR and \\fBTk_GetBitmap\\fR\nare shared, so callers should never modify them.\nIf a bitmap must be modified dynamically, then it should be\ncreated by calling Xlib procedures such as \\fBXReadBitmapFile\\fR\nor \\fBXCreatePixmap\\fR directly.\n.PP\nThe procedure \\fBTk_NameOfBitmap\\fR is roughly the inverse of\n\\fBTk_GetBitmap\\fR.\nGiven an X Pixmap argument, it returns the textual description that was\npassed to \\fBTk_GetBitmap\\fR when the bitmap was created.\n\\fIBitmap\\fR must have been the return value from a previous\ncall to \\fBTk_AllocBitmapFromObj\\fR or \\fBTk_GetBitmap\\fR.\n.PP\n\\fBTk_SizeOfBitmap\\fR returns the dimensions of its \\fIbitmap\\fR\nargument in the words pointed to by the \\fIwidthPtr\\fR and\n\\fIheightPtr\\fR arguments. As with \\fBTk_NameOfBitmap\\fR,\n\\fIbitmap\\fR must have been created by \\fBTk_AllocBitmapFromObj\\fR or\n\\fBTk_GetBitmap\\fR.\n.PP\nWhen a bitmap is no longer needed, \\fBTk_FreeBitmapFromObj\\fR or\n\\fBTk_FreeBitmap\\fR should be called to release it.\nFor \\fBTk_FreeBitmapFromObj\\fR the bitmap to release is specified\nwith the same information used to create it; for\n\\fBTk_FreeBitmap\\fR the bitmap to release is specified\nwith its Pixmap token.\nThere should be exactly one call to \\fBTk_FreeBitmapFromObj\\fR\nor \\fBTk_FreeBitmap\\fR for each call to \\fBTk_AllocBitmapFromObj\\fR or\n\\fBTk_GetBitmap\\fR.\n.SH BUGS\n.PP\nIn determining whether an existing bitmap can be used to satisfy\na new request, \\fBTk_AllocBitmapFromObj\\fR and \\fBTk_GetBitmap\\fR\nconsider only the immediate value of the string description. For\nexample, when a file name is passed to \\fBTk_GetBitmap\\fR,\n\\fBTk_GetBitmap\\fR will assume it is safe to re-use an existing\nbitmap created from the same file name: it will not check to\nsee whether the file itself has changed, or whether the current\ndirectory has changed, thereby causing the name to refer to\na different file.\n.SH KEYWORDS\nbitmap, pixmap\n" }, { "path": "doc/GetCapStyl.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetCapStyle 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetCapStyle, Tk_NameOfCapStyle \\- translate between strings and cap styles\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_GetCapStyle\\fR(\\fIinterp, string, capPtr\\fR)\n.sp\nconst char *\n\\fBTk_NameOfCapStyle\\fR(\\fIcap\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tcl_Interp\" *capPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP \"const char\" *string in\nString containing name of cap style \\- one of\n.QW \\fBbutt\\fR ,\n.QW \\fBprojecting\\fR ,\nor\n.QW \\fBround\\fR\n\\- or a unique abbreviation of one.\n.AP int *capPtr out\nPointer to location in which to store X cap style corresponding to\n\\fIstring\\fR.\n.AP int cap in\nCap style: one of \\fBCapButt\\fR, \\fBCapProjecting\\fR, or \\fBCapRound\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetCapStyle\\fR places in \\fI*capPtr\\fR the X cap style\ncorresponding to \\fIstring\\fR.\nThis will be one of the values\n\\fBCapButt\\fR, \\fBCapProjecting\\fR, or \\fBCapRound\\fR.\nCap styles are typically used in X graphics contexts to indicate\nhow the end-points of lines should be capped.\nSee the X documentation for information on what each style\nimplies.\n.PP\nUnder normal circumstances the return value is \\fBTCL_OK\\fR and\n\\fIinterp\\fR is unused.\nIf \\fIstring\\fR does not contain a valid cap style\nor an abbreviation of one of these names, then an error message is\nstored in interpreter \\fIinterp\\fR's result, \\fBTCL_ERROR\\fR is returned, and\n\\fI*capPtr\\fR is unmodified.\n.PP\n\\fBTk_NameOfCapStyle\\fR is the logical inverse of \\fBTk_GetCapStyle\\fR.\nGiven a cap style such as \\fBCapButt\\fR it returns a\nstatically-allocated string corresponding to \\fIcap\\fR.\nIf \\fIcap\\fR is not a legal cap style, then\n.QW \"unknown cap style\"\nis returned.\n.SH KEYWORDS\nbutt, cap style, projecting, round\n" }, { "path": "doc/GetClrmap.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetColormap 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \\- allocate and free colormaps\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nColormap\n\\fBTk_GetColormap\\fR(\\fIinterp, tkwin, string\\fR)\n.sp\n\\fBTk_PreserveColormap\\fR(\\fIdisplay, colormap\\fR)\n.sp\n\\fBTk_FreeColormap\\fR(\\fIdisplay, colormap\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Colormap\" colormap\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP Tk_Window tkwin in\nToken for window in which colormap will be used.\n.AP \"const char\" *string in\nSelects a colormap: either \\fBnew\\fR or the name of a window\nwith the same screen and visual as \\fItkwin\\fR.\n.AP Display *display in\nDisplay for which \\fIcolormap\\fR was allocated.\n.AP Colormap colormap in\nColormap to free or preserve; must have been returned by a previous\ncall to \\fBTk_GetColormap\\fR or \\fBTk_GetVisual\\fR.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures are used to manage colormaps.\n\\fBTk_GetColormap\\fR returns a colormap suitable for use in \\fItkwin\\fR.\nIf its \\fIstring\\fR argument is \\fBnew\\fR then a new colormap is\ncreated; otherwise \\fIstring\\fR must be the name of another window\nwith the same screen and visual as \\fItkwin\\fR, and the colormap from that\nwindow is returned.\nIf \\fIstring\\fR does not make sense, or if it refers to a window on\na different screen from \\fItkwin\\fR or with\na different visual than \\fItkwin\\fR, then \\fBTk_GetColormap\\fR returns\n\\fBNone\\fR and leaves an error message in \\fIinterp\\fR's result.\n.PP\n\\fBTk_PreserveColormap\\fR increases the internal reference count for a\ncolormap previously returned by \\fBTk_GetColormap\\fR, which allows the\ncolormap to be stored in several locations without knowing which order\nthey will be released.\n.PP\n\\fBTk_FreeColormap\\fR should be called when a colormap returned by\n\\fBTk_GetColormap\\fR is no longer needed.\nTk maintains a reference count for each colormap returned by\n\\fBTk_GetColormap\\fR, so there should eventually be one call to\n\\fBTk_FreeColormap\\fR for each call to \\fBTk_GetColormap\\fR and each\ncall to \\fBTk_PreserveColormap\\fR.\nWhen a colormap's reference count becomes zero, Tk releases the\nX colormap.\n.PP\n\\fBTk_GetVisual\\fR and \\fBTk_GetColormap\\fR work together, in that\na new colormap created by \\fBTk_GetVisual\\fR may later be returned\nby \\fBTk_GetColormap\\fR.\nThe reference counting mechanism for colormaps includes both procedures,\nso callers of \\fBTk_GetVisual\\fR must also call \\fBTk_FreeColormap\\fR\nto release the colormap.\nIf \\fBTk_GetColormap\\fR is called with a \\fIstring\\fR value of\n\\fBnew\\fR then the resulting colormap will never\nbe returned by \\fBTk_GetVisual\\fR; however, it can be used in other\nwindows by calling \\fBTk_GetColormap\\fR with the original window's\nname as \\fIstring\\fR.\n.SH KEYWORDS\ncolormap, visual\n" }, { "path": "doc/GetColor.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1991 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1998 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_AllocColorFromObj 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \\- maintain database of colors\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nXColor *\n\\fBTk_AllocColorFromObj\\fR(\\fIinterp, tkwin, objPtr\\fR)\n.sp\nXColor *\n\\fBTk_GetColor\\fR(\\fIinterp, tkwin, name\\fR)\n.sp\nXColor *\n\\fBTk_GetColorFromObj\\fR(\\fItkwin, objPtr\\fR)\n.sp\nXColor *\n\\fBTk_GetColorByValue\\fR(\\fItkwin, prefPtr\\fR)\n.sp\nconst char *\n\\fBTk_NameOfColor\\fR(\\fIcolorPtr\\fR)\n.sp\nGC\n\\fBTk_GCForColor\\fR(\\fIcolorPtr, drawable\\fR)\n.sp\n\\fBTk_FreeColorFromObj\\fR(\\fItkwin, objPtr\\fR)\n.sp\n\\fBTk_FreeColor\\fR(\\fIcolorPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tcl_Interp\" *colorPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP Tk_Window tkwin in\nToken for window in which color will be used.\n.AP Tcl_Obj *objPtr in/out\nString value describes desired color; internal rep will be\nmodified to cache pointer to corresponding (XColor *).\n.AP \"const char\" *name in\nSame as \\fIobjPtr\\fR except description of color is passed as a string and\nresulting (XColor *) is not cached.\n.AP XColor *prefPtr in\nIndicates red, green, and blue intensities of desired\ncolor.\n.AP XColor *colorPtr in\nPointer to X color information. Must have been allocated by previous\ncall to \\fBTk_AllocColorFromObj\\fR, \\fBTk_GetColor\\fR or\n\\fBTk_GetColorByValue\\fR, except when passed to \\fBTk_NameOfColor\\fR.\n.AP Drawable drawable in\nDrawable in which the result graphics context will be used. Must have\nsame screen and depth as the window for which the color was allocated.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures manage the colors being used by a Tk application.\nThey allow colors to be shared whenever possible, so that colormap\nspace is preserved, and they pick closest available colors when\ncolormap space is exhausted.\n.PP\nGiven a textual description of a color, \\fBTk_AllocColorFromObj\\fR\nlocates a pixel value that may be used to render the color\nin a particular window. The desired color is specified with a\nvalue whose string value must have one of the following forms:\n.TP 20\n\\fIcolorname\\fR\n.\nAny of the valid textual names for a color defined in the\nserver's color database file, such as \\fBred\\fR or \\fBPeachPuff\\fR.\n.TP 20\n\\fB#\\fIRGB\\fR\n.TP 20\n\\fB#\\fIRRGGBB\\fR\n.TP 20\n\\fB#\\fIRRRGGGBBB\\fR\n.TP 20\n\\fB#\\fIRRRRGGGGBBBB\\fR\n.\nA numeric specification of the red, green, and blue intensities\nto use to display the color. Each \\fIR\\fR, \\fIG\\fR, or \\fIB\\fR\nrepresents a single hexadecimal digit. The four forms permit\ncolors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values.\nWhen fewer than 16 bits are provided for each color, they represent\nthe most significant bits of the color, while the lower unfilled\nbits will be repeatedly replicated from the available higher bits.\nFor example, #3a7 is the same as #3333aaaa7777.\n.PP\n\\fBTk_AllocColorFromObj\\fR returns a pointer to\nan XColor structure; the structure indicates the exact intensities of\nthe allocated color (which may differ slightly from those requested,\ndepending on the limitations of the screen) and a pixel value\nthat may be used to draw with the color in \\fItkwin\\fR.\nIf an error occurs in \\fBTk_AllocColorFromObj\\fR (such as an unknown\ncolor name) then NULL is returned and an error message is stored in\n\\fIinterp\\fR's result if \\fIinterp\\fR is not NULL.\nIf the colormap for \\fItkwin\\fR is full, \\fBTk_AllocColorFromObj\\fR\nwill use the closest existing color in the colormap.\n\\fBTk_AllocColorFromObj\\fR caches information about\nthe return value in \\fIobjPtr\\fR, which speeds up future calls to procedures\nsuch as \\fBTk_AllocColorFromObj\\fR and \\fBTk_GetColorFromObj\\fR.\n.PP\n\\fBTk_GetColor\\fR is identical to \\fBTk_AllocColorFromObj\\fR except\nthat the description of the color is specified with a string instead\nof a value. This prevents \\fBTk_GetColor\\fR from caching the\nreturn value, so \\fBTk_GetColor\\fR is less efficient than\n\\fBTk_AllocColorFromObj\\fR.\n.PP\n\\fBTk_GetColorFromObj\\fR returns the token for an existing color, given\nthe window and description used to create the color.\n\\fBTk_GetColorFromObj\\fR does not actually create the color; the color\nmust already have been created with a previous call to\n\\fBTk_AllocColorFromObj\\fR or \\fBTk_GetColor\\fR. The return\nvalue is cached in \\fIobjPtr\\fR, which speeds up\nfuture calls to \\fBTk_GetColorFromObj\\fR with the same \\fIobjPtr\\fR\nand \\fItkwin\\fR.\n.PP\n\\fBTk_GetColorByValue\\fR is similar to \\fBTk_GetColor\\fR except that\nthe desired color is indicated with the \\fIred\\fR, \\fIgreen\\fR, and\n\\fIblue\\fR fields of the structure pointed to by \\fIcolorPtr\\fR.\n.PP\nThis package maintains a database\nof all the colors currently in use.\nIf the same color is requested multiple times from\n\\fBTk_GetColor\\fR or \\fBTk_AllocColorFromObj\\fR (e.g. by different\nwindows), or if the\nsame intensities are requested multiple times from\n\\fBTk_GetColorByValue\\fR, then existing pixel values will\nbe re-used. Re-using an existing pixel avoids any interaction\nwith the window server, which makes the allocation much more\nefficient. These procedures also provide a portable interface that\nworks across all platforms. For this reason, you should generally use\n\\fBTk_AllocColorFromObj\\fR, \\fBTk_GetColor\\fR, or \\fBTk_GetColorByValue\\fR\ninstead of lower level procedures like \\fBXAllocColor\\fR.\n.PP\nSince different calls to this package\nmay return the same shared\npixel value, callers should never change the color of a pixel\nreturned by the procedures.\nIf you need to change a color value dynamically, you should use\n\\fBXAllocColorCells\\fR to allocate the pixel value for the color.\n.PP\nThe procedure \\fBTk_NameOfColor\\fR is roughly the inverse of\n\\fBTk_GetColor\\fR. If its \\fIcolorPtr\\fR argument was created\nby \\fBTk_AllocColorFromObj\\fR or \\fBTk_GetColor\\fR then the return value\nis the string that was used to create the\ncolor. If \\fIcolorPtr\\fR was created by a call to \\fBTk_GetColorByValue\\fR,\nor by any other mechanism, then the return value is a string\nthat could be passed to \\fBTk_GetColor\\fR to return the same\ncolor. Note: the string returned by \\fBTk_NameOfColor\\fR is\nonly guaranteed to persist until the next call to\n\\fBTk_NameOfColor\\fR.\n.PP\n\\fBTk_GCForColor\\fR returns a graphics context whose \\fBforeground\\fR\nfield is the pixel allocated for \\fIcolorPtr\\fR and whose other fields\nall have default values.\nThis provides an easy way to do basic drawing with a color.\nThe graphics context is cached with the color and will exist only as\nlong as \\fIcolorPtr\\fR exists; it is freed when the last reference\nto \\fIcolorPtr\\fR is freed by calling \\fBTk_FreeColor\\fR.\n.PP\nWhen a color is no longer needed \\fBTk_FreeColorFromObj\\fR or\n\\fBTk_FreeColor\\fR should be called to release it.\nFor \\fBTk_FreeColorFromObj\\fR the color to release is specified\nwith the same information used to create it; for\n\\fBTk_FreeColor\\fR the color to release is specified\nwith a pointer to its XColor structure.\nThere should be exactly one call to \\fBTk_FreeColorFromObj\\fR\nor \\fBTk_FreeColor\\fR for each call to \\fBTk_AllocColorFromObj\\fR,\n\\fBTk_GetColor\\fR, or \\fBTk_GetColorByValue\\fR.\n.SH KEYWORDS\ncolor, intensity, value, pixel value\n" }, { "path": "doc/GetCursor.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1998 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_AllocCursorFromObj 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor \\- maintain database of cursors\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Cursor\n\\fBTk_AllocCursorFromObj\\fR(\\fIinterp, tkwin, objPtr\\fR)\n.sp\nTk_Cursor\n\\fBTk_GetCursor\\fR(\\fIinterp, tkwin, name\\fR)\n.sp\nTk_Cursor\n\\fBTk_GetCursorFromObj\\fR(\\fItkwin, objPtr\\fR)\n.sp\nTk_Cursor\n\\fBTk_GetCursorFromData\\fR(\\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\\fR)\n.sp\nconst char *\n\\fBTk_NameOfCursor\\fR(\\fIdisplay, cursor\\fR)\n.sp\n\\fBTk_FreeCursorFromObj\\fR(\\fItkwin, objPtr\\fR)\n.sp\n\\fBTk_FreeCursor\\fR(\\fIdisplay, cursor\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"unsigned long\" *pixelPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP Tk_Window tkwin in\nToken for window in which the cursor will be used.\n.AP Tcl_Obj *objPtr in/out\nDescription of cursor; see below for possible values. Internal rep will be\nmodified to cache pointer to corresponding Tk_Cursor.\n.AP \"const char\" *name in\nSame as \\fIobjPtr\\fR except description of cursor is passed as a string and\nresulting Tk_Cursor is not cached.\n.AP \"const char\" *source in\nData for cursor cursor, in standard cursor format.\n.AP \"const char\" *mask in\nData for mask cursor, in standard cursor format.\n.AP \"int\" width in\nWidth of \\fIsource\\fR and \\fImask\\fR.\n.AP \"int\" height in\nHeight of \\fIsource\\fR and \\fImask\\fR.\n.AP \"int\" xHot in\nX-location of cursor hot-spot.\n.AP \"int\" yHot in\nY-location of cursor hot-spot.\n.AP \"const char\" *fg in\nTextual description of foreground color for cursor.\n.AP \"const char\" *bg in\nTextual description of background color for cursor.\n.AP Display *display in\nDisplay for which \\fIcursor\\fR was allocated.\n.AP Tk_Cursor cursor in\nOpaque Tk identifier for cursor. If passed to \\fBTk_FreeCursor\\fR, must\nhave been returned by some previous call to \\fBTk_GetCursor\\fR or\n\\fBTk_GetCursorFromData\\fR.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures manage a collection of cursors\nbeing used by an application. The procedures allow cursors to be\nre-used efficiently, thereby avoiding server overhead, and also\nallow cursors to be named with character strings.\n.PP\n\\fBTk_AllocCursorFromObj\\fR takes as argument an object describing a\ncursor, and returns an opaque Tk identifier for a cursor corresponding\nto the description. It re-uses an existing cursor if possible and\ncreates a new one otherwise. \\fBTk_AllocCursorFromObj\\fR caches\ninformation about the return value in \\fIobjPtr\\fR, which speeds up\nfuture calls to procedures such as \\fBTk_AllocCursorFromObj\\fR and\n\\fBTk_GetCursorFromObj\\fR. If an error occurs in creating the cursor,\nsuch as when \\fIobjPtr\\fR refers to a non-existent file, then \\fBNone\\fR\nis returned and an error message will be stored in \\fIinterp\\fR's result\nif \\fIinterp\\fR is not NULL. \\fIObjPtr\\fR must contain a standard Tcl\nlist with one of the following forms:\n.TP\n\\fIname\\fR\\0[\\fIfgColor\\fR\\0[\\fIbgColor\\fR]]\n.\n\\fIName\\fR is the name of a cursor in the standard X cursor cursor,\ni.e., any of the names defined in \\fBcursorcursor.h\\fR, without\nthe \\fBXC_\\fR. Some example values are \\fBX_cursor\\fR, \\fBhand2\\fR,\nor \\fBleft_ptr\\fR. Appendix B of\n.QW \"The X Window System\"\nby Scheifler & Gettys has illustrations showing what each of these\ncursors looks like. If \\fIfgColor\\fR and \\fIbgColor\\fR are both\nspecified, they give the foreground and background colors to use\nfor the cursor (any of the forms acceptable to \\fBTk_GetColor\\fR\nmay be used). If only \\fIfgColor\\fR is specified, then there\nwill be no background color: the background will be transparent.\nIf no colors are specified, then the cursor\nwill use black for its foreground color and white for its background\ncolor.\n.RS\n.PP\nThe Macintosh version of Tk supports all of the X cursors and\nwill also accept any of the standard Mac cursors\nincluding \\fBibeam\\fR, \\fBcrosshair\\fR, \\fBwatch\\fR, \\fBplus\\fR, and\n\\fBarrow\\fR. In addition, Tk will load Macintosh cursor resources of\nthe types \\fBcrsr\\fR (color) and \\fBCURS\\fR (black and white) by the\nname of the resource. The application and all its open\ndynamic library's resource files will be searched for the named\ncursor. If there are conflicts color cursors will always be loaded\nin preference to black and white cursors.\n.RE\n.TP\n\\fB@\\fIsourceName\\0maskName\\0fgColor\\0bgColor\\fR\n.\nIn this form, \\fIsourceName\\fR and \\fImaskName\\fR are the names of\nfiles describing cursors for the cursor's source bits and mask.\nEach file must be in standard X11 cursor format.\n\\fIFgColor\\fR and \\fIbgColor\\fR\nindicate the colors to use for the\ncursor, in any of the forms acceptable to \\fBTk_GetColor\\fR. This\nform of the command will not work on Macintosh or Windows computers.\n.TP\n\\fB@\\fIsourceName\\0fgColor\\fR\n.\nThis form is similar to the one above, except that the source is\nused as mask also. This means that the cursor's background is\ntransparent. This form of the command will not work on Macintosh\nor Windows computers.\n.TP\n\\fB@\\fIsourceName\\fR\n.\nThis form only works on Windows, and will load a Windows system\ncursor (\\fB.ani\\fR or \\fB.cur\\fR) from the file specified in\n\\fIsourceName\\fR.\n.PP\n\\fBTk_GetCursor\\fR is identical to \\fBTk_AllocCursorFromObj\\fR except\nthat the description of the cursor is specified with a string instead\nof an object. This prevents \\fBTk_GetCursor\\fR from caching the\nreturn value, so \\fBTk_GetCursor\\fR is less efficient than\n\\fBTk_AllocCursorFromObj\\fR.\n.PP\n\\fBTk_GetCursorFromObj\\fR returns the token for an existing cursor, given\nthe window and description used to create the cursor.\n\\fBTk_GetCursorFromObj\\fR does not actually create the cursor; the cursor\nmust already have been created with a previous call to\n\\fBTk_AllocCursorFromObj\\fR or \\fBTk_GetCursor\\fR. The return\nvalue is cached in \\fIobjPtr\\fR, which speeds up\nfuture calls to \\fBTk_GetCursorFromObj\\fR with the same \\fIobjPtr\\fR\nand \\fItkwin\\fR.\n.PP\n\\fBTk_GetCursorFromData\\fR allows cursors to be created from\nin-memory descriptions of their source and mask cursors. \\fISource\\fR\npoints to standard cursor data for the cursor's source bits, and\n\\fImask\\fR points to standard cursor data describing\nwhich pixels of \\fIsource\\fR are to be drawn and which are to be\nconsidered transparent. \\fIWidth\\fR and \\fIheight\\fR give the\ndimensions of the cursor, \\fIxHot\\fR and \\fIyHot\\fR indicate the\nlocation of the cursor's hot-spot (the point that is reported when\nan event occurs), and \\fIfg\\fR and \\fIbg\\fR describe the cursor's\nforeground and background colors textually (any of the forms\nsuitable for \\fBTk_GetColor\\fR may be used). Typically, the\narguments to \\fBTk_GetCursorFromData\\fR are created by including\na cursor file directly into the source code for a program, as in\nthe following example:\n.CS\nTk_Cursor cursor;\n#include \"source.cursor\"\n#include \"mask.cursor\"\ncursor = Tk_GetCursorFromData(interp, tkwin, source_bits,\n mask_bits, source_width, source_height, source_x_hot,\n source_y_hot, \"red\", \"blue\");\n.CE\n.PP\nUnder normal conditions \\fBTk_GetCursorFromData\\fR\nwill return an identifier for the requested cursor. If an error\noccurs in creating the cursor then \\fBNone\\fR is returned and an error\nmessage will be stored in \\fIinterp\\fR's result.\n.PP\n\\fBTk_AllocCursorFromObj\\fR, \\fBTk_GetCursor\\fR, and\n\\fBTk_GetCursorFromData\\fR maintain a\ndatabase of all the cursors they have created. Whenever possible,\na call to \\fBTk_AllocCursorFromObj\\fR, \\fBTk_GetCursor\\fR, or\n\\fBTk_GetCursorFromData\\fR will\nreturn an existing cursor rather than creating a new one. This\napproach can substantially reduce server overhead, so the Tk\nprocedures should generally be used in preference to Xlib procedures\nlike \\fBXCreateFontCursor\\fR or \\fBXCreatePixmapCursor\\fR, which\ncreate a new cursor on each call. The Tk procedures are also more\nportable than the lower-level X procedures.\n.PP\nThe procedure \\fBTk_NameOfCursor\\fR is roughly the inverse of\n\\fBTk_GetCursor\\fR. If its \\fIcursor\\fR argument was created\nby \\fBTk_GetCursor\\fR, then the return value is the \\fIname\\fR\nargument that was passed to \\fBTk_GetCursor\\fR to create the\ncursor. If \\fIcursor\\fR was created by a call to \\fBTk_GetCursorFromData\\fR,\nor by any other mechanism, then the return value is a hexadecimal string\ngiving the X identifier for the cursor.\nNote that the string returned by \\fBTk_NameOfCursor\\fR is\nonly guaranteed to persist until the next call to\n\\fBTk_NameOfCursor\\fR. Also, this call is not portable except for\ncursors returned by \\fBTk_GetCursor\\fR.\n.PP\nWhen a cursor returned by \\fBTk_AllocCursorFromObj\\fR, \\fBTk_GetCursor\\fR,\nor \\fBTk_GetCursorFromData\\fR\nis no longer needed, \\fBTk_FreeCursorFromObj\\fR or\n\\fBTk_FreeCursor\\fR should be called to release it.\nFor \\fBTk_FreeCursorFromObj\\fR the cursor to release is specified\nwith the same information used to create it; for\n\\fBTk_FreeCursor\\fR the cursor to release is specified\nwith its Tk_Cursor token.\nThere should be exactly one call to \\fBTk_FreeCursor\\fR for\neach call to \\fBTk_AllocCursorFromObj\\fR, \\fBTk_GetCursor\\fR,\nor \\fBTk_GetCursorFromData\\fR.\n.SH BUGS\n.PP\nIn determining whether an existing cursor can be used to satisfy\na new request, \\fBTk_AllocCursorFromObj\\fR, \\fBTk_GetCursor\\fR,\nand \\fBTk_GetCursorFromData\\fR\nconsider only the immediate values of their arguments. For\nexample, when a file name is passed to \\fBTk_GetCursor\\fR,\n\\fBTk_GetCursor\\fR will assume it is safe to re-use an existing\ncursor created from the same file name: it will not check to\nsee whether the file itself has changed, or whether the current\ndirectory has changed, thereby causing the name to refer to\na different file. Similarly, \\fBTk_GetCursorFromData\\fR assumes\nthat if the same \\fIsource\\fR pointer is used in two different calls,\nthen the pointers refer to the same data; it does not check to\nsee if the actual data values have changed.\n.SH KEYWORDS\ncursor\n" }, { "path": "doc/GetDash.3", "content": "'\\\"\n'\\\" Copyright (c) 1989-1993 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetDash 3 8.3 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetDash \\- convert from string to valid dash structure.\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n\nint\n\\fBTk_GetDash\\fR(\\fIinterp, string, dashPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Dash *dashPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP \"const char\" *string in\nTextual value to be converted.\n.AP Tk_Dash *dashPtr out\nPoints to place to store the dash pattern\nvalue converted from \\fIstring\\fR. Must not be NULL.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedure parses the string and fills in the result in the\nTk_Dash structure. The string can be a list of integers or a\ncharacter string containing only\n.QW \\fB.,-_\\fR\nand spaces. If all\ngoes well, \\fBTCL_OK\\fR is returned and a dash descriptor is stored\nin the variable pointed to by \\fIdashPtr\\fR.\nIf \\fIstring\\fR does not have the\nproper syntax then \\fBTCL_ERROR\\fR is returned, an error message is left\nin the interpreter's result, and nothing is stored at *\\fIdashPtr\\fR.\n.PP\nThe first possible syntax is a list of integers. Each element\nrepresents the number of pixels of a line segment. Only the odd\nsegments are drawn using the\n.QW outline\ncolor. The other segments are drawn transparent.\n.PP\nThe second possible syntax is a character list containing only\n5 possible characters\n.QW \"\\fB.,-_ \\fR\" .\nThe space can be used\nto enlarge the space between other line elements, and can not\noccur in the first position of the string. Some examples:\n.PP\n.CS\n \\-dash . = \\-dash {2 4}\n \\-dash - = \\-dash {6 4}\n \\-dash -. = \\-dash {6 4 2 4}\n \\-dash -.. = \\-dash {6 4 2 4 2 4}\n \\-dash {. } = \\-dash {2 8}\n \\-dash , = \\-dash {4 4}\n.CE\n.PP\nThe main difference between this syntax and the numeric is that it\nis shape-conserving. This means that all values in the dash\nlist will be multiplied by the line width before display. This\nensures that\n.QW .\nwill always be displayed as a dot and\n.QW -\nalways as a dash regardless of the line width.\n.PP\nOn systems where only a limited set of dash patterns, the dash\npattern will be displayed as the most close dash pattern that\nis available. For example, on Windows only the first 4 of the\nabove examples are available; the last 2 examples will be\ndisplayed identically to the first one.\n.SH \"SEE ALSO\"\ncanvas(n), Tk_CreateItemType(3)\n.SH KEYWORDS\ndash, conversion\n" }, { "path": "doc/GetFont.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1998 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_AllocFontFromObj 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FontGetDescription, Tk_FreeFontFromObj, Tk_FreeFont \\- maintain database of fonts\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Font\n\\fBTk_AllocFontFromObj\\fR(\\fIinterp, tkwin, objPtr\\fR)\n.sp\nTk_Font\n\\fBTk_GetFont\\fR(\\fIinterp, tkwin, string\\fR)\n.sp\nTk_Font\n\\fBTk_GetFontFromObj\\fR(\\fItkwin, objPtr\\fR)\n.sp\nTcl_Obj *\n\\fBTk_FontGetDescription\\fR(\\fItkfont\\fR)\n.sp\nconst char *\n\\fBTk_NameOfFont\\fR(\\fItkfont\\fR)\n.sp\nTk_Font\n\\fBTk_FreeFontFromObj\\fR(\\fItkwin, objPtr\\fR)\n.sp\n\\fBTk_FreeFont\\fR(\\fItkfont\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"const char\" *tkfont\n.AP \"Tcl_Interp\" *interp in\nInterpreter to use for error reporting. If \\fBNULL\\fR, then no error\nmessages are left after errors.\n.AP Tk_Window tkwin in\nToken for window in which font will be used.\n.AP Tcl_Obj *objPtr in/out\nGives name or description of font. See documentation\nfor the \\fBfont\\fR command for details on acceptable formats.\nInternal rep will be modified to cache corresponding Tk_Font.\n.AP \"const char\" *string in\nSame as \\fIobjPtr\\fR except description of font is passed as a string and\nresulting Tk_Font is not cached.\n.AP Tk_Font tkfont in\nOpaque font token.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_AllocFontFromObj\\fR finds the font indicated by \\fIobjPtr\\fR and\nreturns a token that represents the font. The return value can be used\nin subsequent calls to procedures such as \\fBTk_GetFontMetrics\\fR,\n\\fBTk_MeasureChars\\fR, and \\fBTk_FreeFont\\fR. The Tk_Font token\nwill remain valid until\n\\fBTk_FreeFontFromObj\\fR or \\fBTk_FreeFont\\fR is called to release it.\n\\fIObjPtr\\fR can contain either a symbolic name or a font description; see\nthe documentation for the \\fBfont\\fR command for a description of the\nvalid formats. If \\fBTk_AllocFontFromObj\\fR is unsuccessful (because,\nfor example, \\fIobjPtr\\fR did not contain a valid font specification) then it\nreturns \\fBNULL\\fR and leaves an error message in \\fIinterp\\fR's result\nif \\fIinterp\\fR is not \\fBNULL\\fR. \\fBTk_AllocFontFromObj\\fR caches\ninformation about the return\nvalue in \\fIobjPtr\\fR, which speeds up future calls to procedures\nsuch as \\fBTk_AllocFontFromObj\\fR and \\fBTk_GetFontFromObj\\fR.\n.PP\n\\fBTk_GetFont\\fR is identical to \\fBTk_AllocFontFromObj\\fR except\nthat the description of the font is specified with a string instead\nof an object. This prevents \\fBTk_GetFont\\fR from caching the\nmatching Tk_Font, so \\fBTk_GetFont\\fR is less efficient than\n\\fBTk_AllocFontFromObj\\fR.\n.PP\n\\fBTk_GetFontFromObj\\fR returns the token for an existing font, given\nthe window and description used to create the font.\n\\fBTk_GetFontFromObj\\fR does not actually create the font; the font\nmust already have been created with a previous call to\n\\fBTk_AllocFontFromObj\\fR or \\fBTk_GetFont\\fR. The return\nvalue is cached in \\fIobjPtr\\fR, which speeds up\nfuture calls to \\fBTk_GetFontFromObj\\fR with the same \\fIobjPtr\\fR\nand \\fItkwin\\fR.\n.PP\n\\fBTk_AllocFontFromObj\\fR and \\fBTk_GetFont\\fR maintain\na database of all fonts they have allocated. If\nthe same font is requested multiple times (e.g. by different\nwindows or for different purposes), then a single Tk_Font will be\nshared for all uses. The underlying resources will be freed automatically\nwhen no-one is using the font anymore.\n.PP\nThe procedure \\fBTk_FontGetDescription\\fR returns information about the font\ndescription as a Tcl list. One possible result is\n.QW \"{{DejaVu Sans} -16 bold underline}\" .\n.PP\nThe procedure \\fBTk_NameOfFont\\fR is roughly the inverse of\n\\fBTk_GetFont\\fR. Given a \\fItkfont\\fR that was created by\n\\fBTk_GetFont\\fR (or \\fBTk_AllocFontFromObj\\fR), the return value is\nthe \\fIstring\\fR argument that was\npassed to \\fBTk_GetFont\\fR to create the font. The string returned by\n\\fBTk_NameOfFont\\fR is only guaranteed to persist until the \\fItkfont\\fR\nis deleted. The caller must not modify this string.\n.PP\nWhen a font is no longer needed,\n\\fBTk_FreeFontFromObj\\fR or \\fBTk_FreeFont\\fR should be called to\nrelease it. For \\fBTk_FreeFontFromObj\\fR the font to release is specified\nwith the same information used to create it; for\n\\fBTk_FreeFont\\fR the font to release is specified\nwith its Tk_Font token. There should be\nexactly one call to \\fBTk_FreeFontFromObj\\fR or \\fBTk_FreeFont\\fR\nfor each call to \\fBTk_AllocFontFromObj\\fR or \\fBTk_GetFont\\fR.\n.SH \"SEE ALSO\"\nTk_FontId(3)\n.SH KEYWORDS\nfont\n" }, { "path": "doc/GetGC.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetGC 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetGC, Tk_FreeGC \\- maintain database of read-only graphics contexts\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nGC\n\\fBTk_GetGC\\fR(\\fItkwin, valueMask, valuePtr\\fR)\n.sp\n\\fBTk_FreeGC\\fR(\\fIdisplay, gc\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"unsigned long\" valueMask\n.AP Tk_Window tkwin in\nToken for window in which the graphics context will be used.\n.AP \"unsigned long\" valueMask in\nMask of bits (such as \\fBGCForeground\\fR or \\fBGCStipple\\fR)\nindicating which fields of \\fI*valuePtr\\fR are valid.\n.AP XGCValues *valuePtr in\nPointer to structure describing the desired values for the\ngraphics context.\n.AP Display *display in\nDisplay for which \\fIgc\\fR was allocated.\n.AP GC gc in\nX identifier for graphics context that is no longer needed.\nMust have been allocated by \\fBTk_GetGC\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetGC\\fR and \\fBTk_FreeGC\\fR manage a collection of graphics contexts\nbeing used by an application. The procedures allow graphics contexts to be\nshared, thereby avoiding the server overhead that would be incurred\nif a separate GC were created for each use. \\fBTk_GetGC\\fR takes arguments\ndescribing the desired graphics context and returns an X identifier\nfor a GC that fits the description. The graphics context that is returned\nwill have default values in all of the fields not specified explicitly\nby \\fIvalueMask\\fR and \\fIvaluePtr\\fR.\n.PP\n\\fBTk_GetGC\\fR maintains a\ndatabase of all the graphics contexts it has created. Whenever possible,\na call to \\fBTk_GetGC\\fR will\nreturn an existing graphics context rather than creating a new one. This\napproach can substantially reduce server overhead, so \\fBTk_GetGC\\fR\nshould generally be used in preference to the Xlib procedure\n\\fBXCreateGC\\fR, which creates a new graphics context on each call.\n.PP\nSince the return values of \\fBTk_GetGC\\fR\nare shared, callers should never modify the graphics contexts\nreturned by \\fBTk_GetGC\\fR.\nIf a graphics context must be modified dynamically, then it should be\ncreated by calling \\fBXCreateGC\\fR instead of \\fBTk_GetGC\\fR.\n.PP\nWhen a graphics context\nis no longer needed, \\fBTk_FreeGC\\fR should be called to release it.\nThere should be exactly one call to \\fBTk_FreeGC\\fR for\neach call to \\fBTk_GetGC\\fR.\nWhen a graphics context is no longer in use anywhere (i.e. it has\nbeen freed as many times as it has been gotten) \\fBTk_FreeGC\\fR\nwill release it to the X server and delete it from the database.\n.SH KEYWORDS\ngraphics context\n" }, { "path": "doc/GetHINSTANCE.3", "content": "'\\\"\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" All rights reserved.\n'\\\"\n.TH Tk_GetHISTANCE 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetHINSTANCE \\- retrieve the global application instance handle\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nHINSTANCE\n\\fBTk_GetHINSTANCE\\fR()\n.fi\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetHINSTANCE\\fR returns the Windows application instance handle\nfor the Tk application. This function is only available on Windows platforms.\n.SH KEYWORDS\nidentifier, instance\n" }, { "path": "doc/GetHWND.3", "content": "'\\\"\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" All rights reserved.\n'\\\"\n.TH HWND 3 8.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetHWND, Tk_AttachHWND \\- manage interactions between the Windows handle and an X window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nHWND\n\\fBTk_GetHWND\\fR(\\fIwindow\\fR)\n.sp\nWindow\n\\fBTk_AttachHWND\\fR(\\fItkwin, hwnd\\fR)\n.fi\n.SH ARGUMENTS\n.AP Window window in\nX token for window.\n.AP Tk_Window tkwin in\nTk window for window.\n.AP HWND hwnd in\nWindows HWND for window.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetHWND\\fR returns the Windows HWND identifier for X Windows\nwindow given by \\fIwindow\\fR.\n.PP\n\\fBTk_AttachHWND\\fR binds the Windows HWND identifier to the\nspecified Tk_Window given by \\fItkwin\\fR. It returns an X Windows\nwindow that encapsulates the HWND.\n.SH KEYWORDS\nidentifier, window\n" }, { "path": "doc/GetImage.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetImage 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \\- use an image in a widget\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Image\n\\fBTk_GetImage\\fR(\\fIinterp, tkwin, name, changeProc, clientData\\fR)\n.sp\n\\fBTk_RedrawImage\\fR(\\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\\fR)\n.sp\n\\fBTk_SizeOfImage\\fR(\\fIimage, widthPtr, heightPtr\\fR)\n.sp\n\\fBTk_FreeImage\\fR(\\fIimage\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_ImageChangedProc *changeProc\n.AP Tcl_Interp *interp in\nPlace to leave error message.\n.AP Tk_Window tkwin in\nWindow in which image will be used.\n.AP \"const char\" *name in\nName of image.\n.AP Tk_ImageChangedProc *changeProc in\nProcedure for Tk to invoke whenever image content or size changes.\n.AP void *clientData in\nOne-word value for Tk to pass to \\fIchangeProc\\fR.\n.AP Tk_Image image in\nToken for image instance; must have been returned by a previous\ncall to \\fBTk_GetImage\\fR.\n.AP int imageX in\nX-coordinate of upper-left corner of region of image to redisplay\n(measured in pixels from the image's upper-left corner).\n.AP int imageY in\nY-coordinate of upper-left corner of region of image to redisplay\n(measured in pixels from the image's upper-left corner).\n.AP \"int\" width (in)\nWidth of region of image to redisplay.\n.AP \"int\" height (in)\nHeight of region of image to redisplay.\n.AP Drawable drawable in\nWhere to display image. Must either be window specified to\n\\fBTk_GetImage\\fR or a pixmap compatible with that window.\n.AP int drawableX in\nWhere to display image in \\fIdrawable\\fR: this is the x-coordinate\nin \\fIdrawable\\fR where x-coordinate \\fIimageX\\fR of the image\nshould be displayed.\n.AP int drawableY in\nWhere to display image in \\fIdrawable\\fR: this is the y-coordinate\nin \\fIdrawable\\fR where y-coordinate \\fIimageY\\fR of the image\nshould be displayed.\n.AP \"int\" widthPtr out\nStore width of \\fIimage\\fR (in pixels) here.\n.AP \"int\" heightPtr out\nStore height of \\fIimage\\fR (in pixels) here.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures are invoked by widgets that wish to display images.\n\\fBTk_GetImage\\fR is invoked by a widget when it first decides to\ndisplay an image.\n\\fIname\\fR gives the name of the desired image and \\fItkwin\\fR\nidentifies the window where the image will be displayed.\n\\fBTk_GetImage\\fR looks up the image in the table of existing\nimages and returns a token for a new instance of the image.\nIf the image does not exist then \\fBTk_GetImage\\fR returns NULL\nand leaves an error message in interpreter \\fIinterp\\fR's result.\n.PP\nWhen a widget wishes to actually display an image it must\ncall \\fBTk_RedrawImage\\fR, identifying the image (\\fIimage\\fR),\na region within the image to redisplay (\\fIimageX\\fR, \\fIimageY\\fR,\n\\fIwidth\\fR, and \\fIheight\\fR), and a place to display the\nimage (\\fIdrawable\\fR, \\fIdrawableX\\fR, and \\fIdrawableY\\fR).\nTk will then invoke the appropriate image manager, which will\ndisplay the requested portion of the image before returning.\n.PP\nA widget can find out the dimensions of an image by calling\n\\fBTk_SizeOfImage\\fR: the width and height will be stored\nin the locations given by \\fIwidthPtr\\fR and \\fIheightPtr\\fR,\nrespectively.\n.PP\nWhen a widget is finished with an image (e.g., the widget is\nbeing deleted or it is going to use a different image instead\nof the current one), it must call \\fBTk_FreeImage\\fR to\nrelease the image instance.\nThe widget should never again use the image token after passing\nit to \\fBTk_FreeImage\\fR.\nThere must be exactly one call to \\fBTk_FreeImage\\fR for each\ncall to \\fBTk_GetImage\\fR.\n.PP\nIf the contents or size of an image changes, then any widgets\nusing the image will need to find out about the changes so that\nthey can redisplay themselves.\nThe \\fIchangeProc\\fR and \\fIclientData\\fR arguments to\n\\fBTk_GetImage\\fR are used for this purpose.\n\\fIchangeProc\\fR will be called by Tk whenever a change occurs\nin the image; it must match the following prototype:\n.CS\ntypedef void \\fBTk_ImageChangedProc\\fR(\n void *\\fIclientData\\fR,\n int \\fIx\\fR,\n int \\fIy\\fR,\n int \\fIwidth\\fR,\n int \\fIheight\\fR,\n int \\fIimageWidth\\fR,\n int \\fIimageHeight\\fR);\n.CE\nThe \\fIclientData\\fR argument to \\fIchangeProc\\fR is the same as the\n\\fIclientData\\fR argument to \\fBTk_GetImage\\fR.\nIt is usually a pointer to the widget record for the widget or\nsome other data structure managed by the widget.\nThe arguments \\fIx\\fR, \\fIy\\fR, \\fIwidth\\fR, and \\fIheight\\fR\nidentify a region within the image that must be redisplayed;\nthey are specified in pixels measured from the upper-left\ncorner of the image.\nThe arguments \\fIimageWidth\\fR and \\fIimageHeight\\fR give\nthe image's (new) size.\n.SH \"SEE ALSO\"\nTk_CreateImageType\n.SH KEYWORDS\nimages, redisplay\n" }, { "path": "doc/GetJoinStl.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetJoinStyle 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetJoinStyle, Tk_NameOfJoinStyle \\- translate between strings and join styles\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_GetJoinStyle\\fR(\\fIinterp, string, joinPtr\\fR)\n.sp\nconst char *\n\\fBTk_NameOfJoinStyle\\fR(\\fIjoin\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tcl_Interp\" *joinPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP \"const char\" *string in\nString containing name of join style \\- one of\n.QW \\fBbevel\\fR ,\n.QW \\fBmiter\\fR ,\nor\n.QW \\fBround\\fR\n\\- or a unique abbreviation of one.\n.AP int *joinPtr out\nPointer to location in which to store X join style corresponding to\n\\fIstring\\fR.\n.AP int join in\nJoin style: one of \\fBJoinBevel\\fR, \\fBJoinMiter\\fR, \\fBJoinRound\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetJoinStyle\\fR places in \\fI*joinPtr\\fR the X join style\ncorresponding to \\fIstring\\fR, which will be one of\n\\fBJoinBevel\\fR, \\fBJoinMiter\\fR, or \\fBJoinRound\\fR.\nJoin styles are typically used in X graphics contexts to indicate\nhow adjacent line segments should be joined together.\nSee the X documentation for information on what each style\nimplies.\n.PP\nUnder normal circumstances the return value is \\fBTCL_OK\\fR and\n\\fIinterp\\fR is unused.\nIf \\fIstring\\fR does not contain a valid join style\nor an abbreviation of one of these names, then an error message is\nstored in interpreter \\fIinterp\\fR's result, \\fBTCL_ERROR\\fR is returned, and\n\\fI*joinPtr\\fR is unmodified.\n.PP\n\\fBTk_NameOfJoinStyle\\fR is the logical inverse of \\fBTk_GetJoinStyle\\fR.\nGiven a join style such as \\fBJoinBevel\\fR it returns a\nstatically-allocated string corresponding to \\fIjoin\\fR.\nIf \\fIjoin\\fR is not a legal join style, then\n.QW \"unknown join style\"\nis returned.\n.SH KEYWORDS\nbevel, join style, miter, round\n" }, { "path": "doc/GetJustify.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1998 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetJustifyFromObj 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \\- translate between strings and justification styles\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_GetJustifyFromObj\\fR(\\fIinterp, objPtr, justifyPtr\\fR)\n.sp\nint\n\\fBTk_GetJustify\\fR(\\fIinterp, string, justifyPtr\\fR)\n.sp\nconst char *\n\\fBTk_NameOfJustify\\fR(\\fIjustify\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tk_Justify\" *justifyPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting, or NULL.\n.AP Tcl_Obj *objPtr in/out\nString value contains name of justification style \\- one of\n.QW \\fBleft\\fR ,\n.QW \\fBright\\fR ,\nor\n.QW \\fBcenter\\fR\n\\- or a unique abbreviation of one.\nThe internal rep will be modified to cache corresponding justify value.\n.AP \"const char\" *string in\nSame as \\fIobjPtr\\fR except description of justification style is passed as\na string.\n.AP int *justifyPtr out\nPointer to location in which to store justify value corresponding to\n\\fIobjPtr\\fR or \\fIstring\\fR.\n.AP Tk_Justify justify in\nJustification style (one of the values listed below).\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetJustifyFromObj\\fR places in \\fI*justifyPtr\\fR the justify value\ncorresponding to \\fIobjPtr\\fR's value.\nThis value will be one of the following:\n.IP \\fBTK_JUSTIFY_LEFT\\fR\nMeans that the text on each line should start at the left edge of\nthe line; as a result, the right edges of lines may be ragged.\n.IP \\fBTK_JUSTIFY_RIGHT\\fR\nMeans that the text on each line should end at the right edge of\nthe line; as a result, the left edges of lines may be ragged.\n.IP \\fBTK_JUSTIFY_CENTER\\fR\nMeans that the text on each line should be centered; as a result,\nboth the left and right edges of lines may be ragged.\n.PP\nUnder normal circumstances the return value is \\fBTCL_OK\\fR and\n\\fIinterp\\fR is unused.\nIf \\fIobjPtr\\fR does not contain a valid justification style\nor an abbreviation of one of these names, \\fBTCL_ERROR\\fR is returned,\n\\fI*justifyPtr\\fR is unmodified, and an error message is\nstored in \\fIinterp\\fR's result if \\fIinterp\\fR is not NULL.\n\\fBTk_GetJustifyFromObj\\fR caches information about the return\nvalue in \\fIobjPtr\\fR, which speeds up future calls to\n\\fBTk_GetJustifyFromObj\\fR with the same \\fIobjPtr\\fR.\n.PP\n\\fBTk_GetJustify\\fR is identical to \\fBTk_GetJustifyFromObj\\fR except\nthat the description of the justification is specified with a string instead\nof an object. This prevents \\fBTk_GetJustify\\fR from caching the\nreturn value, so \\fBTk_GetJustify\\fR is less efficient than\n\\fBTk_GetJustifyFromObj\\fR.\n.PP\n\\fBTk_NameOfJustify\\fR is the logical inverse of \\fBTk_GetJustify\\fR.\nGiven a justify value it returns a statically-allocated string\ncorresponding to \\fIjustify\\fR.\nIf \\fIjustify\\fR is not a legal justify value, then\n.QW \"unknown justification style\"\nis returned.\n.SH KEYWORDS\ncenter, fill, justification, string\n" }, { "path": "doc/GetOption.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetOption 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetOption \\- retrieve an option from the option database\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Uid\n\\fBTk_GetOption\\fR(\\fItkwin, name, class\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window *class\n.AP Tk_Window tkwin in\nToken for window.\n.AP \"const char\" *name in\nName of desired option.\n.AP \"const char\" *class in\nClass of desired option. Null means there is no class for\nthis option; do lookup based on name only.\n.BE\n.SH DESCRIPTION\n.PP\nThis procedure is invoked to retrieve an option from the database\nassociated with \\fItkwin\\fR's main window. If there is an option\nfor \\fItkwin\\fR that matches the given \\fIname\\fR or \\fIclass\\fR,\nthen it is returned in the form of a Tk_Uid. If multiple options\nmatch \\fIname\\fR and \\fIclass\\fR, then the highest-priority one\nis returned. If no option matches, then NULL is returned.\n.PP\n\\fBTk_GetOption\\fR caches options related to \\fItkwin\\fR so that\nsuccessive calls for the same \\fItkwin\\fR will execute much more\nquickly than successive calls for different windows.\n.SH KEYWORDS\nclass, name, option, retrieve\n" }, { "path": "doc/GetPixels.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1998 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetPixelsFromObj 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM, Tk_GetDoublePixelsFromObj \\- translate between strings and screen units\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_GetPixelsFromObj\\fR(\\fIinterp, tkwin, objPtr, intPtr\\fR)\n.sp\nint\n\\fBTk_GetDoublePixelsFromObj\\fR(\\fIinterp, tkwin, objPtr, doublePtr\\fR)\n.sp\nint\n\\fBTk_GetPixels\\fR(\\fIinterp, tkwin, string, intPtr\\fR)\n.sp\nint\n\\fBTk_GetMMFromObj\\fR(\\fIinterp, tkwin, objPtr, doublePtr\\fR)\n.sp\nint\n\\fBTk_GetScreenMM\\fR(\\fIinterp, tkwin, string, doublePtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tcl_Interp\" *joinPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP Tk_Window tkwin in\nWindow whose screen geometry determines the conversion between absolute\nunits and pixels.\n.AP Tcl_Obj *objPtr in/out\nString value specifies a distance on the screen;\ninternal rep will be modified to cache converted distance.\n.AP \"const char\" *string in\nSame as \\fIobjPtr\\fR except specification of distance is passed as\na string.\n.AP int *intPtr out\nPointer to location in which to store converted distance in pixels.\n.AP double *doublePtr out\nPointer to location in which to store converted distance in millimeters.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures take as argument a specification of distance on\nthe screen (\\fIobjPtr\\fR or \\fIstring\\fR) and compute the\ncorresponding distance either in integer pixels or floating-point millimeters.\nIn either case,\n\\fIobjPtr\\fR or \\fIstring\\fR\nspecifies a screen distance as a\nfloating-point number followed by one of the following characters\nthat indicates units:\n.IP \nThe number specifies a distance in pixels.\n.IP \\fBc\\fR\nThe number specifies a distance in centimeters on the screen.\n.IP \\fBi\\fR\nThe number specifies a distance in inches on the screen.\n.IP \\fBm\\fR\nThe number specifies a distance in millimeters on the screen.\n.IP \\fBp\\fR\nThe number specifies a distance in printer's points (1/72 inch)\non the screen.\n.PP\n\\fBTk_GetPixelsFromObj\\fR converts the value of \\fIobjPtr\\fR to the\nnearest even number of pixels and stores that value at \\fI*intPtr\\fR.\nIt returns \\fBTCL_OK\\fR under normal circumstances.\nIf an error occurs (e.g. \\fIobjPtr\\fR contains a number followed\nby a character that is not one of the ones above) then\n\\fBTCL_ERROR\\fR is returned and an error message is left\nin \\fIinterp\\fR's result if \\fIinterp\\fR is not NULL.\n\\fBTk_GetPixelsFromObj\\fR caches information about the return\nvalue in \\fIobjPtr\\fR, which speeds up future calls to\n\\fBTk_GetPixelsFromObj\\fR with the same \\fIobjPtr\\fR.\n.PP\n\\fBTk_GetDoublePixelsFromObj\\fR is identical to \\fBTk_GetPixelsFromObj\\fR\nexcept it returns a double not rounded to the nearest integer.\n.PP\n\\fBTk_GetPixels\\fR is identical to \\fBTk_GetPixelsFromObj\\fR except\nthat the screen distance is specified with a string instead\nof an object. This prevents \\fBTk_GetPixels\\fR from caching the\nreturn value, so \\fBTk_GetPixels\\fR is less efficient than\n\\fBTk_GetPixelsFromObj\\fR.\n.PP\n\\fBTk_GetMMFromObj\\fR and \\fBTk_GetScreenMM\\fR are similar to\n\\fBTk_GetPixelsFromObj\\fR and \\fBTk_GetPixels\\fR (respectively) except\nthat they convert the screen distance to millimeters and\nstore a double-precision floating-point result at \\fI*doublePtr\\fR.\n.SH KEYWORDS\ncentimeters, convert, inches, millimeters, pixels, points, screen units\n" }, { "path": "doc/GetPixmap.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetPixmap 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetPixmap, Tk_FreePixmap \\- allocate and free pixmaps\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nPixmap\n\\fBTk_GetPixmap\\fR(\\fIdisplay, d, width, height, depth\\fR)\n.sp\n\\fBTk_FreePixmap\\fR(\\fIdisplay, pixmap\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Drawable\" *pixelPtr\n.AP Display *display in\nX display for the pixmap.\n.AP Drawable d in\nPixmap or window where the new pixmap will be used for drawing.\n.AP \"int\" width in\nWidth of pixmap.\n.AP \"int\" height in\nHeight of pixmap.\n.AP \"int\" depth in\nNumber of bits per pixel in pixmap.\n.AP Pixmap pixmap in\nPixmap to destroy.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures are identical to the Xlib procedures \\fBXCreatePixmap\\fR\nand \\fBXFreePixmap\\fR, except that they have extra code to manage X\nresource identifiers so that identifiers for deleted pixmaps can be\nreused in the future.\nIt is important for Tk applications to use these procedures rather\nthan \\fBXCreatePixmap\\fR and \\fBXFreePixmap\\fR; otherwise long-running\napplications may run out of resource identifiers.\n.PP\n\\fBTk_GetPixmap\\fR creates a pixmap suitable for drawing in \\fId\\fR,\nwith dimensions given by \\fIwidth\\fR, \\fIheight\\fR, and \\fIdepth\\fR,\nand returns its identifier.\n\\fBTk_FreePixmap\\fR destroys the pixmap given by \\fIpixmap\\fR and makes\nits resource identifier available for reuse.\n.SH KEYWORDS\npixmap, resource identifier\n" }, { "path": "doc/GetRelief.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1998 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetReliefFromObj 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \\- translate between strings and relief values\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_GetReliefFromObj\\fR(\\fIinterp, objPtr, reliefPtr\\fR)\n.sp\nint\n\\fBTk_GetRelief\\fR(\\fIinterp, name, reliefPtr\\fR)\n.sp\nconst char *\n\\fBTk_NameOfRelief\\fR(\\fIrelief\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tcl_Interp\" *reliefPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP Tcl_Obj *objPtr in/out\nString value contains name of relief, one of\n.QW \\fBflat\\fR ,\n.QW \\fBgroove\\fR ,\n.QW \\fBraised\\fR ,\n.QW \\fBridge\\fR ,\n.QW \\fBsolid\\fR ,\nor\n.QW \\fBsunken\\fR\n(or any unique abbreviation thereof on input);\nthe internal rep will be modified to cache corresponding relief value.\n.AP \"const char\" *name in\nSame as \\fIobjPtr\\fR except description of relief is passed as\na string.\n.AP int *reliefPtr out\nPointer to location in which to store relief value corresponding to\n\\fIobjPtr\\fR or \\fIname\\fR.\n.AP int relief in\nRelief value (one of \\fBTK_RELIEF_FLAT\\fR, \\fBTK_RELIEF_RAISED\\fR,\n\\fBTK_RELIEF_SUNKEN\\fR, \\fBTK_RELIEF_GROOVE\\fR, \\fBTK_RELIEF_SOLID\\fR,\nor \\fBTK_RELIEF_RIDGE\\fR).\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetReliefFromObj\\fR places in \\fI*reliefPtr\\fR the relief value\ncorresponding to the value of \\fIobjPtr\\fR. This value will be one of\n\\fBTK_RELIEF_FLAT\\fR, \\fBTK_RELIEF_RAISED\\fR, \\fBTK_RELIEF_SUNKEN\\fR,\n\\fBTK_RELIEF_GROOVE\\fR, \\fBTK_RELIEF_SOLID\\fR, or \\fBTK_RELIEF_RIDGE\\fR.\nUnder normal circumstances the return value is \\fBTCL_OK\\fR and\n\\fIinterp\\fR is unused.\nIf \\fIobjPtr\\fR does not contain one of the valid relief names\nor an abbreviation of one of them, then \\fBTCL_ERROR\\fR is returned,\n\\fI*reliefPtr\\fR is unmodified, and an error message\nis stored in \\fIinterp\\fR's result if \\fIinterp\\fR is not NULL.\n\\fBTk_GetReliefFromObj\\fR caches information about the return\nvalue in \\fIobjPtr\\fR, which speeds up future calls to\n\\fBTk_GetReliefFromObj\\fR with the same \\fIobjPtr\\fR.\n.PP\n\\fBTk_GetRelief\\fR is identical to \\fBTk_GetReliefFromObj\\fR except\nthat the description of the relief is specified with a string instead\nof an object. This prevents \\fBTk_GetRelief\\fR from caching the\nreturn value, so \\fBTk_GetRelief\\fR is less efficient than\n\\fBTk_GetReliefFromObj\\fR.\n.PP\n\\fBTk_NameOfRelief\\fR is the logical inverse of \\fBTk_GetRelief\\fR.\nGiven a relief value it returns the corresponding string (\\fBflat\\fR,\n\\fBraised\\fR, \\fBsunken\\fR, \\fBgroove\\fR, \\fBsolid\\fR, or \\fBridge\\fR).\nIf \\fIrelief\\fR is not a legal relief value, then\n.QW \"unknown relief\"\nis returned.\n.SH KEYWORDS\nname, relief, string\n" }, { "path": "doc/GetRootCrd.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetRootCoords 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetRootCoords \\- Compute root-window coordinates of window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_GetRootCoords\\fR(\\fItkwin, xPtr, yPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window tkwin\n.AP Tk_Window tkwin in\nToken for window.\n.AP int *xPtr out\nPointer to location in which to store root-window x-coordinate\ncorresponding to left edge of \\fItkwin\\fR's border.\n.AP int *yPtr out\nPointer to location in which to store root-window y-coordinate\ncorresponding to top edge of \\fItkwin\\fR's border.\n.BE\n.SH DESCRIPTION\n.PP\nThis procedure scans through the structural information maintained\nby Tk to compute the root-window coordinates corresponding to\nthe upper-left corner of \\fItkwin\\fR's border. If \\fItkwin\\fR has\nno border, then \\fBTk_GetRootCoords\\fR returns the root-window\ncoordinates corresponding to location (0,0) in \\fItkwin\\fR.\n\\fBTk_GetRootCoords\\fR is relatively efficient, since it does not have to\ncommunicate with the X server.\n.SH KEYWORDS\ncoordinates, root window\n" }, { "path": "doc/GetScroll.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetScrollInfo 3 8.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetScrollInfoObj, Tk_GetScrollInfo \\- parse arguments for scrolling commands\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_GetScrollInfoObj\\fR(\\fIinterp, objc, objv, fractionPtr, stepsPtr\\fR)\n.sp\nint\n\\fBTk_GetScrollInfo\\fR(\\fIinterp, argc, argv, fractionPtr, stepsPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tcl_Interp\" *fractionPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP Tcl_Size objc in\nNumber of Tcl_Obj's in \\fIobjv\\fR array.\n.AP \"Tcl_Obj *const *\" objv in\nArgument objects. These represent the entire widget command, of\nwhich the first word is typically the widget name and the second\nword is typically \\fBxview\\fR or \\fByview\\fR.\n.AP int argc in\nNumber of strings in \\fIargv\\fR array.\n.AP \"const char **\" argv in\nArgument strings. These represent the entire widget command, of\nwhich the first word is typically the widget name and the second\nword is typically \\fBxview\\fR or \\fByview\\fR.\n.AP double *fractionPtr out\nFilled in with fraction from \\fBmoveto\\fR option, if any.\n.AP int *stepsPtr out\nFilled in with line or page count from \\fBscroll\\fR option, if any.\nThe value may be negative.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetScrollInfoObj\\fR parses the arguments expected by widget\nscrolling commands such as \\fBxview\\fR and \\fByview\\fR.\nIt receives the entire list of words that make up a widget command\nand parses the words starting with \\fIobjv\\fR[2].\nThe words starting with \\fIobjv\\fR[2] must have one of the following forms:\n.CS\n\\fBmoveto \\fIfraction\\fR\n\\fBscroll \\fInumber\\fB pages\\fR\n\\fBscroll \\fInumber\\fB units\\fR\n.CE\n.LP\nAny of the \\fBmoveto\\fR, \\fBscroll\\fR, \\fBpages\\fR, and \\fBunits\\fR\nkeywords may be abbreviated.\nIf \\fIobjv\\fR has the \\fBmoveto\\fR form, \\fBTK_SCROLL_MOVETO\\fR\nis returned as result and \\fI*fractionPtr\\fR is filled in with the\n\\fIfraction\\fR argument to the command, which must be a proper real\nvalue.\nIf \\fIobjv\\fR has the \\fBscroll\\fR form, \\fBTK_SCROLL_PAGES\\fR\nor \\fBTK_SCROLL_UNITS\\fR is returned and \\fI*stepsPtr\\fR is filled\nin with the \\fInumber\\fR value, which must be a integer or a float,\nbut if it is a float then it is converted to an integer, rounded away from 0.\nIf an error occurs in parsing the arguments, \\fBTK_SCROLL_ERROR\\fR\nis returned and an error message is left in interpreter\n\\fIinterp\\fR's result.\n.PP\n\\fBTk_GetScrollInfo\\fR is identical in function to\n\\fBTk_GetScrollInfoObj\\fR. However, \\fBTk_GetScrollInfo\\fR accepts\nstring arguments, making it more appropriate for use with legacy\nwidgets.\n.SH KEYWORDS\nparse, scrollbar, scrolling command, xview, yview\n" }, { "path": "doc/GetSelect.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetSelection 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetSelection \\- retrieve the contents of a selection\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_GetSelection\\fR(\\fIinterp, tkwin, selection, target, proc, clientData\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_GetSelProc clientData\n.AP Tcl_Interp *interp in\nInterpreter to use for reporting errors.\n.AP Tk_Window tkwin in\nWindow on whose behalf to retrieve the selection (determines\ndisplay from which to retrieve).\n.AP Atom selection in\nThe name of the selection to be retrieved.\n.AP Atom target in\nForm in which to retrieve selection.\n.AP Tk_GetSelProc *proc in\nProcedure to invoke to process pieces of the selection as they\nare retrieved.\n.AP void *clientData in\nArbitrary one-word value to pass to \\fIproc\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetSelection\\fR retrieves the selection specified by the atom\n\\fIselection\\fR in the format specified by \\fItarget\\fR. The\nselection may actually be retrieved in several pieces; as each piece\nis retrieved, \\fIproc\\fR is called to process the piece. \\fIProc\\fR\nshould have arguments and result that match the type\n\\fBTk_GetSelProc\\fR:\n.PP\n.CS\ntypedef int \\fBTk_GetSelProc\\fR(\n void *\\fIclientData\\fR,\n Tcl_Interp *\\fIinterp\\fR,\n char *\\fIportion\\fR);\n.CE\n.PP\nThe \\fIclientData\\fR and \\fIinterp\\fR parameters to \\fIproc\\fR\nwill be copies of the corresponding arguments to\n\\fBTk_GetSelection\\fR. \\fIPortion\\fR will be a pointer to\na string containing part or all of the selection. For large\nselections, \\fIproc\\fR will be called several times with successive\nportions of the selection. The X Inter-Client Communication\nConventions Manual allows a selection to be returned in formats\nother than strings, e.g. as an array of atoms or integers. If\nthis happens, Tk converts the selection back into a string\nbefore calling \\fIproc\\fR. If a selection is returned as an\narray of atoms, Tk converts it to a string containing the atom names\nseparated by white space. For any other format besides string,\nTk converts a selection to a string containing hexadecimal\nvalues separated by white space.\n.PP\n\\fBTk_GetSelection\\fR returns to its caller when the selection has\nbeen completely retrieved and processed by \\fIproc\\fR, or when a\nfatal error has occurred (e.g. the selection owner did not respond\npromptly). \\fBTk_GetSelection\\fR normally returns \\fBTCL_OK\\fR; if\nan error occurs, it returns \\fBTCL_ERROR\\fR and leaves an error message\nin interpreter \\fIinterp\\fR's result. \\fIProc\\fR should also return either\n\\fBTCL_OK\\fR or \\fBTCL_ERROR\\fR. If \\fIproc\\fR encounters an error in\ndealing with the selection, it should leave an error message in the\ninterpreter result and return \\fBTCL_ERROR\\fR; this will abort the\nselection retrieval.\n.SH KEYWORDS\nformat, get, selection retrieval\n" }, { "path": "doc/GetUid.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetUid 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetUid, Tk_Uid \\- convert from string to unique identifier\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Uid\n\\fBTk_GetUid\\fR(\\fIstring\\fR)\n.fi\n.SH ARGUMENTS\n.AP char *string in\nString for which the corresponding unique identifier is\ndesired.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetUid\\fR returns the unique identifier corresponding\nto \\fIstring\\fR.\nUnique identifiers are similar to atoms in Lisp, and are used\nin Tk to speed up comparisons and\nsearches. A unique identifier (type Tk_Uid) is a string pointer\nand may be used anywhere that a variable of type\n.QW \"char *\"\ncould be used. However, there is guaranteed to be exactly\none unique identifier for any given string value. If \\fBTk_GetUid\\fR\nis called twice, once with string \\fIa\\fR and once with string\n\\fIb\\fR, and if \\fIa\\fR and \\fIb\\fR have the same string value\n(strcmp(a, b) == 0), then \\fBTk_GetUid\\fR will return exactly\nthe same Tk_Uid value for each call (Tk_GetUid(a) == Tk_GetUid(b)).\nThis means that variables of type\nTk_Uid may be compared directly (x == y) without having to call\n\\fBstrcmp\\fR.\nIn addition, the return value from \\fBTk_GetUid\\fR will have the\nsame string value as its argument (strcmp(Tk_GetUid(a), a) == 0).\n.SH KEYWORDS\natom, unique identifier\n" }, { "path": "doc/GetVRoot.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetVRootGeometry 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetVRootGeometry \\- Get location and size of virtual root for window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_GetVRootGeometry\\fR(\\fItkwin, xPtr, yPtr, widthPtr, heightPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window heightPtr\n.AP Tk_Window tkwin in\nToken for window whose virtual root is to be queried.\n.AP int xPtr out\nPoints to word in which to store x-offset of virtual root.\n.AP int yPtr out\nPoints to word in which to store y-offset of virtual root.\n.AP \"int\" widthPtr out\nPoints to word in which to store width of virtual root.\n.AP \"int\" heightPtr out\nPoints to word in which to store height of virtual root.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetVRootGeometry\\fR returns geometry information about the virtual\nroot window associated with \\fItkwin\\fR. The\n.QW associated\nvirtual root is the one in which \\fItkwin\\fR's nearest top-level ancestor (or\n\\fItkwin\\fR itself if it is a top-level window) has\nbeen reparented by the window manager. This window is identified by\na \\fB__SWM_ROOT\\fR or \\fB__WM_ROOT\\fR property placed on the top-level\nwindow by the window manager.\nIf \\fItkwin\\fR is not associated with a virtual root (e.g.\nbecause the window manager does not use virtual roots) then *\\fIxPtr\\fR and\n*\\fIyPtr\\fR will be set to 0 and *\\fIwidthPtr\\fR and *\\fIheightPtr\\fR\nwill be set to the dimensions of the screen containing \\fItkwin\\fR.\n.SH KEYWORDS\ngeometry, height, location, virtual root, width, window manager\n" }, { "path": "doc/GetVisual.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_GetVisual 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetVisual \\- translate from string to visual\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nVisual *\n\\fBTk_GetVisual\\fR(\\fIinterp, tkwin, string, depthPtr, colormapPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tcl_Interp\" *colormapPtr\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting.\n.AP Tk_Window tkwin in\nToken for window in which the visual will be used.\n.AP \"const char\" *string in\nString that identifies the desired visual. See below for\nvalid formats.\n.AP int *depthPtr out\nDepth of returned visual gets stored here.\n.AP Colormap *colormapPtr out\nIf non-NULL then a suitable colormap for visual is found and its\nidentifier is stored here.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetVisual\\fR takes a string description of a visual and\nfinds a suitable X Visual for use in \\fItkwin\\fR, if there is one.\nIt returns a pointer to the X Visual structure for the visual\nand stores the number of bits per pixel for it at \\fI*depthPtr\\fR.\nIf \\fIstring\\fR is unrecognizable or if no suitable visual could\nbe found, then NULL is returned and \\fBTk_GetVisual\\fR leaves\nan error message in interpreter \\fIinterp\\fR's result.\nIf \\fIcolormap\\fR is non-NULL then \\fBTk_GetVisual\\fR\nalso locates an appropriate colormap for use with the result visual\nand stores its X identifier at \\fI*colormapPtr\\fR.\n.PP\nThe \\fIstring\\fR argument specifies the desired visual in one\nof the following ways:\n.TP 15\n\\fIclass depth\\fR\n.\nThe string consists of a class name followed by an integer depth,\nwith any amount of white space (including none) in between.\n\\fIclass\\fR selects what sort of visual is desired and must be one of\n\\fBdirectcolor\\fR, \\fBgrayscale\\fR, \\fBgreyscale\\fR, \\fBpseudocolor\\fR,\n\\fBstaticcolor\\fR, \\fBstaticgray\\fR, \\fBstaticgrey\\fR, or\n\\fBtruecolor\\fR, or a unique abbreviation.\n\\fIdepth\\fR specifies how many bits per pixel are needed for the\nvisual.\nIf possible, \\fBTk_GetVisual\\fR will return a visual with this depth;\nif there is no visual of the desired depth then \\fBTk_GetVisual\\fR\nlooks first for a visual with greater depth, then one with less\ndepth.\n.TP 15\n\\fBdefault\\fR\n.\nUse the default visual for \\fItkwin\\fR's screen.\n.TP 15\n\\fIpathName\\fR\n.\nUse the visual for the window given by \\fIpathName\\fR.\n\\fIpathName\\fR must be the name of a window on the same screen\nas \\fItkwin\\fR.\n.TP 15\n\\fInumber\\fR\n.\nUse the visual whose X identifier is \\fInumber\\fR.\n.TP 15\n\\fBbest\\fR ?\\fIdepth\\fR?\n.\nChoose the\n.QW \"best possible\"\nvisual, using the following rules, in decreasing order of priority:\n.RS\n.IP (a)\na visual that has exactly the desired depth is best, followed\nby a visual with greater depth than requested (but as little extra\nas possible), followed by a visual with less depth than requested\n(but as great a depth as possible);\n.IP (b)\nif no \\fIdepth\\fR is specified, then the deepest available visual\nis chosen;\n.IP (c)\n\\fBpseudocolor\\fR is better than \\fBtruecolor\\fR or \\fBdirectcolor\\fR,\nwhich are better than \\fBstaticcolor\\fR, which is better than\n\\fBstaticgray\\fR or \\fBgrayscale\\fR;\n.IP (d)\nthe default visual for the screen is better than any other visual.\n.RE\n.SH CREDITS\n.PP\nThe idea for \\fBTk_GetVisual\\fR, and the first implementation, came\nfrom Paul Mackerras.\n.SH KEYWORDS\ncolormap, screen, visual\n" }, { "path": "doc/Grab.3", "content": "'\\\"\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" All rights reserved.\n'\\\"\n.TH Tk_Grab 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_Grab, Tk_Ungrab \\- manipulate grab state in an application\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_Grab\\fR(\\fIinterp, tkwin, grabGlobal\\fR)\n.sp\n\\fBTk_Ungrab\\fR(\\fItkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AP Tcl_Interp *interp in\nInterpreter to use for error reporting\n.AP Tk_Window tkwin in\nWindow on whose behalf the pointer is to be grabbed or released\n.AP int grabGlobal in\nBoolean indicating whether the grab is global or application local\n.BE\n.SH DESCRIPTION\n.PP\nThese functions are used to set or release a global or\napplication local grab. When a grab is set on a particular window\nin a Tk application, mouse and keyboard events can only be received by\nthat window and its descendants. Mouse and keyboard events for\nwindows outside the tree rooted at \\fItkwin\\fR will be redirected to\n\\fItkwin\\fR. If the grab is global, then all mouse and keyboard\nevents for windows outside the tree rooted at \\fItkwin\\fR (even those\nintended for windows in other applications) will be redirected to\n\\fItkwin\\fR. If the grab is application local, only mouse and\nkeyboard events intended for a windows within the same application\n(but outside the tree rooted at \\fItkwin\\fR) will be redirected.\n.PP\n\\fBTk_Grab\\fR sets a grab on a particular window. \\fITkwin\\fR\nspecifies the window on whose behalf the pointer is to be grabbed.\n\\fIGrabGlobal\\fR indicates whether the grab should be global or\napplication local; if it is non-zero, it means the grab should be\nglobal. Normally, \\fBTk_Grab\\fR returns \\fBTCL_OK\\fR; if an error occurs\nand the grab cannot be set, \\fBTCL_ERROR\\fR is returned and an error message\nis left if \\fIinterp\\fR's result. Once this call completes\nsuccessfully, no window outside the tree rooted at \\fItkwin\\fR will\nreceive pointer- or keyboard-related events until the next call to\nTk_Ungrab. If a previous grab was in effect within the application,\nthen it is replaced with a new one.\n.PP\n\\fBTk_Ungrab\\fR releases a grab on the mouse pointer and keyboard, if\nthere is one set on the window given by \\fItkwin\\fR. Once a grab is\nreleased, pointer and keyboard events will start being delivered to\nother windows again.\n.SH KEYWORDS\ngrab, window\n" }, { "path": "doc/HWNDToWindow.3", "content": "'\\\"\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" All rights reserved.\n'\\\"\n.TH Tk_HWNDToWindow 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_HWNDToWindow \\- Find Tk's window information for a Windows window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Window\n\\fBTk_HWNDToWindow\\fR(\\fIhwnd\\fR)\n.fi\n.SH ARGUMENTS\n.AP HWND hwnd in\nWindows handle for the window.\n.BE\n.SH DESCRIPTION\n.PP\nGiven a Windows HWND window identifier, this procedure returns the\ncorresponding Tk_Window handle. If there is no Tk_Window corresponding\nto \\fIhwnd\\fR then NULL is returned.\n.SH KEYWORDS\nWindows window id\n" }, { "path": "doc/HandleEvent.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_HandleEvent 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_HandleEvent \\- invoke event handlers for window system events\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_HandleEvent\\fR(\\fIeventPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS XEvent *eventPtr\n.AP XEvent *eventPtr in\nPointer to X event to dispatch to relevant handler(s). It is important\nthat all unused fields of the structure be set to zero.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_HandleEvent\\fR is a lower-level procedure that deals with window\nevents. It is called by \\fBTcl_ServiceEvent\\fR (and indirectly by\n\\fBTcl_DoOneEvent\\fR), and in a few other cases within Tk.\nIt makes callbacks to any window event\nhandlers (created by calls to \\fBTk_CreateEventHandler\\fR)\nthat match \\fIeventPtr\\fR and then returns. In some cases\nit may be useful for an application to bypass the Tk event\nqueue and call \\fBTk_HandleEvent\\fR directly instead of\ncalling \\fBTcl_QueueEvent\\fR followed by\n\\fBTcl_ServiceEvent\\fR.\n.PP\nThis procedure may be invoked recursively. For example,\nit is possible to invoke \\fBTk_HandleEvent\\fR recursively\nfrom a handler called by \\fBTk_HandleEvent\\fR. This sort\nof operation is useful in some modal situations, such\nas when a\nnotifier has been popped up and an application wishes to\nwait for the user to click a button in the notifier before\ndoing anything else.\n.SH KEYWORDS\ncallback, event, handler, window\n" }, { "path": "doc/IdToWindow.3", "content": "'\\\"\n'\\\" Copyright (c) 1995-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_IdToWindow 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_IdToWindow \\- Find Tk's window information for an X window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Window\n\\fBTk_IdToWindow\\fR(\\fIdisplay, window\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window display\n.AP Display *display in\nX display containing the window.\n.AP Window window in\nX id for window.\n.BE\n.SH DESCRIPTION\n.PP\nGiven an X window identifier and the X display it corresponds to,\nthis procedure returns the corresponding Tk_Window handle.\nIf there is no Tk_Window corresponding to \\fIwindow\\fR then\nNULL is returned.\n.SH KEYWORDS\nX window id\n" }, { "path": "doc/ImgChanged.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_ImageChanged 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_ImageChanged \\- notify widgets that image needs to be redrawn\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_ImageChanged\\fR(\\fImodel, x, y, width, height, imageWidth, imageHeight\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_ImageModel imageHeight\n.AP Tk_ImageModel model in\nToken for image, which was passed to image's \\fIcreateProc\\fR when\nthe image was created.\n.AP int x in\nX-coordinate of upper-left corner of region that needs redisplay (measured\nfrom upper-left corner of image).\n.AP int y in\nY-coordinate of upper-left corner of region that needs redisplay (measured\nfrom upper-left corner of image).\n.AP \"int\" width in\nWidth of region that needs to be redrawn, in pixels.\n.AP \"int\" height in\nHeight of region that needs to be redrawn, in pixels.\n.AP \"int\" imageWidth in\nCurrent width of image, in pixels.\n.AP \"int\" imageHeight in\nCurrent height of image, in pixels.\n.BE\n.SH DESCRIPTION\n.PP\nAn image manager calls \\fBTk_ImageChanged\\fR for an image\nwhenever anything happens that requires the image to be redrawn.\nAs a result of calling \\fBTk_ImageChanged\\fR, any widgets using\nthe image are notified so that they can redisplay themselves\nappropriately.\nThe \\fImodel\\fR argument identifies the image, and\n\\fIx\\fR, \\fIy\\fR, \\fIwidth\\fR, and \\fIheight\\fR\nspecify a rectangular region within the image that needs to\nbe redrawn.\n\\fIimageWidth\\fR and \\fIimageHeight\\fR specify the image's (new) size.\n.PP\nAn image manager should call \\fBTk_ImageChanged\\fR during\nits \\fIcreateProc\\fR to specify the image's initial size and to\nforce redisplay if there are existing instances for the image.\nIf any of the pixel values in the image should change later on,\n\\fBTk_ImageChanged\\fR should be called again with \\fIx\\fR, \\fIy\\fR,\n\\fIwidth\\fR, and \\fIheight\\fR values that cover all the pixels\nthat changed.\nIf the size of the image should change, then \\fBTk_ImageChanged\\fR\nmust be called to indicate the new size, even if no pixels\nneed to be redisplayed.\n.SH \"SEE ALSO\"\nTk_CreateImageType\n.SH KEYWORDS\nimages, redisplay, image size changes\n" }, { "path": "doc/Inactive.3", "content": "'\\\"\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" All rights reserved.\n'\\\"\n.TH Tk_GetUserInactiveTime 3 8.5 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetUserInactiveTime, Tk_ResetUserInactiveTime \\- discover user inactivity time\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nlong\n\\fBTk_GetUserInactiveTime\\fR(\\fIdisplay\\fR)\n.sp\n\\fBTk_ResetUserInactiveTime\\fR(\\fIdisplay\\fR)\n.fi\n.SH ARGUMENTS\n.AS Display *display\n.AP Display *display in\nThe display on which the user inactivity timer is to be queried or\nreset.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_GetUserInactiveTime\\fR returns the number of milliseconds that\nhave passed since the last user interaction (usually via keyboard or\nmouse) with the respective display. On systems and displays that do not\nsupport querying the user inactivity time, \\fB\\-1\\fR is returned.\n\\fBTk_ResetUserInactiveTime\\fR resets the user inactivity timer of the\ngiven display to zero. On windowing systems that do not support\nmultiple displays \\fIdisplay\\fR can be passed as \\fBNULL\\fR.\n.SH KEYWORDS\nidle, inactive\n" }, { "path": "doc/InternAtom.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_InternAtom 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_InternAtom, Tk_GetAtomName \\- manage cache of X atoms\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nAtom\n\\fBTk_InternAtom\\fR(\\fItkwin, name\\fR)\n.sp\nconst char *\n\\fBTk_GetAtomName\\fR(\\fItkwin, atom\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window parent\n.AP Tk_Window tkwin in\nToken for window. Used to map atom or name relative to a particular display.\n.AP \"const char\" *name in\nString name for which atom is desired.\n.AP Atom atom in\nAtom for which corresponding string name is desired.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures are similar to the Xlib procedures\n\\fBXInternAtom\\fR and \\fBXGetAtomName\\fR. \\fBTk_InternAtom\\fR\nreturns the atom identifier associated with string given by\n\\fIname\\fR; the atom identifier is only valid for the display\nassociated with \\fItkwin\\fR.\n\\fBTk_GetAtomName\\fR returns the string associated\nwith \\fIatom\\fR on \\fItkwin\\fR's display. The string returned\nby \\fBTk_GetAtomName\\fR is in Tk's storage: the caller need\nnot free this space when finished with the string, and the caller\nshould not modify the contents of the returned string.\nIf there is no atom \\fIatom\\fR on \\fItkwin\\fR's display,\nthen \\fBTk_GetAtomName\\fR returns the string\n.QW \"?bad atom?\" .\n.PP\nTk caches\nthe information returned by \\fBTk_InternAtom\\fR and \\fBTk_GetAtomName\\fR\nso that future calls\nfor the same information can be serviced from the cache without\ncontacting the server. Thus \\fBTk_InternAtom\\fR and \\fBTk_GetAtomName\\fR\nare generally much faster than their Xlib counterparts, and they\nshould be used in place of the Xlib procedures.\n.SH KEYWORDS\natom, cache, display\n" }, { "path": "doc/MainLoop.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_MainLoop 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_MainLoop \\- loop for events until all windows are deleted\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_MainLoop\\fR()\n.fi\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_MainLoop\\fR is a procedure that loops repeatedly calling\n\\fBTcl_DoOneEvent\\fR. It returns only when there are no applications\nleft in this process (i.e. no main windows exist anymore). Most\nwindowing applications will call \\fBTk_MainLoop\\fR after\ninitialization; the main execution of the application will consist\nentirely of callbacks invoked via \\fBTcl_DoOneEvent\\fR.\n.SH KEYWORDS\napplication, event, main loop\n" }, { "path": "doc/MainWin.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_MainWindow 3 7.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_MainWindow, Tk_GetNumMainWindows \\- functions for querying main window information\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Window\n\\fBTk_MainWindow\\fR(\\fIinterp\\fR)\n.sp\n\\fBTk_SetMainMenubar\\fR(\\fIinterp, tkwin, menuName\\fR)\n.sp\n\\fBTk_SetWindowMenubar\\fR(\\fIinterp, tkwin, oldMenuName, menuName\\fR)\n.sp\nint\n\\fBTk_GetNumMainWindows\\fR()\n.fi\n.SH ARGUMENTS\n.AS Tcl_Interp *pathName\n.AP Tcl_Interp *interp in/out\nInterpreter associated with the application.\n.AP Tk_Window tkwin in\nToken for main window.\n.AP const char *menuName in\nThe name of the new menubar that the toplevel needs to be set to.\nNULL means that their is no menu now.\n.AP const char *oldMenuName in\nThe name of the menubar previously set in this toplevel.\nNULL means no menu was set previously.\n.BE\n.SH DESCRIPTION\n.PP\nA main window is a special kind of toplevel window used as the\noutermost window in an application.\n.PP\nIf \\fIinterp\\fR is associated with a Tk application then \\fBTk_MainWindow\\fR\nreturns the application's main window. If there is no Tk application\nassociated with \\fIinterp\\fR then \\fBTk_MainWindow\\fR returns NULL and\nleaves an error message in interpreter \\fIinterp\\fR's result.\n.PP\n\\fBTk_GetNumMainWindows\\fR returns a count of the number of main\nwindows currently open in the current thread.\n\\fBTk_SetMainMenubar\\fR\nCalled when a toplevel widget is brought to front. On the Macintosh,\nsets up the menubar that goes across the top of the main monitor. On\nother platforms, nothing is necessary.\n\\fBTk_SetWindowMenubar\\fR associates a menu with a window.\nThe old menu clones for the menubar are thrown away, and a handler is\nset up to allocate the new ones.\n.SH KEYWORDS\napplication, main window\n" }, { "path": "doc/MaintGeom.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_MaintainGeometry 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_MaintainGeometry, Tk_UnmaintainGeometry \\- maintain geometry of one window relative to another\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_MaintainGeometry\\fR(\\fIwindow, container, x, y, width, height\\fR)\n.sp\n\\fBTk_UnmaintainGeometry\\fR(\\fIwindow, container\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window container\n.AP Tk_Window window in\nWindow whose geometry is to be controlled.\n.AP Tk_Window container in\nWindow relative to which \\fIwindow\\fR's geometry will be controlled.\n.AP int x in\nDesired x-coordinate of \\fIwindow\\fR in \\fIcontainer\\fR, measured in pixels\nfrom the inside of \\fIcontainer\\fR's left border to the outside of\n\\fIwindow\\fR's left border.\n.AP int y in\nDesired y-coordinate of \\fIwindow\\fR in \\fIcontainer\\fR, measured in pixels\nfrom the inside of \\fIcontainer\\fR's top border to the outside of\n\\fIwindow\\fR's top border.\n.AP int width in\nDesired width for \\fIwindow\\fR, in pixels.\n.AP int height in\nDesired height for \\fIwindow\\fR, in pixels.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_MaintainGeometry\\fR and \\fBTk_UnmaintainGeometry\\fR make it\neasier for geometry managers to deal with windows whose containers are not\ntheir parents.\nThree problems arise if the container for a window is not its parent:\n.IP [1]\nThe x- and y-position of the window must be translated from the\ncoordinate system of the container to that of the parent before\npositioning the window.\n.IP [2]\nIf the container window, or any of its ancestors up to the window's\nparent, is moved, then the window must be repositioned within its\nparent in order to maintain the correct position relative to the\ncontainer.\n.IP [3]\nIf the container or one of its ancestors is mapped or unmapped, then\nthe window must be mapped or unmapped to correspond.\n.LP\nNone of these problems is an issue if the parent and container are\nthe same. For example, if the container or one of its ancestors\nis unmapped, the window is automatically removed by the screen\nby X.\n.PP\n\\fBTk_MaintainGeometry\\fR deals with these problems for windows\nwhose containers are not their parents, as well as handling the simpler\ncase of windows whose container are their parents.\n\\fBTk_MaintainGeometry\\fR is typically called by a window manager\nonce it has decided where a window should be positioned relative\nto its container.\n\\fBTk_MaintainGeometry\\fR translates the coordinates to the\ncoordinate system of \\fIwindow\\fR's parent and then moves and\nresizes the window appropriately.\nFurthermore, it remembers the desired position and creates event\nhandlers to monitor the container and all of its ancestors up\nto (but not including) the window's parent.\nIf any of these windows is moved, mapped, or unmapped,\nthe window will be adjusted so that it is mapped only when the\ncontainer is mapped and its geometry relative to the container\nremains as specified by \\fIx\\fR, \\fIy\\fR, \\fIwidth\\fR, and\n\\fIheight\\fR.\n.PP\nWhen a window manager relinquishes control over a window, or\nif it decides that it does not want the window to appear on the\nscreen under any conditions, it calls \\fBTk_UnmaintainGeometry\\fR.\n\\fBTk_UnmaintainGeometry\\fR unmaps the window and cancels any\nprevious calls to \\fBTk_MaintainGeometry\\fR for the\n\\fIcontainer\\fR\\-\\fIwindow\\fR pair, so that the window's\ngeometry and mapped state are no longer maintained\nautomatically.\n\\fBTk_UnmaintainGeometry\\fR need not be called by a geometry\nmanager if the window, the container, or any of the container's ancestors\nis destroyed: Tk will call it automatically.\n.PP\nIf \\fBTk_MaintainGeometry\\fR is called repeatedly for the same\n\\fIcontainer\\fR\\-\\fIwindow\\fR pair, the information from the most\nrecent call supersedes any older information.\nIf \\fBTk_UnmaintainGeometry\\fR is called for a \\fIcontainer\\fR\\-\\fIwindow\\fR\npair that is is not currently managed, the call has no effect.\n.SH KEYWORDS\ngeometry manager, map, container, parent, position, window, unmap\n" }, { "path": "doc/ManageGeom.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_ManageGeometry 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_ManageGeometry \\- arrange to handle geometry requests for a window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_ManageGeometry\\fR(\\fItkwin, mgrPtr, clientData\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_GeometryProc clientData\n.AP Tk_Window tkwin in\nToken for window to be managed.\n.AP \"const Tk_GeomMgr\" *mgrPtr in\nPointer to data structure containing information about the\ngeometry manager, or NULL to indicate that \\fItkwin\\fR's geometry\nshould not be managed anymore.\nThe data structure pointed to by \\fImgrPtr\\fR must be static:\nTk keeps a reference to it as long as the window is managed.\n.AP void *clientData in\nArbitrary one-word value to pass to geometry manager callbacks.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_ManageGeometry\\fR arranges for a particular geometry manager,\ndescribed by the \\fImgrPtr\\fR argument, to control the geometry\nof a particular content window, given by \\fItkwin\\fR.\nIf \\fItkwin\\fR was previously managed by some other geometry manager,\nthe previous manager loses control in favor of the new one.\nIf \\fImgrPtr\\fR is NULL, geometry management is cancelled for\n\\fItkwin\\fR.\n.PP\nThe structure pointed to by \\fImgrPtr\\fR contains information about\nthe geometry manager:\n.CS\ntypedef struct {\n const char *\\fIname\\fR;\n Tk_GeomRequestProc *\\fIrequestProc\\fR;\n Tk_GeomLostContentProc *\\fIlostContentProc\\fR;\n} \\fBTk_GeomMgr\\fR;\n.CE\nThe \\fIname\\fR field is the textual name for the geometry manager,\nsuch as \\fBpack\\fR or \\fBplace\\fR; this value will be returned\nby the command \\fBwinfo manager\\fR.\n.PP\n\\fIrequestProc\\fR is a procedure in the geometry manager that\nwill be invoked whenever \\fBTk_GeometryRequest\\fR is called by the\ncontent window to change its desired geometry.\n\\fIrequestProc\\fR should have arguments and results that match the\ntype \\fBTk_GeomRequestProc\\fR:\n.CS\ntypedef void \\fBTk_GeomRequestProc\\fR(\n void *\\fIclientData\\fR,\n Tk_Window \\fItkwin\\fR);\n.CE\nThe parameters to \\fIrequestProc\\fR will be identical to the\ncorresponding parameters passed to \\fBTk_ManageGeometry\\fR.\n\\fIclientData\\fR usually points to a data\nstructure containing application-specific information about\nhow to manage \\fItkwin\\fR's geometry.\n.PP\nThe \\fIlostContentProc\\fR field of \\fImgrPtr\\fR points to another\nprocedure in the geometry manager.\nTk will invoke \\fIlostContentProc\\fR if some other manager\ncalls \\fBTk_ManageGeometry\\fR to claim\n\\fItkwin\\fR away from the current geometry manager.\n\\fIlostContentProc\\fR is not invoked if \\fBTk_ManageGeometry\\fR is\ncalled with a NULL value for \\fImgrPtr\\fR (presumably the current\ngeometry manager has made this call, so it already knows that the\nwindow is no longer managed), nor is it called if \\fImgrPtr\\fR\nis the same as the window's current geometry manager.\n\\fIlostContentProc\\fR should have\narguments and results that match the following prototype:\n.CS\ntypedef void \\fBTk_GeomLostContentProc\\fR(\n void *\\fIclientData\\fR,\n Tk_Window \\fItkwin\\fR);\n.CE\nThe parameters to \\fIlostContentProc\\fR will be identical to the\ncorresponding parameters passed to \\fBTk_ManageGeometry\\fR.\n.SH KEYWORDS\ncallback, geometry, managed, request, unmanaged\n" }, { "path": "doc/MapWindow.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1997 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_MapWindow 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_MapWindow, Tk_UnmapWindow \\- map or unmap a window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Window\n\\fBTk_MapWindow\\fR(\\fItkwin\\fR)\n.sp\n\\fBTk_UnmapWindow\\fR(\\fItkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window parent\n.AP Tk_Window tkwin in\nToken for window.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures may be used to map and unmap windows\nmanaged by Tk. \\fBTk_MapWindow\\fR maps the window given\nby \\fItkwin\\fR, and also creates an X window corresponding\nto \\fItkwin\\fR if it does not already exist. See the\n\\fBTk_CreateWindow\\fR manual entry for information on\ndeferred window creation.\n\\fBTk_UnmapWindow\\fR unmaps \\fItkwin\\fR's window\nfrom the screen.\n.PP\nIf \\fItkwin\\fR is a child window (i.e. \\fBTk_CreateWindow\\fR was\nused to create a child window), then event handlers interested in map\nand unmap events are invoked immediately. If \\fItkwin\\fR is not an\ninternal window, then the event handlers will be invoked later, after\nX has seen the request and returned an event for it.\n.PP\nThese procedures should be used in place of the X procedures\n\\fBXMapWindow\\fR and \\fBXUnmapWindow\\fR, since they update\nTk's local data structure for \\fItkwin\\fR. Applications\nusing Tk should not invoke \\fBXMapWindow\\fR and \\fBXUnmapWindow\\fR\ndirectly.\n.SH KEYWORDS\nmap, unmap, window\n" }, { "path": "doc/MeasureChar.3", "content": "'\\\"\n'\\\" Copyright (c) 1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_MeasureChars 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_MeasureChars, Tk_MeasureCharsInContext, Tk_TextWidth, Tk_DrawChars, Tk_DrawCharsInContext,\nTk_UnderlineChars, Tk_UnderlineCharsInContext \\- routines to measure and display simple single-line strings.\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_MeasureChars\\fR(\\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\\fR)\n.sp\nint\n\\fBTk_MeasureCharsInContext\\fR(\\fItkfont, string, numBytes, rangeStart, rangeLength, maxPixels, flags, lengthPtr\\fR)\n.sp\nint\n\\fBTk_TextWidth\\fR(\\fItkfont, string, numBytes\\fR)\n.sp\n\\fBTk_DrawChars\\fR(\\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\\fR)\n.sp\n\\fBTk_DrawCharsInContext\\fR(\\fIdisplay, drawable, gc, tkfont, string, numBytes, rangeStart, rangeLength, x, y\\fR)\n.sp\n\\fBTk_UnderlineChars\\fR(\\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\\fR)\n.sp\n\\fBTk_UnderlineCharsInContext\\fR(\\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y, firstByte, lastByte\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"const char\" firstChar\n.AP Tk_Font tkfont in\nToken for font in which text is to be drawn or measured. Must have been\nreturned by a previous call to \\fBTk_GetFont\\fR.\n.AP \"const char\" *string in\nText to be measured or displayed. Need not be null terminated. Any\nnon-printing meta-characters in the string (such as tabs, newlines, and\nother control characters) will be measured or displayed in a\nplatform-dependent manner.\n.AP Tcl_Size numBytes in\nThe maximum number of bytes to consider when measuring or drawing\n\\fIstring\\fR. Must be greater than or equal to 0.\n.AP int maxPixels in\nIf \\fImaxPixels\\fR is >= 0, it specifies the longest permissible\nline length in pixels. Characters from \\fIstring\\fR are processed only\nuntil this many pixels have been covered. If \\fImaxPixels\\fR is < 0, then\nthe line length is unbounded and the \\fIflags\\fR argument is ignored.\n.AP int flags in\nVarious flag bits OR-ed together: \\fBTK_PARTIAL_OK\\fR means include a character\nas long as any part of it fits in the length given by \\fImaxPixels\\fR;\notherwise, a character must fit completely to be considered.\n\\fBTK_WHOLE_WORDS\\fR means stop on a word boundary, if possible. If\n\\fBTK_AT_LEAST_ONE\\fR is set, it means return at least one character even if no\ncharacters could fit in the length given by \\fImaxPixels\\fR. If\n\\fBTK_AT_LEAST_ONE\\fR is set and \\fBTK_WHOLE_WORDS\\fR is also set, it means\nthat if not even one word fits on the line, return the first few letters of the\nword that did fit; if not even one letter of the word fit, then the first\nletter will still be returned.\n\\fBTK_ISOLATE_END\\fR means that the last character should not be considered in\ncontext with the rest of the string (used for breaking lines, with the\nTk_*InContext variants of the functions only).\n.AP int *lengthPtr out\nFilled with the number of pixels occupied by the number of characters\nreturned as the result of \\fBTk_MeasureChars\\fR.\n.AP Display *display in\nDisplay on which to draw.\n.AP Drawable drawable in\nWindow or pixmap in which to draw.\n.AP GC gc in\nGraphics context for drawing characters. The font selected into this GC\nmust be the same as the \\fItkfont\\fR.\n.AP int \"x, y\" in\nCoordinates at which to place the left edge of the baseline when displaying\n\\fIstring\\fR.\n.AP int firstByte in\nThe index of the first byte of the first character to underline in the\n\\fIstring\\fR. Underlining begins at the left edge of this character.\n.AP int lastByte in\nThe index of the first byte of the last character up to which the\nunderline will be drawn. The character specified by \\fIlastByte\\fR\nwill not itself be underlined.\n.AP Tcl_Size rangeStart in\nIndex of first byte to draw or to measure.\n.AP Tcl_Size rangeLength in\nLength of range to draw or to measure, in bytes.\n.BE\n.SH DESCRIPTION\n.PP\nThese routines are for measuring and displaying simple single-font,\nsingle-line strings. To measure and display single-font, multi-line,\njustified text, refer to the documentation for \\fBTk_ComputeTextLayout\\fR.\nThere is no programming interface in the core of Tk that supports\nmulti-font, multi-line text; support for that behavior must be built on\ntop of simpler layers.\nNote that the interfaces described here are\nbyte-oriented not character-oriented, so index values coming from Tcl\nscripts need to be converted to byte offsets using the\n\\fBTcl_UtfAtIndex\\fR and related routines.\n.PP\nA glyph is the displayable picture of a letter, number, or some other\nsymbol. Not all character codes in a given font have a glyph.\nCharacters such as tabs, newlines/returns, and control characters that\nhave no glyph are measured and displayed by these procedures in a\nplatform-dependent manner; under X, they are replaced with backslashed\nescape sequences, while under Windows and Macintosh hollow or solid boxes\nmay be substituted. Refer to the documentation for\n\\fBTk_ComputeTextLayout\\fR for a programming interface that supports the\nplatform-independent expansion of tab characters into columns and\nnewlines/returns into multi-line text.\n.PP\n\\fBTk_MeasureChars\\fR is used both to compute the length of a given\nstring and to compute how many characters from a string fit in a given\namount of space. The return value is the number of bytes from\n\\fIstring\\fR that fit in the space specified by \\fImaxPixels\\fR subject to\nthe conditions described by \\fIflags\\fR. If all characters fit, the return\nvalue will be \\fInumBytes\\fR. \\fI*lengthPtr\\fR is filled with the computed\nwidth, in pixels, of the portion of the string that was measured. For\nexample, if the return value is 5, then \\fI*lengthPtr\\fR is filled with the\ndistance between the left edge of \\fIstring\\fR[0] and the right edge of\n\\fIstring\\fR[4].\n.PP\n\\fBTk_TextWidth\\fR is a wrapper function that provides a simpler interface\nto the \\fBTk_MeasureChars\\fR function. The return value is how much\nspace in pixels the given \\fIstring\\fR needs.\n.PP\n\\fBTk_DrawChars\\fR draws the \\fIstring\\fR at the given location in the\ngiven \\fIdrawable\\fR.\n.PP\n\\fBTk_UnderlineChars\\fR underlines the given range of characters in the\ngiven \\fIstring\\fR. It does not draw the characters (which are assumed to\nhave been displayed previously by \\fBTk_DrawChars\\fR); it just draws the\nunderline. This procedure is used to underline a few characters without\nhaving to construct an underlined font. To produce natively underlined\ntext, the appropriate underlined font should be constructed and used.\n.PP\n\\fBTk_MeasureCharsInContext\\fR, \\fBTk_DrawCharsInContext\\fR,\n\\fBTk_UnderlineCharsInContext\\fR are variants of respectively\n\\fBTk_MeasureChars\\fR, \\fBTk_DrawChars\\fR and \\fBTk_UnderlineChars\\fR,\nbut with access to all the characters on the line for context. Except\non macOS, this context isn't actually consulted (meaning the out of\ncontext variants are called).\n.SH \"SEE ALSO\"\nfont(n), FontId(3)\n.SH KEYWORDS\nfont, measurement\n" }, { "path": "doc/MoveToplev.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1993 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_MoveToplevelWindow 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_MoveToplevelWindow \\- Adjust the position of a top-level window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_MoveToplevelWindow\\fR(\\fItkwin, x, y\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window tkwin\n.AP Tk_Window tkwin in\nToken for top-level window to move.\n.AP int x in\nNew x-coordinate for the top-left pixel of \\fItkwin\\fR's border, or the\ntop-left pixel of the decorative border supplied for \\fItkwin\\fR by the\nwindow manager, if there is one.\n.AP int y in\nNew y-coordinate for the top-left pixel of \\fItkwin\\fR's border, or the\ntop-left pixel of the decorative border supplied for \\fItkwin\\fR by the\nwindow manager, if there is one.\n.BE\n.SH DESCRIPTION\n.PP\nIn general, a window should never set its own position; this should be\ndone only by the geometry manger that is responsible for the window.\nFor top-level windows the window manager is effectively the geometry\nmanager; Tk provides interface code between the application and the\nwindow manager to convey the application's desires to the geometry\nmanager. The desired size for a top-level window is conveyed using\nthe usual \\fBTk_GeometryRequest\\fR mechanism. The procedure\n\\fBTk_MoveToplevelWindow\\fR may be used by an application to request\na particular position for a top-level window; this procedure is\nsimilar in function to the \\fBwm geometry\\fR Tcl command except that\nnegative offsets cannot be specified. It is invoked by widgets such as\nmenus that want to appear at a particular place on the screen.\n.PP\nWhen \\fBTk_MoveToplevelWindow\\fR is called it does not immediately\npass on the new desired location to the window manager; it defers\nthis action until all other outstanding work has been completed,\nusing the \\fBTcl_DoWhenIdle\\fR mechanism.\n.SH KEYWORDS\nposition, top-level window, window manager\n" }, { "path": "doc/Name.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1997 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_Name 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_Name, Tk_PathName, Tk_NameToWindow \\- convert between names and window tokens\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Uid\n\\fBTk_Name\\fR(\\fItkwin\\fR)\n.sp\nchar *\n\\fBTk_PathName\\fR(\\fItkwin\\fR)\n.sp\nTk_Window\n\\fBTk_NameToWindow\\fR(\\fIinterp, pathName, tkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tcl_Interp *pathName\n.AP Tk_Window tkwin in\nToken for window.\n.AP Tcl_Interp *interp out\nInterpreter to use for error reporting (can be NULL).\n.AP \"const char\" *pathName in\nCharacter string containing path name of window.\n.BE\n.SH DESCRIPTION\n.PP\nEach window managed by Tk has two names, a short name that identifies\na window among children of the same parent, and a path name that\nidentifies the window uniquely among all the windows belonging to the\nsame main window. The path name is used more often in Tk than the\nshort name; many commands, like \\fBbind\\fR, expect path names as\narguments.\n.PP\nThe \\fBTk_Name\\fR macro returns a window's\nshort name, which is the same as the \\fIname\\fR argument\npassed to \\fBTk_CreateWindow\\fR when\nthe window was created. The value is returned\nas a Tk_Uid, which may be used just like a string pointer but also has\nthe properties of a unique identifier (see the manual entry for\n\\fBTk_GetUid\\fR for details).\n.PP\nThe \\fBTk_PathName\\fR macro returns a hierarchical name for \\fItkwin\\fR.\nPath names have a structure similar to file names in Unix but with\ndots between elements instead of slashes: the main window for\nan application has the path name\n.QW . ;\nits children have names like\n.QW .a\nand\n.QW .b ;\ntheir children have names like\n.QW .a.aa\nand\n.QW .b.bb ;\nand so on. A window is considered to be a child of\nanother window for naming purposes if the second window was named\nas the first window's \\fIparent\\fR when the first window was created.\nThis is not always the same as the X window hierarchy. For\nexample, a pop-up\nis created as a child of the root window, but its logical parent will\nusually be a window within the application.\n.PP\nThe procedure \\fBTk_NameToWindow\\fR returns the token for a window\ngiven its path name (the \\fIpathName\\fR argument) and another window\nbelonging to the same main window (\\fItkwin\\fR). It normally\nreturns a token for the named window, but if no such window exists\n\\fBTk_NameToWindow\\fR leaves an error message in interpreter\n\\fIinterp\\fR's result\nand returns NULL. The \\fItkwin\\fR argument to \\fBTk_NameToWindow\\fR\nis needed because path names are only unique within a single\napplication hierarchy. If, for example, a single process has opened\ntwo main windows, each will have a separate naming hierarchy and the\nsame path name might appear in each of the hierarchies. Normally\n\\fItkwin\\fR is the main window of the desired hierarchy, but this\nneed not be the case: any window in the desired hierarchy may be used.\n.SH KEYWORDS\nname, path name, token, window\n" }, { "path": "doc/NameOfImg.3", "content": "'\\\"\n'\\\" Copyright (c) 1995-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_NameOfImage 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_NameOfImage \\- Return name of image.\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nconst char *\n\\fBTk_NameOfImage\\fR(\\fIimageModel\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_ImageModel imageModel\n.AP Tk_ImageModel imageModel in\nToken for image, which was passed to image manager's \\fIcreateProc\\fR when\nthe image was created.\n.BE\n.SH DESCRIPTION\n.PP\nThis procedure is invoked by image managers to find out the name\nof an image. Given the token for the image, it returns the\nstring name for the image.\n.SH KEYWORDS\nimage manager, image name\n" }, { "path": "doc/OwnSelect.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_OwnSelection 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_OwnSelection \\- make a window the owner of the primary selection\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_OwnSelection\\fR(\\fItkwin, selection, proc, clientData\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_LostSelProc clientData\n.AP Tk_Window tkwin in\nWindow that is to become new selection owner.\n.AP Atom selection in\nThe name of the selection to be owned, such as XA_PRIMARY.\n.AP Tk_LostSelProc *proc in\nProcedure to invoke when \\fItkwin\\fR loses selection ownership later.\n.AP void *clientData in\nArbitrary one-word value to pass to \\fIproc\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_OwnSelection\\fR arranges for \\fItkwin\\fR to become the\nnew owner of the selection specified by the atom\n\\fIselection\\fR. After this call completes, future requests\nfor the selection will be directed to handlers created for\n\\fItkwin\\fR using \\fBTk_CreateSelHandler\\fR. When \\fItkwin\\fR\neventually loses the selection ownership, \\fIproc\\fR will be\ninvoked so that the window can clean itself up (e.g. by\nunhighlighting the selection). \\fIProc\\fR should have arguments and\nresult that match the type \\fBTk_LostSelProc\\fR:\n.CS\ntypedef void \\fBTk_LostSelProc\\fR(\n void *\\fIclientData\\fR);\n.CE\nThe \\fIclientData\\fR parameter to \\fIproc\\fR is a copy of the\n\\fIclientData\\fR argument given to \\fBTk_OwnSelection\\fR, and is\nusually a pointer to a data structure containing application-specific\ninformation about \\fItkwin\\fR.\n.SH KEYWORDS\nown, selection owner\n" }, { "path": "doc/ParseArgv.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_ParseArgv 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_ParseArgv \\- process command-line options\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_ParseArgv\\fR(\\fIinterp, tkwin, argcPtr, argv, argTable, flags\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_ArgvInfo *argTable\n.AP Tcl_Interp *interp in\nInterpreter to use for returning error messages.\n.AP Tk_Window tkwin in\nWindow to use when arguments specify Tk options. If NULL, then\nno Tk options will be processed.\n.AP int argcPtr in/out\nPointer to number of arguments in argv; gets modified to hold\nnumber of unprocessed arguments that remain after the call.\n.AP \"const char\" **argv in/out\nCommand line arguments passed to main program. Modified to\nhold unprocessed arguments that remain after the call.\n.AP Tk_ArgvInfo *argTable in\nArray of argument descriptors, terminated by element with\ntype \\fBTK_ARGV_END\\fR.\n.AP int flags in\nIf non-zero, then it specifies one or more flags that control the\nparsing of arguments. Different flags may be OR'ed together.\nThe flags currently defined are \\fBTK_ARGV_DONT_SKIP_FIRST_ARG\\fR,\n\\fBTK_ARGV_NO_ABBREV\\fR, \\fBTK_ARGV_NO_LEFTOVERS\\fR, and\n\\fBTK_ARGV_NO_DEFAULTS\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_ParseArgv\\fR processes an array of command-line arguments according\nto a table describing the kinds of arguments that are expected.\nEach of the arguments in \\fIargv\\fR is processed in turn: if it matches\none of the entries in \\fIargTable\\fR, the argument is processed\naccording to that entry and discarded. The arguments that do not\nmatch anything in \\fIargTable\\fR are copied down to the beginning\nof \\fIargv\\fR (retaining their original order) and returned to\nthe caller. At the end of the call\n\\fBTk_ParseArgv\\fR sets \\fI*argcPtr\\fR to hold the number of\narguments that are left in \\fIargv\\fR, and \\fIargv[*argcPtr]\\fR\nwill hold the value NULL. Normally, \\fBTk_ParseArgv\\fR\nassumes that \\fIargv[0]\\fR is a command name, so it is treated like\nan argument that does not match \\fIargTable\\fR and returned to the\ncaller; however, if the \\fBTK_ARGV_DONT_SKIP_FIRST_ARG\\fR bit is set in\n\\fIflags\\fR then \\fIargv[0]\\fR will be processed just like the other\nelements of \\fIargv\\fR.\n.PP\n\\fBTk_ParseArgv\\fR normally returns the value \\fBTCL_OK\\fR. If an error\noccurs while parsing the arguments, then \\fBTCL_ERROR\\fR is returned and\n\\fBTk_ParseArgv\\fR will leave an error message in the result of\ninterpreter \\fIinterp\\fR in the standard Tcl fashion. In\nthe event of an error return, \\fI*argvPtr\\fR will not have been\nmodified, but \\fIargv\\fR could have been partially modified. The\npossible causes of errors are explained below.\n.PP\nThe \\fIargTable\\fR array specifies the kinds of arguments that are\nexpected; each of its entries has the following structure:\n.CS\ntypedef struct {\n const char *\\fIkey\\fR;\n int \\fItype\\fR;\n void *\\fIsrc\\fR;\n void *\\fIdst\\fR;\n const char *\\fIhelp\\fR;\n} \\fBTk_ArgvInfo\\fR;\n.CE\nThe \\fIkey\\fR field is a string such as\n.QW \\-display\nor\n.QW \\-bg\nthat is compared with the values in \\fIargv\\fR. \\fIType\\fR\nindicates how to process an argument that matches \\fIkey\\fR\n(more on this below). \\fISrc\\fR and \\fIdst\\fR are additional\nvalues used in processing the argument. Their exact usage\ndepends on \\fItype\\fR, but typically \\fIsrc\\fR indicates\na value and \\fIdst\\fR indicates where to store the\nvalue. The \\fBchar *\\fR declarations for \\fIsrc\\fR and \\fIdst\\fR\nare placeholders: the actual types may be different. Lastly,\n\\fIhelp\\fR is a string giving a brief description\nof this option; this string is printed when users ask for help\nabout command-line options.\n.PP\nWhen processing an argument in \\fIargv\\fR, \\fBTk_ParseArgv\\fR\ncompares the argument to each of the \\fIkey\\fR's in \\fIargTable\\fR.\n\\fBTk_ParseArgv\\fR selects the first specifier whose \\fIkey\\fR matches\nthe argument exactly, if such a specifier exists. Otherwise\n\\fBTk_ParseArgv\\fR selects a specifier for which the argument\nis a unique abbreviation. If the argument is a unique abbreviation\nfor more than one specifier, then an error is returned. If there\nis no matching entry in \\fIargTable\\fR, then the argument is\nskipped and returned to the caller.\n.PP\nOnce a matching argument specifier is found, \\fBTk_ParseArgv\\fR\nprocesses the argument according to the \\fItype\\fR field of the\nspecifier. The argument that matched \\fIkey\\fR is called\n.QW \"the matching argument\"\nin the descriptions below. As part of the processing,\n\\fBTk_ParseArgv\\fR may also use the next argument in \\fIargv\\fR\nafter the matching argument, which is called\n.QW \"the following argument\" .\nThe legal values for \\fItype\\fR, and the processing\nthat they cause, are as follows:\n.IP \\fBTK_ARGV_END\\fR\nMarks the end of the table. The last entry in \\fIargTable\\fR\nmust have this type; all of its other fields are ignored and it\nwill never match any arguments.\n.IP \\fBTK_ARGV_CONSTANT\\fR\n\\fISrc\\fR is treated as an integer and \\fIdst\\fR is treated\nas a pointer to an integer. \\fISrc\\fR is stored at \\fI*dst\\fR.\nThe matching argument is discarded.\n.IP \\fBTK_ARGV_INT\\fR\nThe following argument must contain an\ninteger string in the format accepted by \\fBstrtol\\fR (e.g.\n.QW 0\nand\n.QW 0x\nprefixes may be used to specify octal or hexadecimal\nnumbers, respectively). \\fIDst\\fR is treated as a pointer to an\ninteger; the following argument is converted to an integer value\nand stored at \\fI*dst\\fR. \\fISrc\\fR is ignored. The matching\nand following arguments are discarded from \\fIargv\\fR.\n.IP \\fBTK_ARGV_FLOAT\\fR\nThe following argument must contain a floating-point number in\nthe format accepted by \\fBstrtol\\fR.\n\\fIDst\\fR is treated as the address of a double-precision\nfloating point value; the following argument is converted to a\ndouble-precision value and stored at \\fI*dst\\fR. The matching\nand following arguments are discarded from \\fIargv\\fR.\n.IP \\fBTK_ARGV_STRING\\fR\nIn this form, \\fIdst\\fR is treated as a pointer to a (char *);\n\\fBTk_ParseArgv\\fR stores at \\fI*dst\\fR a pointer to the following\nargument, and discards the matching and following arguments from\n\\fIargv\\fR. \\fISrc\\fR is ignored.\n.IP \\fBTK_ARGV_UID\\fR\nThis form is similar to \\fBTK_ARGV_STRING\\fR, except that the argument\nis turned into a Tk_Uid by calling \\fBTk_GetUid\\fR.\n\\fIDst\\fR is treated as a pointer to a\nTk_Uid; \\fBTk_ParseArgv\\fR stores at \\fI*dst\\fR the Tk_Uid\ncorresponding to the following\nargument, and discards the matching and following arguments from\n\\fIargv\\fR. \\fISrc\\fR is ignored.\n.IP \\fBTK_ARGV_CONST_OPTION\\fR\nThis form causes a Tk option to be set (as if the \\fBoption\\fR\ncommand had been invoked). The \\fIsrc\\fR field is treated as a\npointer to a string giving the value of an option, and \\fIdst\\fR\nis treated as a pointer to the name of the option. The matching\nargument is discarded. If \\fItkwin\\fR is NULL, then argument\nspecifiers of this type are ignored (as if they did not exist).\n.IP \\fBTK_ARGV_OPTION_VALUE\\fR\nThis form is similar to \\fBTK_ARGV_CONST_OPTION\\fR, except that the\nvalue of the option is taken from the following argument instead\nof from \\fIsrc\\fR. \\fIDst\\fR is used as the name of the option.\n\\fISrc\\fR is ignored. The matching and following arguments\nare discarded. If \\fItkwin\\fR is NULL, then argument\nspecifiers of this type are ignored (as if they did not exist).\n.IP \\fBTK_ARGV_OPTION_NAME_VALUE\\fR\nIn this case the following argument is taken as the name of a Tk\noption and the argument after that is taken as the value for that\noption. Both \\fIsrc\\fR and \\fIdst\\fR are ignored. All three\narguments are discarded from \\fIargv\\fR. If \\fItkwin\\fR is NULL,\nthen argument\nspecifiers of this type are ignored (as if they did not exist).\n.IP \\fBTK_ARGV_HELP\\fR\nWhen this kind of option is encountered, \\fBTk_ParseArgv\\fR uses the\n\\fIhelp\\fR fields of \\fIargTable\\fR to format a message describing\nall the valid arguments. The message is placed in interpreter\n\\fIinterp\\fR's result\nand \\fBTk_ParseArgv\\fR returns \\fBTCL_ERROR\\fR. When this happens, the\ncaller normally prints the help message and aborts. If the \\fIkey\\fR\nfield of a \\fBTK_ARGV_HELP\\fR specifier is NULL, then the specifier will\nnever match any arguments; in this case the specifier simply provides\nextra documentation, which will be included when some other\n\\fBTK_ARGV_HELP\\fR entry causes help information to be returned.\n.IP \\fBTK_ARGV_REST\\fR\nThis option is used by programs or commands that allow the last\nseveral of their options to be the name and/or options for some\nother program. If a \\fBTK_ARGV_REST\\fR argument is found, then\n\\fBTk_ParseArgv\\fR does not process any\nof the remaining arguments; it returns them all at\nthe beginning of \\fIargv\\fR (along with any other unprocessed arguments).\nIn addition, \\fBTk_ParseArgv\\fR treats \\fIdst\\fR as the address of an\ninteger value, and stores at \\fI*dst\\fR the index of the first of the\n\\fBTK_ARGV_REST\\fR options in the returned \\fIargv\\fR. This allows the\nprogram to distinguish the \\fBTK_ARGV_REST\\fR options from other\nunprocessed options that preceded the \\fBTK_ARGV_REST\\fR.\n.IP \\fBTK_ARGV_FUNC\\fR\nFor this kind of argument, \\fIsrc\\fR is treated as the address of\na procedure, which is invoked to process the following argument.\nThe procedure should have the following structure:\n.RS\n.CS\nint\n\\fIfunc\\fR(\\fIdst\\fR, \\fIkey\\fR, \\fInextArg\\fR)\n char *\\fIdst\\fR;\n char *\\fIkey\\fR;\n char *\\fInextArg\\fR;\n{\n}\n.CE\nThe \\fIdst\\fR and \\fIkey\\fR parameters will contain the\ncorresponding fields from the \\fIargTable\\fR entry, and\n\\fInextArg\\fR will point to the following argument from \\fIargv\\fR\n(or NULL if there are not any more arguments left in \\fIargv\\fR).\nIf \\fIfunc\\fR uses \\fInextArg\\fR (so that\n\\fBTk_ParseArgv\\fR should discard it), then it should return 1. Otherwise it\nshould return 0 and \\fBTkParseArgv\\fR will process the following\nargument in the normal fashion. In either event the matching argument\nis discarded.\n.RE\n.IP \\fBTK_ARGV_GENFUNC\\fR\nThis form provides a more general procedural escape. It treats\n\\fIsrc\\fR as the address of a procedure, and passes that procedure\nall of the remaining arguments. The procedure should have the following\nform:\n.RS\n.CS\nint\n\\fIgenfunc\\fR(dst, interp, key, argc, argv)\n char *\\fIdst\\fR;\n Tcl_Interp *\\fIinterp\\fR;\n char *\\fIkey\\fR;\n int \\fIargc\\fR;\n char **\\fIargv\\fR;\n{\n}\n.CE\nThe \\fIdst\\fR and \\fIkey\\fR parameters will contain the\ncorresponding fields from the \\fIargTable\\fR entry. \\fIInterp\\fR\nwill be the same as the \\fIinterp\\fR argument to \\fBTcl_ParseArgv\\fR.\n\\fIArgc\\fR and \\fIargv\\fR refer to all of the options after the\nmatching one. \\fIGenfunc\\fR should behave in a fashion similar\nto \\fBTk_ParseArgv\\fR: parse as many of the remaining arguments as it can,\nthen return any that are left by compacting them to the beginning of\n\\fIargv\\fR (starting at \\fIargv\\fR[0]). \\fIGenfunc\\fR\nshould return a count of how many arguments are left in \\fIargv\\fR;\n\\fBTk_ParseArgv\\fR will process them. If \\fIgenfunc\\fR encounters\nan error then it should leave an error message in interpreter\n\\fIinterp\\fR's result,\nin the usual Tcl fashion, and return \\-1; when this happens\n\\fBTk_ParseArgv\\fR will abort its processing and return \\fBTCL_ERROR\\fR.\n.RE\n.SS \"FLAGS\"\n.IP \\fBTK_ARGV_DONT_SKIP_FIRST_ARG\\fR\n\\fBTk_ParseArgv\\fR normally treats \\fIargv[0]\\fR as a program\nor command name, and returns it to the caller just as if it\nhad not matched \\fIargTable\\fR. If this flag is given, then\n\\fIargv[0]\\fR is not given special treatment.\n.IP \\fBTK_ARGV_NO_ABBREV\\fR\nNormally, \\fBTk_ParseArgv\\fR accepts unique abbreviations for\n\\fIkey\\fR values in \\fIargTable\\fR. If this flag is given then\nonly exact matches will be acceptable.\n.IP \\fBTK_ARGV_NO_LEFTOVERS\\fR\nNormally, \\fBTk_ParseArgv\\fR returns unrecognized arguments to the\ncaller. If this bit is set in \\fIflags\\fR then \\fBTk_ParseArgv\\fR\nwill return an error if it encounters any argument that does not\nmatch \\fIargTable\\fR. The only exception to this rule is \\fIargv[0]\\fR,\nwhich will be returned to the caller with no errors as\nlong as \\fBTK_ARGV_DONT_SKIP_FIRST_ARG\\fR is not specified.\n.IP \\fBTK_ARGV_NO_DEFAULTS\\fR\nNormally, \\fBTk_ParseArgv\\fR searches an internal table of\nstandard argument specifiers in addition to \\fIargTable\\fR. If\nthis bit is set in \\fIflags\\fR, then \\fBTk_ParseArgv\\fR will\nuse only \\fIargTable\\fR and not its default table.\n.SH EXAMPLE\n.PP\nHere is an example definition of an \\fIargTable\\fR and\nsome sample command lines that use the options. Note the effect\non \\fIargc\\fR and \\fIargv\\fR; arguments processed by \\fBTk_ParseArgv\\fR\nare eliminated from \\fIargv\\fR, and \\fIargc\\fR\nis updated to reflect reduced number of arguments.\n.CS\n/*\n * Define and set default values for globals.\n */\nint debugFlag = 0;\nint numReps = 100;\nconst char defaultFileName[] = \"out\";\nconst char *fileName = defaultFileName;\nBoolean exec = FALSE;\n\n/*\n * Define option descriptions.\n */\nstatic Tk_ArgvInfo argTable[] = {\n {\"-X\", TK_ARGV_CONSTANT, (char *) 1, &debugFlag,\n \"Turn on debugging printfs\"},\n {\"-N\", TK_ARGV_INT, NULL, &numReps,\n \"Number of repetitions\"},\n {\"-of\", TK_ARGV_STRING, NULL, &fileName,\n \"Name of file for output\"},\n {\"x\", TK_ARGV_REST, NULL, &exec,\n \"File to exec, followed by any arguments (must be last argument).\"},\n {NULL, TK_ARGV_END, NULL, NULL,\n NULL}\n};\n\nint main(int argc, char *argv[])\n{\n \\&...\n\n if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {\n fprintf(stderr, \"%s\\en\", Tcl_GetString(Tcl_GetObjResult(interp)));\n exit(1);\n }\n\n /*\n * Remainder of the program.\n */\n}\n.CE\n.PP\nNote that default values can be assigned to variables named in\n\\fIargTable\\fR: the variables will only be overwritten if the\nparticular arguments are present in \\fIargv\\fR.\nHere are some example command lines and their effects.\n.CS\nprog -N 200 infile # just sets the numReps variable to 200\nprog -of out200 infile # sets fileName to reference \"out200\"\nprog -XN 10 infile # sets the debug flag, also sets numReps\n.CE\nIn all of the above examples, \\fIargc\\fR will be set by \\fBTk_ParseArgv\\fR to 2,\n\\fIargv\\fR[0] will be\n.QW prog ,\n\\fIargv\\fR[1] will be\n.QW infile ,\nand \\fIargv\\fR[2] will be NULL.\n.SH KEYWORDS\narguments, command line, options\n" }, { "path": "doc/QWinEvent.3", "content": "'\\\"\n'\\\" Copyright (c) 1995-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_QueueWindowEvent 3 7.5 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CollapseMotionEvents, Tk_QueueWindowEvent \\- Add a window event to the Tcl event queue\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_CollapseMotionEvents\\fR(\\fIdisplay, collapse\\fR)\n.sp\n\\fBTk_QueueWindowEvent\\fR(\\fIeventPtr, position\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tcl_QueuePosition position\n.AP Display *display in\nDisplay for which to control motion event collapsing.\n.AP int collapse in\nIndicates whether motion events should be collapsed or not.\n.AP XEvent *eventPtr in\nAn event to add to the event queue. It is important\nthat all unused fields of the structure be set to zero.\n.AP Tcl_QueuePosition position in\nWhere to add the new event in the queue: \\fBTCL_QUEUE_TAIL\\fR,\n\\fBTCL_QUEUE_HEAD\\fR, or \\fBTCL_QUEUE_MARK\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_QueueWindowEvent\\fR places a window event on Tcl's internal event\nqueue for eventual servicing. It creates a Tcl_Event structure, copies the\nevent into that structure, and calls \\fBTcl_QueueEvent\\fR to add the event\nto the queue. When the event is eventually removed from the queue it is\nprocessed just like all window events.\n.PP\nWhen multiple motion events are received for the same window in rapid\nsuccession, they are collapsed by default. This behavior can be controlled\nwith \\fBTk_CollapseMotionEvents\\fR. \\fBTk_CollapseMotionEvents\\fR always\nreturns the previous value for collapse behavior on the \\fIdisplay\\fR.\n.PP\nThe \\fIposition\\fR argument to \\fBTk_QueueWindowEvent\\fR has\nthe same significance as for \\fBTcl_QueueEvent\\fR; see the\ndocumentation for \\fBTcl_QueueEvent\\fR for details.\n.SH KEYWORDS\ncallback, clock, handler, modal timeout, events\n" }, { "path": "doc/Restack.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_RestackWindow 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_RestackWindow \\- Change a window's position in the stacking order\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_RestackWindow\\fR(\\fItkwin, aboveBelow, other\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window aboveBelow\n.AP Tk_Window tkwin in\nToken for window to restack.\n.AP int aboveBelow in\nIndicates new position of \\fItkwin\\fR relative to \\fIother\\fR;\nmust be \\fBAbove\\fR or \\fBBelow\\fR.\n.AP Tk_Window other in\n\\fITkwin\\fR will be repositioned just above or below this window.\nMust be a sibling of \\fItkwin\\fR or a descendant of a sibling.\nIf NULL then \\fItkwin\\fR is restacked above or below all siblings.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_RestackWindow\\fR changes the stacking order of \\fIwindow\\fR relative\nto its siblings.\nIf \\fIother\\fR is specified as NULL then \\fIwindow\\fR is repositioned\nat the top or bottom of its stacking order, depending on whether\n\\fIaboveBelow\\fR is \\fBAbove\\fR or \\fBBelow\\fR.\nIf \\fIother\\fR has a non-NULL value then \\fIwindow\\fR is repositioned\njust above or below \\fIother\\fR.\n.PP\nThe \\fIaboveBelow\\fR argument must have one of the symbolic values\n\\fBAbove\\fR or \\fBBelow\\fR.\nBoth of these values are defined by the include file .\n.SH KEYWORDS\nabove, below, obscure, stacking order\n" }, { "path": "doc/RestrictEv.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_RestrictEvents 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_RestrictEvents \\- filter and selectively delay X events\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_RestrictProc *\n\\fBTk_RestrictEvents\\fR(\\fIproc, arg, prevArgPtr\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_RestrictProc **prevArgPtr\n.AP Tk_RestrictProc *proc in\nPredicate procedure to call to filter incoming X events.\nNULL means do not restrict events at all.\n.AP void *arg in\nArbitrary argument to pass to \\fIproc\\fR.\n.AP void **prevArgPtr out\nPointer to place to save argument to previous restrict procedure.\n.BE\n.SH DESCRIPTION\n.PP\nThis procedure is useful in certain situations where applications\nare only prepared to receive certain X events. After\n\\fBTk_RestrictEvents\\fR is called, \\fBTcl_DoOneEvent\\fR (and\nhence \\fBTk_MainLoop\\fR) will filter X input events through\n\\fIproc\\fR. \\fIProc\\fR indicates whether a\ngiven event is to be processed immediately, deferred until some\nlater time (e.g. when the event restriction is lifted), or discarded.\n\\fIProc\\fR\nis a procedure with arguments and result that match\nthe type \\fBTk_RestrictProc\\fR:\n.CS\ntypedef Tk_RestrictAction \\fBTk_RestrictProc\\fR(\n void *\\fIarg\\fR,\n XEvent *\\fIeventPtr\\fR);\n.CE\nThe \\fIarg\\fR argument is a copy of the \\fIarg\\fR passed\nto \\fBTk_RestrictEvents\\fR; it may be used to provide \\fIproc\\fR with\ninformation it needs to filter events. The \\fIeventPtr\\fR points to\nan event under consideration. \\fIProc\\fR returns a restrict action\n(enumerated type \\fBTk_RestrictAction\\fR) that indicates what\n\\fBTcl_DoOneEvent\\fR should do with the event. If the return value is\n\\fBTK_PROCESS_EVENT\\fR, then the event will be handled immediately.\nIf the return value is \\fBTK_DEFER_EVENT\\fR, then the event will be\nleft on the event queue for later processing. If the return value is\n\\fBTK_DISCARD_EVENT\\fR, then the event will be removed from the event\nqueue and discarded without being processed.\n.PP\n\\fBTk_RestrictEvents\\fR uses its return value and \\fIprevArgPtr\\fR\nto return information about the current event restriction procedure\n(a NULL return value means there are currently no restrictions).\nThese values may be used to restore the previous restriction state\nwhen there is no longer any need for the current restriction.\n.PP\nThere are very few places where \\fBTk_RestrictEvents\\fR is needed.\nIn most cases, the best way to restrict events is by changing the\nbindings with the \\fBbind\\fR Tcl command or by calling\n\\fBTk_CreateEventHandler\\fR and \\fBTk_DeleteEventHandler\\fR from C.\nThe main place where \\fBTk_RestrictEvents\\fR must be used is when\nperforming synchronous actions (for example, if you need to wait\nfor a particular event to occur on a particular window but you do not\nwant to invoke any handlers for any other events). The\n.QW obvious\nsolution in these situations is to call \\fBXNextEvent\\fR or\n\\fBXWindowEvent\\fR, but these procedures cannot be used because\nTk keeps its own event queue that is separate from the X event\nqueue. Instead, call \\fBTk_RestrictEvents\\fR to set up a filter,\nthen call \\fBTcl_DoOneEvent\\fR to retrieve the desired event(s).\n.SH KEYWORDS\ndelay, event, filter, restriction\n" }, { "path": "doc/SetAppName.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1997 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_SetAppName 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_SetAppName \\- Set the name of an application for 'send' commands\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nconst char *\n\\fBTk_SetAppName\\fR(\\fItkwin, name\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window parent\n.AP Tk_Window tkwin in\nToken for window in application. Used only to select a particular\napplication.\n.AP \"const char\" *name in\nName under which to register the application.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_SetAppName\\fR associates a name with a given application and\nrecords that association on the display containing with the application's\nmain window.\nAfter this procedure has been invoked, other applications on the\ndisplay will be able to use the \\fBsend\\fR command to invoke operations\nin the application.\nIf \\fIname\\fR is already in use by some other application on the\ndisplay, then a new name will be generated by appending\n.QW \"\\fB #2\\fR\"\nto \\fIname\\fR; if this name is also in use,\nthe number will be incremented until an unused name is found.\nThe return value from the procedure is a pointer to the name actually\nused.\n.PP\nIf the application already has a name when \\fBTk_SetAppName\\fR is\ncalled, then the new name replaces the old name.\n.PP\n\\fBTk_SetAppName\\fR also adds a \\fBsend\\fR command to the application's\ninterpreter, which can be used to send commands from this application\nto others on any of the displays where the application has windows.\n.PP\nThe application's name registration persists until the interpreter is\ndeleted or the \\fBsend\\fR command is deleted from \\fIinterp\\fR, at which\npoint the name is automatically unregistered and the application\nbecomes inaccessible via \\fBsend\\fR.\nThe application can be made accessible again by calling \\fBTk_SetAppName\\fR.\n.PP\n\\fBTk_SetAppName\\fR is called automatically by \\fBTk_Init\\fR,\nso applications do not normally need to call it explicitly.\n.PP\nThe command \\fBtk appname\\fR provides Tcl-level access to the\nfunctionality of \\fBTk_SetAppName\\fR.\n.SH KEYWORDS\napplication, name, register, send command\n" }, { "path": "doc/SetCaret.3", "content": "'\\\"\n'\\\" Copyright (c) 2002 ActiveState Corporation.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_SetCaretPos 3 8.4 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_SetCaretPos \\- set the display caret location\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_SetCaretPos\\fR(\\fItkwin, x, y, height\\fR)\n.fi\n.SH ARGUMENTS\n.AP Tk_Window tkwin in\nToken for window.\n.AP int x in\nWindow-relative x coordinate.\n.AP int y in\nWindow-relative y coordinate.\n.AP int h in\nHeight of the caret in the window.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_SetCaretPos\\fR sets the caret location for the display of the\nspecified Tk_Window \\fItkwin\\fR. The caret is the per-display cursor\nlocation used for indicating global focus (e.g. to comply with Microsoft\nAccessibility guidelines), as well as for location of the over-the-spot XIM\n(X Input Methods) or Windows IME windows.\n.SH KEYWORDS\ncaret, cursor\n" }, { "path": "doc/SetClass.3", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_SetClass 3 \"\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_SetClass, Tk_Class \\- set or retrieve a window's class\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_SetClass\\fR(\\fItkwin, class\\fR)\n.sp\nTk_Uid\n\\fBTk_Class\\fR(\\fItkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window parent\n.AP Tk_Window tkwin in\nToken for window.\n.AP char *class in\nNew class name for window.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_SetClass\\fR is called to associate a class with a particular\nwindow. The \\fIclass\\fR string identifies the type of the\nwindow; all windows with the same general class of behavior\n(button, menu, etc.) should have the same class. By\nconvention all class names start with a capital letter, and\nthere exists a Tcl command with the same name as\neach class (except all in lower-case) which can be used to\ncreate and manipulate windows of that class.\nA window's class string is initialized to NULL\nwhen the window is created.\n.PP\nFor main windows, Tk automatically propagates the name and class\nto the WM_CLASS property used by window managers. This happens\neither when a main window is actually created (e.g. in\n\\fBTk_MakeWindowExist\\fR), or when \\fBTk_SetClass\\fR\nis called, whichever occurs later. If a main window has not been\nassigned a class then Tk will not set the WM_CLASS property for\nthe window.\n.PP\n\\fBTk_Class\\fR is a macro that returns the\ncurrent value of \\fItkwin\\fR's class. The value is returned\nas a Tk_Uid, which may be used just like a string pointer but also has\nthe properties of a unique identifier (see the manual entry for\n\\fBTk_GetUid\\fR for details).\nIf \\fItkwin\\fR has not yet been given a class, then\n\\fBTk_Class\\fR will return NULL.\n.SH KEYWORDS\nclass, unique identifier, window, window manager\n" }, { "path": "doc/SetClassProcs.3", "content": "'\\\"\n'\\\" Copyright (c) 2000 Ajuba Solutions.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_SetClassProcs 3 8.4 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_SetClassProcs \\- register widget specific procedures\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_SetClassProcs\\fR(\\fItkwin, procs, instanceData\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_ClassProc instanceData\n.AP Tk_Window tkwin in\nToken for window to modify.\n.AP \"const Tk_ClassProcs\" *procs in\nPointer to data structure containing widget specific procedures.\nThe data structure pointed to by \\fIprocs\\fR must be static:\nTk keeps a reference to it as long as the window exists.\n.AP void *instanceData in\nArbitrary one-word value to pass to widget callbacks.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_SetClassProcs\\fR is called to register a set of procedures that\nare used as callbacks in different places.\n.PP\nThe structure pointed to by \\fIprocs\\fR contains the following:\n.CS\ntypedef struct {\n Tcl_Size \\fIsize\\fR;\n Tk_ClassWorldChangedProc *\\fIworldChangedProc\\fR;\n Tk_ClassCreateProc *\\fIcreateProc\\fR;\n Tk_ClassModalProc *\\fImodalProc\\fR;\n} \\fBTk_ClassProcs\\fR;\n.CE\nThe \\fIsize\\fR field is used to simplify future expansion of the\nstructure. It should always be set to (literally) \\fBsizeof(Tk_ClassProcs)\\fR.\n.PP\n\\fIworldChangedProc\\fR is invoked when the system has altered\nin some way that requires some reaction from the widget. For example,\nwhen a font alias (see the \\fBfont\\fR manual entry) is reconfigured,\nwidgets configured to use that font alias must update their display\naccordingly. \\fIworldChangedProc\\fR should have arguments and results\nthat match the type \\fBTk_ClassWorldChangedProc\\fR:\n.CS\ntypedef void \\fBTk_ClassWorldChangedProc\\fR(\n void *\\fIinstanceData\\fR);\n.CE\nThe \\fIinstanceData\\fR parameter passed to the \\fIworldChangedProc\\fR\nwill be identical to the \\fIinstanceData\\fR parameter passed to\n\\fBTk_SetClassProcs\\fR.\n.PP\n\\fIcreateProc\\fR is used to create platform-dependent windows. It is\ninvoked by \\fBTk_MakeWindowExist\\fR. \\fIcreateProc\\fR should have\narguments and results that match the type \\fBTk_ClassCreateProc\\fR:\n.CS\ntypedef Window \\fBTk_ClassCreateProc\\fR(\n Tk_Window \\fItkwin\\fR,\n Window \\fIparent\\fR,\n void *\\fIinstanceData\\fR);\n.CE\nThe \\fItkwin\\fR and \\fIinstanceData\\fR parameters will be identical to\nthe \\fItkwin\\fR and \\fIinstanceData\\fR parameters passed to\n\\fBTk_SetClassProcs\\fR. The \\fIparent\\fR parameter will be the parent\nof the window to be created. The \\fIcreateProc\\fR should return the\ncreated window.\n.PP\n\\fImodalProc\\fR is invoked after all bindings on a widget have been\ntriggered in order to handle a modal loop. \\fImodalProc\\fR should\nhave arguments and results that match the type \\fBTk_ClassModalProc\\fR:\n.CS\ntypedef void \\fBTk_ClassModalProc\\fR(\n Tk_Window \\fItkwin\\fR,\n XEvent *\\fIeventPtr\\fR);\n.CE\nThe \\fItkwin\\fR parameter to \\fImodalProc\\fR will be identical to the\n\\fItkwin\\fR parameter passed to \\fBTk_SetClassProcs\\fR. The\n\\fIeventPtr\\fR parameter will be a pointer to an XEvent structure\ndescribing the event being processed.\n.SH KEYWORDS\ncallback, class\n" }, { "path": "doc/SetGrid.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_SetGrid 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_SetGrid, Tk_UnsetGrid \\- control the grid for interactive resizing\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_SetGrid\\fR(\\fItkwin, reqWidth, reqHeight, widthInc, heightInc\\fR)\n.sp\n\\fBTk_UnsetGrid\\fR(\\fItkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window heightInc\n.AP Tk_Window tkwin in\nToken for window.\n.AP int reqWidth in\nWidth in grid units that corresponds to the pixel dimension \\fItkwin\\fR\nhas requested via \\fBTk_GeometryRequest\\fR.\n.AP int reqHeight in\nHeight in grid units that corresponds to the pixel dimension \\fItkwin\\fR\nhas requested via \\fBTk_GeometryRequest\\fR.\n.AP int widthInc in\nWidth of one grid unit, in pixels.\n.AP int heightInc in\nHeight of one grid unit, in pixels.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_SetGrid\\fR turns on gridded geometry management for \\fItkwin\\fR's\ntoplevel window and specifies the geometry of the grid.\n\\fBTk_SetGrid\\fR is typically invoked by a widget when its \\fBsetGrid\\fR\noption is true.\nIt restricts interactive resizing of \\fItkwin\\fR's toplevel window so\nthat the space allocated to the toplevel is equal to its requested\nsize plus or minus even multiples of \\fIwidthInc\\fR and \\fIheightInc\\fR.\nFurthermore, the \\fIreqWidth\\fR and \\fIreqHeight\\fR values are\npassed to the window manager so that it can report the window's\nsize in grid units during interactive resizes.\nIf \\fItkwin\\fR's configuration changes (e.g., the size of a grid unit\nchanges) then the widget should invoke \\fBTk_SetGrid\\fR again with the new\ninformation.\n.PP\n\\fBTk_UnsetGrid\\fR cancels gridded geometry management for\n\\fItkwin\\fR's toplevel window.\n.PP\nFor each toplevel window there can be at most one internal window\nwith gridding enabled.\nIf \\fBTk_SetGrid\\fR or \\fBTk_UnsetGrid\\fR is invoked when some\nother window is already controlling gridding for \\fItkwin\\fR's\ntoplevel, the calls for the new window have no effect.\n.PP\nSee the \\fBwm\\fR manual entry for additional information on gridded geometry\nmanagement.\n.SH KEYWORDS\ngrid, window, window manager\n" }, { "path": "doc/SetOptions.3", "content": "'\\\"\n'\\\" Copyright (c) 1998 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_SetOptions 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions \\- process configuration options\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_OptionTable\n\\fBTk_CreateOptionTable\\fR(\\fIinterp, templatePtr\\fR)\n.sp\n\\fBTk_DeleteOptionTable\\fR(\\fIoptionTable\\fR)\n.sp\nint\n\\fBTk_InitOptions\\fR(\\fIinterp, recordPtr, optionTable, tkwin\\fR)\n.sp\nint\n\\fBTk_SetOptions\\fR(\\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\\fR)\n.sp\n\\fBTk_FreeSavedOptions\\fR(\\fIsavedPtr\\fR)\n.sp\n\\fBTk_RestoreSavedOptions\\fR(\\fIsavedPtr\\fR)\n.sp\nTcl_Obj *\n\\fBTk_GetOptionValue\\fR(\\fIinterp, recordPtr, optionTable, namePtr, tkwin\\fR)\n.sp\nTcl_Obj *\n\\fBTk_GetOptionInfo\\fR(\\fIinterp, recordPtr, optionTable, namePtr, tkwin\\fR)\n.sp\n\\fBTk_FreeConfigOptions\\fR(\\fIrecordPtr, optionTable, tkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_SavedOptions \"*const *objv\" in/out\n.AP Tcl_Interp *interp in\nA Tcl interpreter. Most procedures use this only for returning error\nmessages; if it is NULL then no error messages are returned. For\n\\fBTk_CreateOptionTable\\fR the value cannot be NULL; it gives the\ninterpreter in which the option table will be used.\n.AP \"const Tk_OptionSpec\" *templatePtr in\nPoints to an array of static information that describes the configuration\noptions that are supported. Used to build a Tk_OptionTable. The information\npointed to by this argument must exist for the lifetime of the Tk_OptionTable.\n.AP Tk_OptionTable optionTable in\nToken for an option table. Must have been returned by a previous call\nto \\fBTk_CreateOptionTable\\fR.\n.AP void *recordPtr in/out\nPoints to structure in which values of configuration options are stored;\nfields of this record are modified by procedures such as \\fBTk_SetOptions\\fR\nand read by procedures such as \\fBTk_GetOptionValue\\fR.\n.AP Tk_Window tkwin in\nFor options such as \\fBTK_OPTION_COLOR\\fR, this argument indicates\nthe window in which the option will be used. If \\fIoptionTable\\fR uses\nno window-dependent options, then a NULL value may be supplied for\nthis argument.\n.AP Tcl_Size objc in\nNumber of values in \\fIobjv\\fR.\n.AP Tcl_Obj \"*const *objv\" in\nCommand-line arguments for setting configuring options.\n.AP Tk_SavedOptions *savePtr out\nIf not NULL, the structure pointed to by this argument is filled\nin with the old values of any options that were modified and old\nvalues are restored automatically if an error occurs in \\fBTk_SetOptions\\fR.\n.AP int *maskPtr out\nIf not NULL, the word pointed to by \\fImaskPtr\\fR is filled in with the\nbit-wise OR of the \\fItypeMask\\fR fields for the options that\nwere modified.\n.AP Tk_SavedOptions *savedPtr in/out\nPoints to a structure previously filled in by \\fBTk_SetOptions\\fR with\nold values of modified options.\n.AP Tcl_Obj *namePtr in\nThe value of this object is the name of a particular option. If NULL\nis passed to \\fBTk_GetOptionInfo\\fR then information is returned for\nall options. Must not be NULL when \\fBTk_GetOptionValue\\fR is called.\n.AP \"type name\" type in\nThe name of the type of a record.\n.AP \"field name\" field in\nThe name of a field in records of type \\fItype\\fR.\n.BE\n.SH DESCRIPTION\n.PP\nThese procedures handle most of the details of parsing configuration\noptions such as those for Tk widgets. Given a description of what\noptions are supported, these procedures handle all the details of\nparsing options and storing their values into a C structure associated\nwith the widget or object. The procedures were designed primarily for\nwidgets in Tk, but they can also be used for other kinds of objects that\nhave configuration options. In the rest of this manual page\n.QW widget\nwill be used to refer to the object whose options are being managed; in\npractice the object may not actually be a widget. The term\n.QW \"widget record\"\nis used to refer to the C-level structure in\nwhich information about a particular widget or object is stored.\n.PP\nNote that the easiest way to learn how to use these procedures is to\nlook at a working example. In Tk, the simplest example is the code\nthat implements the button family of widgets, which is in \\fBtkButton.c\\fR.\nOther examples are in \\fBtkSquare.c\\fR and \\fBtkMenu.c\\fR.\n.PP\nIn order to use these procedures, the code that implements the widget\nmust contain a static array of Tk_OptionSpec structures. This is a\ntemplate that describes the various options supported by that class of\nwidget; there is a separate template for each kind of widget. The\ntemplate contains information such as the name of each option, its type,\nits default value, and where the value of the option is stored in the\nwidget record. See TEMPLATES below for more detail.\n.PP\nIn order to process configuration options efficiently, the static\ntemplate must be augmented with additional information that is available\nonly at runtime. The procedure \\fBTk_CreateOptionTable\\fR creates this\ndynamic information from the template and returns a Tk_OptionTable token\nthat describes both the static and dynamic information. All of the\nother procedures, such as \\fBTk_SetOptions\\fR, take a Tk_OptionTable\ntoken as argument. Typically, \\fBTk_CreateOptionTable\\fR is called the\nfirst time that a widget of a particular class is created and the\nresulting Tk_OptionTable is used in the future for all widgets of that\nclass. A Tk_OptionTable may be used only in a single interpreter, given\nby the \\fIinterp\\fR argument to \\fBTk_CreateOptionTable\\fR. When an\noption table is no longer needed \\fBTk_DeleteOptionTable\\fR should be\ncalled to free all of its resources. All of the option tables\nfor a Tcl interpreter are freed automatically if the interpreter is deleted.\n.PP\n\\fBTk_InitOptions\\fR is invoked when a new widget is created to set the\ndefault values.\n\\fBTk_InitOptions\\fR is passed a token for an option table\n(\\fIoptionTable\\fR) and a pointer to a widget record (\\fIrecordPtr\\fR),\nwhich is the C structure that holds information about this widget.\n\\fBTk_InitOptions\\fR uses the information in the option table to choose an\nappropriate default for each option, then it stores the default value\ndirectly into the widget record, overwriting any information that was\nalready present in the widget record. \\fBTk_InitOptions\\fR normally\nreturns \\fBTCL_OK\\fR. If an error occurred while setting the default\nvalues (e.g., because a default value was erroneous) then \\fBTCL_ERROR\\fR\nis returned and an error message is left in \\fIinterp\\fR's result if\n\\fIinterp\\fR is not NULL. For any widget's configuration option that\nhas \\fBTK_OPTION_DONT_SET_DEFAULT\\fR set in its \\fIflags\\fR field,\nthe above initialization is fully skipped, see below.\n.PP\n\\fBTk_SetOptions\\fR is invoked to modify configuration options based\non information specified in a Tcl command. The command might be one that\ncreates a new widget, or a command that modifies options on an existing\nwidget. The \\fIobjc\\fR and \\fIobjv\\fR arguments describe the\nvalues of the arguments from the Tcl command. \\fIObjv\\fR must contain\nan even number of objects: the first object of each pair gives the name of\nan option and the second object gives the new value for that option.\n\\fBTk_SetOptions\\fR looks up each name in \\fIoptionTable\\fR, checks that\nthe new value of the option conforms to the type in \\fIoptionTable\\fR,\nand stores the value of the option into the widget record given by\n\\fIrecordPtr\\fR. \\fBTk_SetOptions\\fR normally returns \\fBTCL_OK\\fR. If\nan error occurred (such as an unknown option name or an illegal option\nvalue) then \\fBTCL_ERROR\\fR is returned and an error message is left in\n\\fIinterp\\fR's result if \\fIinterp\\fR is not NULL.\n.PP\n\\fBTk_SetOptions\\fR has two additional features. First, if the\n\\fImaskPtr\\fR argument is not NULL then it points to an integer\nvalue that is filled in with information about the options that were\nmodified. For each option in the template passed to\n\\fBTk_CreateOptionTable\\fR there is a \\fItypeMask\\fR field. The\nbits of this field are defined by the code that implements the widget;\nfor example, each bit might correspond to a particular configuration option.\nAlternatively, bits might be used functionally. For example, one bit might\nbe used for redisplay: all options that affect the widget's display, such\nthat changing the option requires the widget to be redisplayed, might have\nthat bit set. Another bit might indicate that the geometry of the widget\nmust be recomputed, and so on. \\fBTk_SetOptions\\fR OR's together the\n\\fItypeMask\\fR fields from all the options that were modified and returns\nthis value at *\\fImaskPtr\\fR; the caller can then use this information\nto optimize itself so that, for example, it does not redisplay the widget\nif the modified options do not affect the widget's appearance.\n.PP\nThe second additional feature of \\fBTk_SetOptions\\fR has to do with error\nrecovery. If an error occurs while processing configuration options, this\nfeature makes it possible to restore all the configuration options to their\nprevious values. Errors can occur either while processing options in\n\\fBTk_SetOptions\\fR or later in the caller. In many cases the caller does\nadditional processing after \\fBTk_SetOptions\\fR returns; for example, it\nmight use an option value to set a trace on a variable and may detect\nan error if the variable is an array instead of a scalar. Error recovery\nis enabled by passing in a non-NULL value for the \\fIsavePtr\\fR argument\nto \\fBTk_SetOptions\\fR; this should be a pointer to an uninitialized\nTk_SavedOptions structure on the caller's stack. \\fBTk_SetOptions\\fR\noverwrites the structure pointed to by \\fIsavePtr\\fR with information\nabout the old values of any options modified by the procedure.\nIf \\fBTk_SetOptions\\fR returns successfully, the\ncaller uses the structure in one of two ways. If the caller completes\nits processing of the new options without any errors, then it must pass\nthe structure to \\fBTk_FreeSavedOptions\\fR so that the old values can be\nfreed. If the caller detects an error in its processing of the new\noptions, then it should pass the structure to \\fBTk_RestoreSavedOptions\\fR,\nwhich will copy the old values back into the widget record and free\nthe new values.\nIf \\fBTk_SetOptions\\fR detects an error then it automatically restores\nany options that had already been modified and leaves *\\fIsavePtr\\fR in\nan empty state: the caller need not call either \\fBTk_FreeSavedOptions\\fR or\n\\fBTk_RestoreSavedOptions\\fR.\nIf the \\fIsavePtr\\fR argument to \\fBTk_SetOptions\\fR is NULL then\n\\fBTk_SetOptions\\fR frees each old option value immediately when it sets a new\nvalue for the option. In this case, if an error occurs in the third\noption, the old values for the first two options cannot be restored.\n.PP\n\\fBTk_GetOptionValue\\fR returns the current value of a configuration option\nfor a particular widget. The \\fInamePtr\\fR argument contains the name of\nan option; \\fBTk_GetOptionValue\\fR uses \\fIoptionTable\\fR\nto lookup the option and extract its value from the widget record\npointed to by \\fIrecordPtr\\fR, then it returns an object containing\nthat value. If an error occurs (e.g., because \\fInamePtr\\fR contains an\nunknown option name) then NULL is returned and an error message is left\nin \\fIinterp\\fR's result unless \\fIinterp\\fR is NULL.\n.PP\n\\fBTk_GetOptionInfo\\fR returns information about configuration options in\na form suitable for \\fBconfigure\\fR widget commands. If the \\fInamePtr\\fR\nargument is not NULL, it points to an object that gives the name of a\nconfiguration option; \\fBTk_GetOptionInfo\\fR returns an object containing\na list with five elements, which are the name of the option, the name and\nclass used for the option in the option database, the default value for\nthe option, and the current value for the option. If the \\fInamePtr\\fR\nargument is NULL, then \\fBTk_GetOptionInfo\\fR returns information about\nall options in the form of a list of lists; each sublist describes one\noption. Synonym options are handled differently depending on whether\n\\fInamePtr\\fR is NULL: if \\fInamePtr\\fR is NULL then the sublist for\neach synonym option has only two elements, which are the name of the\noption and the name of the other option that it refers to; if \\fInamePtr\\fR\nis non-NULL and names a synonym option then the object returned\nis the five-element list\nfor the other option that the synonym refers to. If an error occurs\n(e.g., because \\fInamePtr\\fR contains an unknown option name) then NULL\nis returned and an error message is left in \\fIinterp\\fR's result unless\n\\fIinterp\\fR is NULL.\n.PP\n\\fBTk_FreeConfigOptions\\fR must be invoked when a widget is deleted.\nIt frees all of the resources associated with any of the configuration\noptions defined in \\fIrecordPtr\\fR by \\fIoptionTable\\fR.\n.SH \"TEMPLATES\"\n.PP\nThe array of Tk_OptionSpec structures passed to \\fBTk_CreateOptionTable\\fR\nvia its \\fItemplatePtr\\fR argument describes the configuration options\nsupported by a particular class of widgets. Each structure specifies\none configuration option and has the following fields:\n.CS\ntypedef struct {\n Tk_OptionType \\fItype\\fR;\n const char *\\fIoptionName\\fR;\n const char *\\fIdbName\\fR;\n const char *\\fIdbClass\\fR;\n const char *\\fIdefValue\\fR;\n Tcl_Size \\fIobjOffset\\fR;\n Tcl_Size \\fIinternalOffset\\fR;\n int \\fIflags\\fR;\n const void *\\fIclientData\\fR;\n int \\fItypeMask\\fR;\n} \\fBTk_OptionSpec\\fR;\n.CE\nThe \\fItype\\fR field indicates what kind of configuration option this is\n(e.g. \\fBTK_OPTION_COLOR\\fR for a color value, or \\fBTK_OPTION_INT\\fR for\nan integer value). \\fIType\\fR determines how the\nvalue of the option is parsed (more on this below).\nThe \\fIoptionName\\fR field is a string such as \\fB\\-font\\fR or \\fB\\-bg\\fR;\nit is the name used for the option in Tcl commands and passed to\nprocedures via the \\fIobjc\\fR or \\fInamePtr\\fR arguments.\nThe \\fIdbName\\fR and \\fIdbClass\\fR fields are used by \\fBTk_InitOptions\\fR\nto look up a default value for this option in the option database; if\n\\fIdbName\\fR is NULL then the option database is not used by\n\\fBTk_InitOptions\\fR for this option. The \\fIdefValue\\fR field\nspecifies a default value for this configuration option if no\nvalue is specified in the option database. The \\fIobjOffset\\fR and\n\\fIinternalOffset\\fR fields indicate where to store the value of this\noption in widget records (more on this below); values for the \\fIobjOffset\\fR\nand \\fIinternalOffset\\fR fields should always be generated with the\n\\fBoffsetof\\fR macro.\nThe \\fIflags\\fR field contains additional information\nto control the processing of this configuration option (see below\nfor details).\n\\fIClientData\\fR provides additional type-specific data needed\nby certain types. For instance, for \\fBTK_OPTION_COLOR\\fR types,\n\\fIclientData\\fR is a string giving the default value to use on\nmonochrome displays. See the descriptions of the different types\nbelow for details.\nThe last field, \\fItypeMask\\fR, is used by \\fBTk_SetOptions\\fR to\nreturn information about which options were modified; see the description\nof \\fBTk_SetOptions\\fR above for details.\n.PP\nWhen \\fBTk_InitOptions\\fR and \\fBTk_SetOptions\\fR store the value of an\noption into the widget record, they can do it in either of two ways.\nIf the \\fIobjOffset\\fR field of the Tk_OptionSpec is greater than\nor equal to zero, then the value of the option is stored as a\n(Tcl_Obj *) at the location in the widget record given by \\fIobjOffset\\fR.\nIf the \\fIinternalOffset\\fR field of the Tk_OptionSpec is\ngreater than or equal to zero, then the value of the option is stored\nin a type-specific internal form at the location in the widget record\ngiven by \\fIinternalOffset\\fR. For example, if the option's type is\n\\fBTK_OPTION_INT\\fR then the internal form is an integer. If the\n\\fIobjOffset\\fR or \\fIinternalOffset\\fR field is negative then the\nvalue is not stored in that form. At least one of the offsets must be\ngreater than or equal to zero.\n.PP\nThe \\fIflags\\fR field consists of one or more bits ORed together. The\nfollowing flags are supported:\n.IP \\fBTK_OPTION_NULL_OK\\fR\nIf this bit is set for an option then an empty string will be accepted as\nthe value for the option and the resulting internal form will be a NULL\npointer, a zero value, or \\fBNone\\fR, depending on the type of the option.\nIf the flag is not set then empty strings will result in errors.\n\\fBTK_OPTION_NULL_OK\\fR is typically used to allow a\nfeature to be turned off entirely, e.g. set a cursor value to\n\\fBNone\\fR so that a window simply inherits its parent's cursor.\nNot all option types support the \\fBTK_OPTION_NULL_OK\\fR\nflag; for those that do, there is an explicit indication of that fact\nin the descriptions below.\n.IP \\fBTK_OPTION_DONT_SET_DEFAULT\\fR\nIf this bit is set for an option then no default value will be set in\n\\fBTk_InitOptions\\fR for this option. Neither the option database, nor any\nsystem default value, nor \\fIoptionTable\\fR are used to give a default\nvalue to this option. Instead it is assumed that the caller has already\nsupplied a default value in the widget code.\n.IP \\fBTK_OPTION_ENUM_VAR\\fR\nIf this value is set for an option, then it indicates the the\ninternalOffset points to an enum variable in stead of an int variable.\nOnly useful in combination with \\fBTK_OPTION_STRING_TABLE\\fR,\n\\fBTK_OPTION_BOOLEAN\\fR, \\fBTK_OPTION_ANCHOR\\fR, \\fBTK_OPTION_JUSTIFY\\fR,\nor \\fBTK_OPTION_ANCHOR\\fR.\n.IP \\fBTK_OPTION_VAR(\\fItype\\fB)\\fR\nIf this value is set for an option, then it indicates the the\ninternalOffset points to a \\fItype\\fR variable in stead of an int variable.\nOnly useful in combination with \\fBTK_OPTION_STRING_TABLE\\fR or\n\\fBTK_OPTION_BOOLEAN\\fR, or as \\fBTK_OPTION_VAR(Tcl_Size)\\fR\nwith \\fBTK_OPTION_INT\\fR\n.RS\n.PP\nThe \\fItype\\fR field of each Tk_OptionSpec structure determines\nhow to parse the value of that configuration option. The\nlegal value for \\fItype\\fR, and the corresponding actions, are\ndescribed below. If the type requires a \\fItkwin\\fR value to be\npassed into procedures like \\fBTk_SetOptions\\fR, or if it uses\nthe \\fIclientData\\fR field of the Tk_OptionSpec, then it is indicated\nexplicitly; if not mentioned, the type requires neither \\fItkwin\\fR\nnor \\fIclientData\\fR.\n.RE\n.IP \\fBTK_OPTION_ANCHOR\\fR\nThe value must be a standard anchor position such as \\fBne\\fR or\n\\fBcenter\\fR. The internal form is a Tk_Anchor value like the ones\nreturned by \\fBTk_GetAnchorFromObj\\fR. This option type supports the\n\\fBTK_OPTION_NULL_OK\\fR flag; if the empty string is specified as the\nvalue for the option, the integer relief value is set to \\fBTK_ANCHOR_NULL\\fR.\n.IP \\fBTK_OPTION_BITMAP\\fR\nThe value must be a standard Tk bitmap name. The internal form is a\nPixmap token like the ones returned by \\fBTk_AllocBitmapFromObj\\fR.\nThis option type requires \\fItkwin\\fR to be supplied to procedures\nsuch as \\fBTk_SetOptions\\fR, and it supports the \\fBTK_OPTION_NULL_OK\\fR flag.\n.IP \\fBTK_OPTION_BOOLEAN\\fR\nThe value must be a standard boolean value such as \\fBtrue\\fR or\n\\fBno\\fR. The internal form is an integer with value 0 or 1. Note that if\nthe \\fIobjOffset\\fR field is not used, information about the original\nvalue of this option will be lost. This option type supports the\n\\fBTK_OPTION_NULL_OK\\fR flag; if a NULL value is set, the internal\nrepresentation is set to -1.\n.IP \\fBTK_OPTION_BORDER\\fR\nThe value must be a standard color name such as \\fBred\\fR or \\fB#ff8080\\fR.\nThe internal form is a Tk_3DBorder token like the ones returned\nby \\fBTk_Alloc3DBorderFromObj\\fR.\nThis option type requires \\fItkwin\\fR to be supplied to procedures\nsuch as \\fBTk_SetOptions\\fR, and it supports the \\fBTK_OPTION_NULL_OK\\fR flag.\n.IP \\fBTK_OPTION_COLOR\\fR\nThe value must be a standard color name such as \\fBred\\fR or \\fB#ff8080\\fR.\nThe internal form is an (XColor *) token like the ones returned by\n\\fBTk_AllocColorFromObj\\fR.\nThis option type requires \\fItkwin\\fR to be supplied to procedures\nsuch as \\fBTk_SetOptions\\fR, and it supports the \\fBTK_OPTION_NULL_OK\\fR flag.\n.IP \\fBTK_OPTION_CURSOR\\fR\nThe value must be a standard cursor name such as \\fBcross\\fR or \\fB@foo\\fR.\nThe internal form is a Tk_Cursor token like the ones returned by\n\\fBTk_AllocCursorFromObj\\fR.\nThis option type requires \\fItkwin\\fR to be supplied to procedures\nsuch as \\fBTk_SetOptions\\fR, and when the option is set the cursor\nfor the window is changed by calling \\fBXDefineCursor\\fR. This\noption type also supports the \\fBTK_OPTION_NULL_OK\\fR flag.\n.IP \\fBTK_OPTION_CUSTOM\\fR\nThis option allows applications to define new option types. The\nclientData field of the entry points to a structure defining the new\noption type. See the section \\fBCUSTOM OPTION TYPES\\fR below for details.\n.IP \\fBTK_OPTION_DOUBLE\\fR\nThe string value must be a floating-point number in\nthe format accepted by \\fBstrtol\\fR. The internal form is a C\n\\fBdouble\\fR value. This option type supports the \\fBTK_OPTION_NULL_OK\\fR\nflag; if a NULL value is set, the internal representation is set to NaN.\n.IP \\fBTK_OPTION_END\\fR\nMarks the end of the template. There must be a Tk_OptionSpec structure\nwith \\fItype\\fR \\fBTK_OPTION_END\\fR at the end of each template. If the\n\\fIclientData\\fR field of this structure is not NULL, then it points to\nan additional array of Tk_OptionSpec's, which is itself terminated by\nanother \\fBTK_OPTION_END\\fR entry. Templates may be chained arbitrarily\ndeeply. This feature allows common options to be shared by several\nwidget classes.\n.IP \\fBTK_OPTION_FONT\\fR\nThe value must be a standard font name such as \\fBTimes 16\\fR.\nThe internal form is a Tk_Font handle like the ones returned by\n\\fBTk_AllocFontFromObj\\fR.\nThis option type requires \\fItkwin\\fR to be supplied to procedures\nsuch as \\fBTk_SetOptions\\fR, and it supports the \\fBTK_OPTION_NULL_OK\\fR flag.\n.IP \\fBTK_OPTION_INT\\fR\nThe string value must be an integer in the format accepted by\n\\fBstrtol\\fR (e.g. \\fB0\\fR and \\fB0x\\fR prefixes may be used to\nspecify octal or hexadecimal numbers, respectively). The internal form is\na C \\fBint\\fR value. This option type supports the \\fBTK_OPTION_NULL_OK\\fR\nflag; if a NULL value is set, the internal representation is set to INT_MIN.\n.IP \\fBTK_OPTION_INDEX\\fR\nThe string value must be an index in the format accepted by\n\\fBTcl_GetIntForIndex()\\fR\nor the empty string. The internal form is a C \\fBint\\fR value. If the string\nstarts with \\fB\\-\\fR, the internal representation will be set to INT_MIN. If the\nstring has the form \\fBend-???\\fR, then the result will be a negative number:\n\\fB-1\\fR stands for \\fBend\\fR, \\fB-2\\fR stands for \\fBend-1\\fR and so on.\nThis option type supports the \\fBTK_OPTION_NULL_OK\\fR flag;\nif a NULL value is set, the internal representation is set to INT_MIN.\n.IP \\fBTK_OPTION_JUSTIFY\\fR\nThe value must be a standard justification value such as \\fBleft\\fR.\nThe internal form is a Tk_Justify like the values returned by\n\\fBTk_GetJustifyFromObj\\fR. This option type supports the\n\\fBTK_OPTION_NULL_OK\\fR\nflag; if the empty string is specified as the value for the option,\nthe integer relief value is set to \\fBTK_JUSTIFY_NULL\\fR.\n.IP \\fBTK_OPTION_PIXELS\\fR\nThe value must specify a screen distance such as \\fB2i\\fR or \\fB6.4\\fR.\nThe internal form is an integer value giving a\ndistance in pixels, like the values returned by\n\\fBTk_GetPixelsFromObj\\fR. Note that if the \\fIobjOffset\\fR field is not\nused, information about the original value of this option will be lost.\nSee \\fBOBJOFFSET VS. INTERNALOFFSET\\fR below for details. This option\ntype supports the \\fBTK_OPTION_NULL_OK\\fR flag; if a NULL value is set, the\ninternal representation is set to INT_MIN.\n.IP \\fBTK_OPTION_RELIEF\\fR\nThe value must be standard relief such as \\fBraised\\fR.\nThe internal form is an integer relief value such as\n\\fBTK_RELIEF_RAISED\\fR. This option type supports the \\fBTK_OPTION_NULL_OK\\fR\nflag; if a NULL value is set, the internal representation is set to\n\\fBTK_RELIEF_NULL\\fR.\n.IP \\fBTK_OPTION_STRING\\fR\nThe value may be any string. The internal form is a (char *) pointer\nthat points to a dynamically allocated copy of the value.\nThis option type supports the \\fBTK_OPTION_NULL_OK\\fR flag.\n.IP \\fBTK_OPTION_STRING_TABLE\\fR\nFor this type, \\fIclientData\\fR is a pointer to an array of strings\nsuitable for passing to \\fBTcl_GetIndexFromObj\\fR. The value must\nbe one of the strings in the table, or a unique abbreviation of\none of the strings. The internal form is an integer giving the index\ninto the table of the matching string, like the return value\nfrom \\fBTcl_GetStringFromObj\\fR. This option type supports the\n\\fBTK_OPTION_NULL_OK\\fR flag; if a NULL value is set, the internal\nrepresentation is set to -1.\n.IP \\fBTK_OPTION_SYNONYM\\fR\nThis type is used to provide alternative names for an option (for\nexample, \\fB\\-bg\\fR is often used as a synonym for \\fB\\-background\\fR).\nThe \\fBclientData\\fR field is a string that gives the name of another\noption in the same table. Whenever the synonym option is used, the\ninformation from the other option will be used instead.\n.IP \\fBTK_OPTION_WINDOW\\fR\nThe value must be a window path name. The internal form is a\n\\fBTk_Window\\fR token for the window.\nThis option type requires \\fItkwin\\fR to be supplied to procedures\nsuch as \\fBTk_SetOptions\\fR (in order to identify the application),\nand it supports the \\fBTK_OPTION_NULL_OK\\fR flag.\n.SH \"STORAGE MANAGEMENT ISSUES\"\n.PP\nIf a field of a widget record has its offset stored in the \\fIobjOffset\\fR\nor \\fIinternalOffset\\fR field of a Tk_OptionSpec structure then the\nprocedures described here will handle all of the storage allocation and\nresource management issues associated with the field. When the value\nof an option is changed, \\fBTk_SetOptions\\fR (or \\fBTk_FreeSavedOptions\\fR)\nwill automatically free any resources associated with the old value, such as\nTk_Fonts for \\fBTK_OPTION_FONT\\fR options or dynamically allocated memory for\n\\fBTK_OPTION_STRING\\fR options. For an option stored as an object using the\n\\fIobjOffset\\fR field of a Tk_OptionSpec, the widget record shares the\nobject pointed to by the \\fIobjv\\fR value from the call to\n\\fBTk_SetOptions\\fR. The reference count for this object is incremented\nwhen a pointer to it is stored in the widget record and decremented when\nthe option is modified. When the widget is deleted\n\\fBTk_FreeConfigOptions\\fR should be invoked; it will free the resources\nassociated with all options and decrement reference counts for any\nobjects.\n.PP\nHowever, the widget code is responsible for storing NULL or \\fBNone\\fR in\nall pointer and token fields before invoking \\fBTk_InitOptions\\fR.\nThis is needed to allow proper cleanup in the rare case where\nan error occurs in \\fBTk_InitOptions\\fR.\n.SH \"OBJOFFSET VS. INTERNALOFFSET\"\n.PP\nIn most cases it is simplest to use the \\fIinternalOffset\\fR field of\na Tk_OptionSpec structure and not the \\fIobjOffset\\fR field. This\nmakes the internal form of the value immediately available to the\nwidget code so the value does not have to be extracted from an object\neach time it is used. However, there are two cases where the\n\\fIobjOffset\\fR field is useful. The first case is for\n\\fBTK_OPTION_PIXELS\\fR options. In this case, the internal form is\nan integer pixel value that is valid only for a particular screen.\nIf the value of the option is retrieved, it will be returned as a simple\nnumber. For example, after the command \\fB.b configure \\-borderwidth 2m\\fR,\nthe command \\fB.b configure \\-borderwidth\\fR might return 7, which is the\ninteger pixel value corresponding to \\fB2m\\fR. Unfortunately, this loses\nthe original screen-independent value. Thus for \\fBTK_OPTION_PIXELS\\fR options\nit is better to use the \\fIobjOffset\\fR field. In this case the original\nvalue of the option is retained in the object and can be returned when\nthe option is retrieved. It might seem convenient to use the\n\\fIinternalOffset\\fR field as well, so that the integer value is\nimmediately available for use in the widget code. But if scaling is\ninvolved, \\fIinternalOffset\\fR won't change value when the scaling\nchanges. Therefore it is better always to use\n\\fBTk_GetPixelsFromObj\\fR to extract the integer value from\nthe object whenever it is needed. Note: the problem of losing\ninformation on retrievals exists only for \\fBTK_OPTION_PIXELS\\fR options.\n.PP\nThe second reason to use the \\fIobjOffset\\fR field is in order to\nimplement new types of options not supported by these procedures.\nTo implement a new type of option, you can use \\fBTK_OPTION_STRING\\fR as\nthe type in the Tk_OptionSpec structure and set the \\fIobjOffset\\fR field\nbut not the \\fIinternalOffset\\fR field. Then, after calling\n\\fBTk_SetOptions\\fR, convert the object to internal form yourself.\n.PP\nTtk widgets do not support the \\fIinternalOffset\\fR machinery.\nOption values of Ttk widgets are always stored as (Tcl_Obj *), meaning that\nthe \\fIobjOffset\\fR field must be used.\n.SH \"CUSTOM OPTION TYPES\"\n.PP\nApplications can extend the built-in configuration types with\nadditional configuration types by writing procedures to parse, print,\nfree, and restore saved copies of the type and creating a structure\npointing to those procedures:\n.CS\ntypedef struct {\n const char *\\fIname\\fR;\n Tk_CustomOptionSetProc *\\fIsetProc\\fR;\n Tk_CustomOptionGetProc *\\fIgetProc\\fR;\n Tk_CustomOptionRestoreProc *\\fIrestoreProc\\fR;\n Tk_CustomOptionFreeProc *\\fIfreeProc\\fR;\n void *\\fIclientData\\fR;\n} \\fBTk_ObjCustomOption\\fR;\n\ntypedef int \\fBTk_CustomOptionSetProc\\fR(\n void *\\fIclientData\\fR,\n Tcl_Interp *\\fIinterp\\fR,\n Tk_Window \\fItkwin\\fR,\n Tcl_Obj **\\fIvaluePtr\\fR,\n char *\\fIrecordPtr\\fR,\n Tcl_Size \\fIinternalOffset\\fR,\n char *\\fIsaveInternalPtr\\fR,\n int \\fIflags\\fR);\n\ntypedef Tcl_Obj *\\fBTk_CustomOptionGetProc\\fR(\n void *\\fIclientData\\fR,\n Tk_Window \\fItkwin\\fR,\n char *\\fIrecordPtr\\fR,\n Tcl_Size \\fIinternalOffset\\fR);\n\ntypedef void \\fBTk_CustomOptionRestoreProc\\fR(\n void *\\fIclientData\\fR,\n Tk_Window \\fItkwin\\fR,\n char *\\fIinternalPtr\\fR,\n char *\\fIsaveInternalPtr\\fR);\n\ntypedef void \\fBTk_CustomOptionFreeProc\\fR(\n void *\\fIclientData\\fR,\n Tk_Window \\fItkwin\\fR,\n char *\\fIinternalPtr\\fR);\n.CE\n.PP\nThe Tk_ObjCustomOption structure contains six fields: a name\nfor the custom option type; pointers to the four procedures; and a\n\\fIclientData\\fR value to be passed to those procedures when they are\ninvoked. The \\fIclientData\\fR value typically points to a structure\ncontaining information that is needed by the procedures when they are\nparsing and printing options. \\fIRestoreProc\\fR and \\fIfreeProc\\fR\nmay be NULL, indicating that no function should be called for those\noperations.\n.PP\nThe \\fIsetProc\\fR procedure is invoked by \\fBTk_SetOptions\\fR to\nconvert a Tcl_Obj into an internal representation and store the\nresulting value in the widget record. The arguments are:\n.RS\n.IP \\fIclientData\\fR\nA copy of the \\fIclientData\\fR field in the Tk_ObjCustomOption\nstructure.\n.IP \\fIinterp\\fR\nA pointer to a Tcl interpreter, used for error reporting.\n.IP \\fITkwin\\fR\nA copy of the \\fItkwin\\fR argument to \\fBTk_SetOptions\\fR\n.IP \\fIvaluePtr\\fR\nA pointer to a reference to a Tcl_Obj describing the new value for the\noption; it could have been specified explicitly in the call to\n\\fBTk_SetOptions\\fR or it could come from the option database or a\ndefault. If the objOffset for the option is non-negative (the option\nvalue is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj\npointer referenced by \\fIvaluePtr\\fR is the pointer that will be\nstored at the objOffset for the option. \\fISetProc\\fR may modify the\nvalue if necessary; for example, \\fIsetProc\\fR may change the value to\nNULL to support the \\fBTK_OPTION_NULL_OK\\fR flag.\n.IP \\fIrecordPtr\\fR\nA pointer to the start of the widget record to modify.\n.IP \\fIinternalOffset\\fR\nOffset in bytes from the start of the widget record to the location\nwhere the internal representation of the option value is to be placed.\n.IP \\fIsaveInternalPtr\\fR\nA pointer to storage allocated in a Tk_SavedOptions structure for the\ninternal representation of the original option value. Before setting\nthe option to its new value, \\fIsetProc\\fR should set the value\nreferenced by \\fIsaveInternalPtr\\fR to the original value of the\noption in order to support \\fBTk_RestoreSavedOptions\\fR.\n.IP \\fIflags\\fR\nA copy of the \\fIflags\\fR field in the Tk_OptionSpec structure for the\noption\n.RE\n.PP\n\\fISetProc\\fR returns a standard Tcl result: \\fBTCL_OK\\fR to indicate successful\nprocessing, or \\fBTCL_ERROR\\fR to indicate a failure of any kind. An error\nmessage may be left in the Tcl interpreter given by \\fIinterp\\fR in\nthe case of an error.\n.PP\nThe \\fIgetProc\\fR procedure is invoked by \\fBTk_GetOptionValue\\fR and\n\\fBTk_GetOptionInfo\\fR to retrieve a Tcl_Obj representation of the\ninternal representation of an option. The \\fIclientData\\fR argument\nis a copy of the \\fIclientData\\fR field in the Tk_ObjCustomOption\nstructure. \\fITkwin\\fR is a copy of the \\fItkwin\\fR argument to\n\\fBTk_GetOptionValue\\fR or \\fBTk_GetOptionInfo\\fR. \\fIRecordPtr\\fR\nis a pointer to the beginning of the widget record to query.\n\\fIInternalOffset\\fR is the offset in bytes from the beginning of the\nwidget record to the location where the internal representation of the\noption value is stored. \\fIGetProc\\fR must return a pointer to a\nTcl_Obj representing the value of the option.\n.PP\nThe \\fIrestoreProc\\fR procedure is invoked by\n\\fBTk_RestoreSavedOptions\\fR to restore a previously saved internal\nrepresentation of a custom option value. The \\fIclientData\\fR argument\nis a copy of the \\fIclientData\\fR field in the Tk_ObjCustomOption\nstructure. \\fITkwin\\fR is a copy of the \\fItkwin\\fR argument to\n\\fBTk_GetOptionValue\\fR or \\fBTk_GetOptionInfo\\fR. \\fIInternalPtr\\fR\nis a pointer to the location where internal representation of the\noption value is stored.\n\\fISaveInternalPtr\\fR is a pointer to the saved value.\n\\fIRestoreProc\\fR must copy the value from \\fIsaveInternalPtr\\fR to\n\\fIinternalPtr\\fR to restore the value. \\fIRestoreProc\\fR need not\nfree any memory associated with either \\fIinternalPtr\\fR or\n\\fIsaveInternalPtr\\fR; \\fIfreeProc\\fR will be invoked to free that\nmemory if necessary. \\fIRestoreProc\\fR has no return value.\n.PP\nThe \\fIfreeProc\\fR procedure is invoked by \\fBTk_SetOptions\\fR and\n\\fBTk_FreeSavedOptions\\fR to free any storage allocated for the\ninternal representation of a custom option. The \\fIclientData\\fR argument\nis a copy of the \\fIclientData\\fR field in the Tk_ObjCustomOption\nstructure. \\fITkwin\\fR is a copy of the \\fItkwin\\fR argument to\n\\fBTk_GetOptionValue\\fR or \\fBTk_GetOptionInfo\\fR. \\fIInternalPtr\\fR\nis a pointer to the location where the internal representation of the\noption value is stored. The \\fIfreeProc\\fR must free any storage\nassociated with the option. \\fIFreeProc\\fR has no return value.\n.SH KEYWORDS\nanchor, bitmap, boolean, border, color, configuration option,\ncursor, double, font, integer, justify,\npixels, relief, screen distance, synonym\n" }, { "path": "doc/SetVisual.3", "content": "'\\\"\n'\\\" Copyright (c) 1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_SetWindowVisual 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_SetWindowVisual \\- change visual characteristics of window\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_SetWindowVisual\\fR(\\fItkwin, visual, depth, colormap\\fR)\n.fi\n.SH ARGUMENTS\n.AS \"Tk_Window int\" colormap\n.AP Tk_Window tkwin in\nToken for window.\n.AP Visual *visual in\nNew visual type to use for \\fItkwin\\fR.\n.AP \"int\" depth in\nNumber of bits per pixel desired for \\fItkwin\\fR.\n.AP Colormap colormap in\nNew colormap for \\fItkwin\\fR, which must be compatible with\n\\fIvisual\\fR and \\fIdepth\\fR.\n.BE\n.SH DESCRIPTION\n.PP\nWhen Tk creates a new window it assigns it the default visual\ncharacteristics (visual, depth, and colormap) for its screen.\n\\fBTk_SetWindowVisual\\fR may be called to change them.\n\\fBTk_SetWindowVisual\\fR must be called before the window has\nactually been created in X (e.g. before \\fBTk_MapWindow\\fR or\n\\fBTk_MakeWindowExist\\fR has been invoked for the window).\nThe safest thing is to call \\fBTk_SetWindowVisual\\fR immediately\nafter calling \\fBTk_CreateWindow\\fR.\nIf \\fItkwin\\fR has already been created before \\fBTk_SetWindowVisual\\fR\nis called then it returns 0 and does not make any changes; otherwise\nit returns 1 to signify that the operation\ncompleted successfully.\n.PP\nNote that \\fBTk_SetWindowVisual\\fR should not be called if you just want\nto change a window's colormap without changing its visual or depth;\ncall \\fBTk_SetWindowColormap\\fR instead.\n.SH KEYWORDS\ncolormap, depth, visual\n" }, { "path": "doc/StrictMotif.3", "content": "'\\\"\n'\\\" Copyright (c) 1995-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_StrictMotif 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_StrictMotif \\- Return value of tk_strictMotif variable\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_StrictMotif\\fR(\\fItkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window tkwin\n.AP Tk_Window tkwin in\nToken for window.\n.BE\n.SH DESCRIPTION\n.PP\nThis procedure returns the current value of the \\fBtk_strictMotif\\fR\nvariable in the interpreter associated with \\fItkwin\\fR's application.\nThe value is returned as an integer that is either 0 or 1.\n1 means that strict Motif compliance has been requested, so anything\nthat is not part of the Motif specification should be avoided.\n0 means that\n.QW Motif-like\nis good enough, and extra features are welcome.\n.PP\nThis procedure uses a link to the Tcl variable to provide much\nfaster access to the variable's value than could be had by calling\n\\fBTcl_GetVar\\fR.\n.SH KEYWORDS\nMotif compliance, tk_strictMotif variable\n" }, { "path": "doc/TextLayout.3", "content": "'\\\"\n'\\\" Copyright (c) 1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_ComputeTextLayout 3 8.1 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_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.\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_TextLayout\n\\fBTk_ComputeTextLayout\\fR(\\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\\fR)\n.sp\n\\fBTk_FreeTextLayout\\fR(\\fIlayout\\fR)\n.sp\n\\fBTk_DrawTextLayout\\fR(\\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\\fR)\n.sp\n\\fBTk_UnderlineTextLayout\\fR(\\fIdisplay, drawable, gc, layout, x, y, underline\\fR)\n.sp\nTcl_Size\n\\fBTk_PointToChar\\fR(\\fIlayout, x, y\\fR)\n.sp\nint\n\\fBTk_CharBbox\\fR(\\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\\fR)\n.sp\nint\n\\fBTk_DistanceToTextLayout\\fR(\\fIlayout, x, y\\fR)\n.sp\nint\n\\fBTk_IntersectTextLayout\\fR(\\fIlayout, x, y, width, height\\fR)\n.sp\n\\fBTk_TextLayoutToPostscript\\fR(\\fIinterp, layout\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_TextLayout \"*xPtr, *yPtr\"\n.AP Tk_Font tkfont in\nFont to use when constructing and displaying a text layout. The\n\\fItkfont\\fR must remain valid for the lifetime of the text layout. Must\nhave been returned by a previous call to \\fBTk_GetFont\\fR.\n.AP \"const char\" *string in\nPotentially multi-line string whose dimensions are to be computed and\nstored in the text layout. The \\fIstring\\fR must remain valid for the\nlifetime of the text layout.\n.AP int numChars in\nThe number of characters to consider from \\fIstring\\fR. If\n\\fInumChars\\fR is negative, then assumes \\fIstring\\fR is null\nterminated and uses \\fBTcl_NumUtfChars\\fR to determine the length of\n\\fIstring\\fR.\n.AP int wrapLength in\nLongest permissible line length, in pixels. Lines in \\fIstring\\fR will\nautomatically be broken at word boundaries and wrapped when they reach\nthis length. If \\fIwrapLength\\fR is too small for even a single\ncharacter to fit on a line, it will be expanded to allow one character to\nfit on each line. If \\fIwrapLength\\fR is <= 0, there is no automatic\nwrapping; lines will get as long as they need to be and only wrap if a\nnewline/return character is encountered.\n.AP Tk_Justify justify in\nHow to justify the lines in a multi-line text layout. Possible values\nare \\fBTK_JUSTIFY_LEFT\\fR, \\fBTK_JUSTIFY_CENTER\\fR, or\n\\fBTK_JUSTIFY_RIGHT\\fR. If the text layout only occupies a single\nline, then \\fIjustify\\fR is irrelevant.\n.AP int flags in\nVarious flag bits OR-ed together. \\fBTK_IGNORE_TABS\\fR means that tab\ncharacters should not be expanded to the next tab stop.\n\\fBTK_IGNORE_NEWLINES\\fR means that newline/return characters should\nnot cause a line break. If either tabs or newlines/returns are\nignored, then they will be treated as regular characters, being\nmeasured and displayed in a platform-dependent manner as described in\n\\fBTk_MeasureChars\\fR, and will not have any special behaviors.\n.AP int *widthPtr out\nIf non-NULL, filled with either the width, in pixels, of the widest\nline in the text layout, or the width, in pixels, of the bounding box for the\ncharacter specified by \\fIindex\\fR.\n.AP int *heightPtr out\nIf non-NULL, filled with either the total height, in pixels, of all\nthe lines in the text layout, or the height, in pixels, of the bounding\nbox for the character specified by \\fIindex\\fR.\n.AP Tk_TextLayout layout in\nA token that represents the cached layout information about the single-font,\nmulti-line, justified piece of text. This token is returned by\n\\fBTk_ComputeTextLayout\\fR.\n.AP Display *display in\nDisplay on which to draw.\n.AP Drawable drawable in\nWindow or pixmap in which to draw.\n.AP GC gc in\nGraphics context to use for drawing text layout. The font selected in\nthis GC must correspond to the \\fItkfont\\fR used when constructing the\ntext layout.\n.AP int \"x, y\" in\nPoint, in pixels, at which to place the upper-left hand corner of the\ntext layout when it is being drawn, or the coordinates of a point (with\nrespect to the upper-left hand corner of the text layout) to check\nagainst the text layout.\n.AP Tcl_Size firstChar in\nThe index of the first character to draw from the given text layout.\nThe number 0 means to draw from the beginning.\n.AP Tcl_Size lastChar in\nThe index of the last character up to which to draw. The character\nspecified by \\fIlastChar\\fR itself will not be drawn. A number less\nthan 0 means to draw all characters in the text layout.\n.AP int underline in\nIndex of the single character to underline in the text layout, or a\nnegative number counting backwards from the end of the string. Any\nout-of-range number (e.g. INT_MIN) means no underline.\n.AP Tcl_Size index in\nThe index of the character whose bounding box is desired. The bounding\nbox is computed with respect to the upper-left hand corner of the text layout.\n.AP int \"*xPtr, *yPtr\" out\nFilled with the upper-left hand corner, in pixels, of the bounding box\nfor the character specified by \\fIindex\\fR. Either or both \\fIxPtr\\fR\nand \\fIyPtr\\fR may be NULL, in which case the corresponding value\nis not calculated.\n.AP int \"width, height\" in\nSpecifies the width and height, in pixels, of the rectangular area to\ncompare for intersection against the text layout.\n.AP Tcl_Interp *interp out\nPostscript code that will print the text layout is appended to\nthe result of interpreter \\fIinterp\\fR.\n.BE\n.SH DESCRIPTION\n.PP\nThese routines are for measuring and displaying single-font, multi-line,\njustified text. To measure and display simple single-font, single-line\nstrings, refer to the documentation for \\fBTk_MeasureChars\\fR. There is\nno programming interface in the core of Tk that supports multi-font,\nmulti-line text; support for that behavior must be built on top of\nsimpler layers.\nNote that unlike the lower level text display routines, the functions\ndescribed here all operate on character-oriented lengths and indices\nrather than byte-oriented values. See the description of\n\\fBTcl_UtfAtIndex\\fR for more details on converting between character\nand byte offsets.\n.PP\nThe routines described here are built on top of the programming interface\ndescribed in the \\fBTk_MeasureChars\\fR documentation. Tab characters and\nnewline/return characters may be treated specially by these procedures,\nbut all other characters are passed through to the lower level.\n.PP\n\\fBTk_ComputeTextLayout\\fR computes the layout information needed to\ndisplay a single-font, multi-line, justified \\fIstring\\fR of text and\nreturns a Tk_TextLayout token that holds this information. This token is\nused in subsequent calls to procedures such as \\fBTk_DrawTextLayout\\fR,\n\\fBTk_DistanceToTextLayout\\fR, and \\fBTk_FreeTextLayout\\fR. The\n\\fIstring\\fR and \\fItkfont\\fR used when computing the layout must remain\nvalid for the lifetime of this token.\n.PP\n\\fBTk_FreeTextLayout\\fR is called to release the storage associated with\n\\fIlayout\\fR when it is no longer needed. A \\fIlayout\\fR should not be used\nin any other text layout procedures once it has been released.\n.PP\n\\fBTk_DrawTextLayout\\fR uses the information in \\fIlayout\\fR to display a\nsingle-font, multi-line, justified string of text at the specified location.\n.PP\n\\fBTk_UnderlineTextLayout\\fR uses the information in \\fIlayout\\fR to\ndisplay an underline below an individual character. This procedure does\nnot draw the text, just the underline. To produce natively underlined\ntext, an underlined font should be constructed and used. All characters,\nincluding tabs, newline/return characters, and spaces at the ends of\nlines, can be underlined using this method. However, the underline will\nnever be drawn outside of the computed width of \\fIlayout\\fR; the\nunderline will stop at the edge for any character that would extend\npartially outside of \\fIlayout\\fR, and the underline will not be visible\nat all for any character that would be located completely outside of the\nlayout.\n.PP\n\\fBTk_PointToChar\\fR uses the information in \\fIlayout\\fR to determine the\ncharacter closest to the given point. The point is specified with respect\nto the upper-left hand corner of the \\fIlayout\\fR, which is considered to be\nlocated at (0, 0). Any point whose \\fIy\\fR-value is less that 0 will be\nconsidered closest to the first character in the text layout; any point\nwhose \\fIy\\fR-value is greater than the height of the text layout will be\nconsidered closest to the last character in the text layout. Any point\nwhose \\fIx\\fR-value is negative will be considered closest to the first\ncharacter on that line; any point whose \\fIx\\fR-value is greater than the\nwidth of the text layout will be considered closest to the last character on\nthat line. The return value is the index of the character that was closest\nto the point, or one more than the index of any character (to indicate that\nthe point was after the end of the string and that the corresponding caret\nwould be at the end of the string). Given a \\fIlayout\\fR with no characters,\nthe value 0 will always be returned, referring to a hypothetical zero-width\nplaceholder character.\n.PP\n\\fBTk_CharBbox\\fR uses the information in \\fIlayout\\fR to return the\nbounding box for the character specified by \\fIindex\\fR. The width of the\nbounding box is the advance width of the character, and does not include any\nleft or right bearing. Any character that extends partially outside of\n\\fIlayout\\fR is considered to be truncated at the edge. Any character\nthat would be located completely outside of \\fIlayout\\fR is considered to\nbe zero-width and pegged against the edge. The height of the bounding\nbox is the line height for this font, extending from the top of the\nascent to the bottom of the descent; information about the actual height\nof individual letters is not available. For measurement purposes, a\n\\fIlayout\\fR that contains no characters is considered to contain a\nsingle zero-width placeholder character at index 0. If \\fIindex\\fR was\nnot a valid character index, the return value is 0 and \\fI*xPtr\\fR,\n\\fI*yPtr\\fR, \\fI*widthPtr\\fR, and \\fI*heightPtr\\fR are unmodified.\nOtherwise, if \\fIindex\\fR did specify a valid, the return value is\nnon-zero, and \\fI*xPtr\\fR, \\fI*yPtr\\fR, \\fI*widthPtr\\fR, and\n\\fI*heightPtr\\fR are filled with the bounding box information for the\ncharacter. If any of \\fIxPtr\\fR, \\fIyPtr\\fR, \\fIwidthPtr\\fR, or\n\\fIheightPtr\\fR are NULL, the corresponding value is not calculated or\nstored.\n.PP\n\\fBTk_DistanceToTextLayout\\fR computes the shortest distance in pixels from\nthe given point (\\fIx, y\\fR) to the characters in \\fIlayout\\fR.\nNewline/return characters and non-displaying space characters that occur at\nthe end of individual lines in the text layout are ignored for hit detection\npurposes, but tab characters are not. The return value is 0 if the point\nactually hits the \\fIlayout\\fR. If the point did not hit the \\fIlayout\\fR\nthen the return value is the distance in pixels from the point to the\n\\fIlayout\\fR.\n.PP\n\\fBTk_IntersectTextLayout\\fR determines whether a \\fIlayout\\fR lies\nentirely inside, entirely outside, or overlaps a given rectangle.\nNewline/return characters and non-displaying space characters that occur\nat the end of individual lines in the \\fIlayout\\fR are ignored for\nintersection calculations. The return value is \\-1 if the \\fIlayout\\fR is\nentirely outside of the rectangle, 0 if it overlaps, and 1 if it is\nentirely inside of the rectangle.\n.PP\n\\fBTk_TextLayoutToPostscript\\fR outputs code consisting of a Postscript\narray of strings that represent the individual lines in \\fIlayout\\fR. It\nis the responsibility of the caller to take the Postscript array of\nstrings and add some Postscript function operate on the array to render\neach of the lines. The code that represents the Postscript array of\nstrings is appended to interpreter \\fIinterp\\fR's result.\n.SH \"DISPLAY MODEL\"\n.PP\nWhen measuring a text layout, space characters that occur at the end of a\nline are ignored. The space characters still exist and the insertion point\ncan be positioned amongst them, but their additional width is ignored when\njustifying lines or returning the total width of a text layout. All\nend-of-line space characters are considered to be attached to the right edge\nof the line; this behavior is logical for left-justified text and reasonable\nfor center-justified text, but not very useful when editing right-justified\ntext. Spaces are considered variable width characters; the first space that\nextends past the edge of the text layout is clipped to the edge, and any\nsubsequent spaces on the line are considered zero width and pegged against\nthe edge. Space characters that occur in the middle of a line of text are\nnot suppressed and occupy their normal space width.\n.PP\nTab characters are not ignored for measurement calculations. If wrapping\nis turned on and there are enough tabs on a line, the next tab will wrap\nto the beginning of the next line. There are some possible strange\ninteractions between tabs and justification; tab positions are calculated\nand the line length computed in a left-justified world, and then the\nwhole resulting line is shifted so it is centered or right-justified,\ncausing the tab columns not to align any more.\n.PP\nWhen wrapping is turned on, lines may wrap at word breaks (space or tab\ncharacters) or newline/returns. A dash or hyphen character in the middle\nof a word is not considered a word break. \\fBTk_ComputeTextLayout\\fR\nalways attempts to place at least one word on each line. If it cannot\nbecause the \\fIwrapLength\\fR is too small, the word will be broken and as\nmuch as fits placed on the line and the rest on subsequent line(s). If\n\\fIwrapLength\\fR is so small that not even one character can fit on a\ngiven line, the \\fIwrapLength\\fR is ignored for that line and one\ncharacter will be placed on the line anyhow. When wrapping is turned\noff, only newline/return characters may cause a line break.\n.PP\nWhen a text layout has been created using an underlined \\fItkfont\\fR,\nthen any space characters that occur at the end of individual lines,\nnewlines/returns, and tabs will not be displayed underlined when\n\\fBTk_DrawTextLayout\\fR is called, because those characters are never\nactually drawn \\- they are merely placeholders maintained in the\n\\fIlayout\\fR.\n.SH KEYWORDS\nfont\n" }, { "path": "doc/TkInitStubs.3", "content": "'\\\"\n'\\\" Copyright (c) 1999 Scriptics Corporation\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_InitStubs 3 8.4 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_InitStubs \\- initialize the Tk stubs mechanism\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nconst char *\n\\fBTk_InitStubs\\fR(\\fIinterp, version, exact\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tcl_Interp *interp in\n.AP Tcl_Interp *interp in\nTcl interpreter handle.\n.AP char *version in\nA version string consisting of one or more decimal numbers\nseparated by dots.\n.AP int exact in\nNon-zero means that only the particular Tk version specified by\n\\fIversion\\fR is acceptable.\nZero means that versions newer than \\fIversion\\fR are also\nacceptable as long as they have the same major version number\nas \\fIversion\\fR.\n.BE\n.SH INTRODUCTION\n.PP\nThe Tcl stubs mechanism defines a way to dynamically bind\nextensions to a particular Tcl implementation at run time.\nthe stubs mechanism requires no changes to applications\nincorporating Tcl/Tk interpreters. Only developers creating\nC-based Tcl/Tk extensions need to take steps to use the\nstubs mechanism with their extensions.\nSee the \\fBTcl_InitStubs\\fR page for more information.\n.PP\nEnabling the stubs mechanism for a Tcl/Tk extension requires the following\nsteps:\n.IP 1) 5\nCall \\fBTcl_InitStubs\\fR in the extension before calling any other\nTcl functions.\n.IP 2) 5\nCall \\fBTk_InitStubs\\fR if the extension before calling any other\nTk functions.\n.IP 2) 5\nDefine the \\fBUSE_TCL_STUBS\\fR and the \\fBUSE_TK_STUBS\\fR\nsymbols. Typically, you would include the \\fB\\-DUSE_TCL_STUBS\\fR and\nthe \\fB\\-DUSE_TK_STUBS\\fR flags when compiling the extension.\n.IP 3) 5\nLink the extension with the Tcl and Tk stubs libraries instead of the\nstandard Tcl and Tk libraries. On Unix platforms, the library names\nare \\fIlibtclstub8.4.a\\fR and \\fIlibtkstub8.4.a\\fR; on Windows\nplatforms, the library names are \\fItclstub84.lib\\fR and\n\\fItkstub84.lib\\fR. Adjust the library names with appropriate version\nnumber but note that the extension may only be used with versions of\nTcl/Tk that have that version number or higher.\n.SH DESCRIPTION\n.PP\n\\fBTk_InitStubs\\fR attempts to initialize the Tk stub table pointers\nand ensure that the correct version of Tk is loaded. In addition\nto an interpreter handle, it accepts as arguments a version number\nand a Boolean flag indicating whether the extension requires\nan exact version match or not. If \\fIexact\\fR is 0, then the\nextension is indicating that newer versions of Tk are acceptable\nas long as they have the same major version number as \\fIversion\\fR;\nnon-zero means that only the specified \\fIversion\\fR is acceptable.\n\\fBTcl_InitStubs\\fR returns a string containing the actual version\nof Tk satisfying the request, or NULL if the Tk version is not\nacceptable, does not support the stubs mechanism, or any other\nerror condition occurred.\n.SH \"SEE ALSO\"\n\\fBTcl_InitStubs\\fR\n.SH KEYWORDS\nstubs\n" }, { "path": "doc/Tk_Init.3", "content": "'\\\"\n'\\\" Copyright (c) 1995-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_Init 3 8.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_Init, Tk_SafeInit \\- add Tk to an interpreter and make a new Tk application.\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nint\n\\fBTk_Init\\fR(\\fIinterp\\fR)\n.sp\nint\n\\fBTk_SafeInit\\fR(\\fIinterp\\fR)\n.SH ARGUMENTS\n.AP Tcl_Interp *interp in\nInterpreter in which to load Tk. Tk should not already be loaded\nin this interpreter.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_Init\\fR is the package initialization procedure for Tk.\nIt is normally invoked by the \\fBTcl_AppInit\\fR procedure\nfor an application or by the \\fBload\\fR command.\n\\fBTk_Init\\fR adds all of Tk's commands to \\fIinterp\\fR\nand creates a new Tk application, including its main window.\nIf the initialization is successful \\fBTk_Init\\fR returns\n\\fBTCL_OK\\fR; if there is an error it returns \\fBTCL_ERROR\\fR.\n\\fBTk_Init\\fR also leaves a result or error message\nin interpreter \\fIinterp\\fR's result.\n.PP\nIf there is a variable \\fBargv\\fR in \\fIinterp\\fR, \\fBTk_Init\\fR\ntreats the contents of this variable as a list of options for the\nnew Tk application.\nThe options may have any of the forms documented for the\n\\fBwish\\fR application (in fact, \\fBwish\\fR uses Tk_Init to process\nits command-line arguments).\n.PP\n\\fBTk_SafeInit\\fR is identical to \\fBTk_Init\\fR except that it removes\nall Tk commands that are considered unsafe. Those commands and the\nreasons for their exclusion are:\n.TP\n\\fBbell\\fR\n.\nContinuous ringing of the bell is a nuisance.\n.TP\n\\fBclipboard\\fR\n.\nA malicious script could replace the contents of the clipboard with\nthe string\n.QW \"\\fBrm \\-r *\\fR\"\nand lead to surprises when the contents of the clipboard are pasted.\n.TP\n\\fBgrab\\fR\n.\nGrab can be used to block the user from using any other applications.\n.TP\n\\fBmenu\\fR\n.\nMenus can be used to cover the entire screen and to steal input from\nthe user.\n.TP\n\\fBselection\\fR\n.\nSee clipboard.\n.TP\n\\fBsend\\fR\n.\nSend can be used to cause unsafe interpreters to execute commands.\n.TP\n\\fBtk\\fR\n.\nThe tk command recreates the send command, which is unsafe.\n.TP\n\\fBtkwait\\fR\n.\nTkwait can block the containing process forever\n.TP\n\\fBtoplevel\\fR\n.\nToplevels can be used to cover the entire screen and to steal input\nfrom the user.\n.TP\n\\fBwm\\fR\n.\nIf toplevels are ever allowed, wm can be used to remove decorations,\nmove windows around, etc.\n.SH KEYWORDS\nsafe, application, initialization, load, main window\n" }, { "path": "doc/Tk_Main.3", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_Main 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_Main \\- main program for Tk-based applications\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\n\\fBTk_Main\\fR(\\fIargc, argv, appInitProc\\fR)\n.SH ARGUMENTS\n.AS Tcl_AppInitProc *appInitProc\n.AP Tcl_Size argc in\nNumber of elements in \\fIargv\\fR.\n.AP char *argv[] in\nArray of strings containing command-line arguments. On Windows, when\nusing -DUNICODE, the parameter type changes to wchar_t *.\n.AP Tcl_AppInitProc *appInitProc in\nAddress of an application-specific initialization procedure.\nThe value for this argument is usually \\fBTcl_AppInit\\fR.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_Main\\fR acts as the main program for most Tk-based applications.\nStarting with Tk 4.0 it is not called \\fBmain\\fR anymore because it\nis part of the Tk library and having a function \\fBmain\\fR\nin a library (particularly a shared library) causes problems on many\nsystems.\nHaving \\fBmain\\fR in the Tk library would also make it hard to use\nTk in C++ programs, since C++ programs must have special C++\n\\fBmain\\fR functions.\n.PP\nNormally each application contains a small \\fBmain\\fR function that does\nnothing but invoke \\fBTk_Main\\fR.\n\\fBTk_Main\\fR then does all the work of creating and running a\n\\fBwish\\fR-like application.\n.PP\nWhen it is has finished its own initialization, but before\nit processes commands, \\fBTk_Main\\fR calls the procedure given by\nthe \\fIappInitProc\\fR argument. This procedure provides a\n.QW hook\nfor the application to perform its own initialization, such as defining\napplication-specific commands. The procedure must have an interface\nthat matches the type \\fBTcl_AppInitProc\\fR:\n.CS\ntypedef int \\fBTcl_AppInitProc\\fR(\n Tcl_Interp *\\fIinterp\\fR);\n.CE\n\\fIAppInitProc\\fR is almost always a pointer to \\fBTcl_AppInit\\fR;\nfor more details on this procedure, see the documentation\nfor \\fBTcl_AppInit\\fR.\n.PP\n\\fBTk_Main\\fR functions much the same as \\fBTcl_Main\\fR. In particular,\n\\fBTk_Main\\fR supports both an interactive mode and a startup script\nmode, with the file name and encoding of a startup script under the\ncontrol of the \\fBTcl_SetStartupScript\\fR and \\fBTcl_GetStartupScript\\fR\nroutines. However it calls \\fBTk_MainLoop\\fR after processing any\nsupplied script, and in interactive uses events registered with\n\\fBTcl_CreateFileHandler\\fR to process user input.\n.SH \"SEE ALSO\"\nTcl_DoOneEvent(3)\n.SH KEYWORDS\napplication-specific initialization, command-line arguments, main program\n" }, { "path": "doc/WinUtil.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1993 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_ConfigureWindow 3 4.0 Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_GetOtherWindow, Tk_MakeContainer, Tk_MakeWindow, Tk_UseWindow \\- window utility functions\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nTk_Window\n\\fBTk_GetOtherWindow\\fR(\\fItkwin\\fR)\n.sp\n\\fBTk_MakeContainer\\fR(\\fItkwin\\fR)\n.sp\n\\fBTk_MakeWindow\\fR(\\fItkwin, parent\\fR)\n.sp\nint\n\\fBTk_UseWindow\\fR(\\fIinterp, tkwin, string\\fR)\n.fi\n.SH ARGUMENTS\n.AS XSetWindowAttributes borderWidth\n.AP Tcl_Interp * interp in\nInterpreter associated with the application.\n.AP Tk_Window tkwin in\nToken for window.\n.AP Window parent in\nParent window.\n.AP \"const char\" *string in\nString identifying an X window to use for \\fItkwin\\fR; must be an integer value.\n.BE\n.SH DESCRIPTION\n.PP\nIf both the container and embedded window are in the same process,\n\\fBTk_GetOtherWindow\\fR will return either one, given the other.\nIf winPtr is a container, the return value is the token for the\nembedded window, and vice versa. If the \"other\" window isn't in this\nprocess, NULL is returned.\n.PP\n\\fBTk_MakeContainer\\fR is called to indicate that a particular window will be a\ncontainer for an embedded application. This changes certain aspects of\nthe window's behavior, such as whether it will receive events anymore.\n.PP\n\\fBTk_MakeWindow\\fR creates an actual window system window object based on the\ncurrent attributes of the specified TkWindow. It returns the handle to the new\nwindow, or None on failure.\n.PP\n\\fBTk_UseWindow\\fR causes a Tk window to use a given X window as its\nparent window, rather than the root window for the screen. It is\ninvoked by an embedded application to specify the window in which it\nis embedded.\n.PP\nThe return value is normally TCL_OK. If an error occurs (such as\nstring not being a valid window spec), then the return value is\nTCL_ERROR and an error message is left in the interp's result if\ninterp is non-NULL.\n.PP\n.SH KEYWORDS\nparent, window\n" }, { "path": "doc/WindowId.3", "content": "'\\\"\n'\\\" Copyright (c) 1990-1993 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1997 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Tk_WindowId 3 \"8.4\" Tk \"Tk Library Procedures\"\n.so man.macros\n.BS\n.SH NAME\nTk_WindowId, Tk_Parent, Tk_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_AlwaysShowSelection, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsContainer, Tk_IsEmbedded, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_MinReqWidth, Tk_MinReqHeight, Tk_InternalBorderLeft, Tk_InternalBorderRight, Tk_InternalBorderTop, Tk_InternalBorderBottom, Tk_Visual, Tk_Depth, Tk_Colormap, Tk_Interp, Tk_NewWindowObj \\- retrieve information from Tk's local data structure\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n.sp\nWindow\n\\fBTk_WindowId\\fR(\\fItkwin\\fR)\n.sp\nTk_Window\n\\fBTk_Parent\\fR(\\fItkwin\\fR)\n.sp\nDisplay *\n\\fBTk_Display\\fR(\\fItkwin\\fR)\n.sp\nconst char *\n\\fBTk_DisplayName\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_ScreenNumber\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_AlwaysShowSelection\\fR(\\fItkwin\\fR)\n.sp\nScreen *\n\\fBTk_Screen\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_X\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_Y\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_Width\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_Height\\fR(\\fItkwin\\fR)\n.sp\nXWindowChanges *\n\\fBTk_Changes\\fR(\\fItkwin\\fR)\n.sp\nXSetWindowAttributes *\n\\fBTk_Attributes\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_IsContainer\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_IsEmbedded\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_IsMapped\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_IsTopLevel\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_ReqWidth\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_ReqHeight\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_MinReqWidth\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_MinReqHeight\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_InternalBorderLeft\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_InternalBorderRight\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_InternalBorderTop\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_InternalBorderBottom\\fR(\\fItkwin\\fR)\n.sp\nVisual *\n\\fBTk_Visual\\fR(\\fItkwin\\fR)\n.sp\nint\n\\fBTk_Depth\\fR(\\fItkwin\\fR)\n.sp\nColormap\n\\fBTk_Colormap\\fR(\\fItkwin\\fR)\n.sp\nTcl_Interp *\n\\fBTk_Interp\\fR(\\fItkwin\\fR)\n.sp\nTcl_Obj *\n\\fBTk_NewWindowObj\\fR(\\fItkwin\\fR)\n.fi\n.SH ARGUMENTS\n.AS Tk_Window tkwin\n.AP Tk_Window tkwin in\nToken for window.\n.BE\n.SH DESCRIPTION\n.PP\n\\fBTk_WindowId\\fR and the other names listed above are\nall macros that return fields from Tk's local data structure\nfor \\fItkwin\\fR. None of these macros requires any\ninteraction with the server; it is safe to assume that\nall are fast.\n.PP\n\\fBTk_WindowId\\fR returns the X identifier for \\fItkwin\\fR,\nor \\fBNULL\\fR if no X window has been created for \\fItkwin\\fR\nyet.\n.PP\n\\fBTk_Parent\\fR returns Tk's token for the logical parent of\n\\fItkwin\\fR. The parent is the token that was specified when\n\\fItkwin\\fR was created, or NULL for main windows.\n.PP\n\\fBTk_Interp\\fR returns the Tcl interpreter associated with a\n\\fItkwin\\fR or NULL if there is an error.\n.PP\n\\fBTk_Display\\fR returns a pointer to the Xlib display structure\ncorresponding to \\fItkwin\\fR. \\fBTk_DisplayName\\fR returns an\nASCII string identifying \\fItkwin\\fR's display. \\fBTk_ScreenNumber\\fR\nreturns the index of \\fItkwin\\fR's screen among all the screens\nof \\fItkwin\\fR's display. \\fBTk_Screen\\fR returns a pointer to\nthe Xlib structure corresponding to \\fItkwin\\fR's screen.\n\\fBTk_AlwaysShowSelection\\fR indicates whether text/entry widgets\nshould always display their selection, regardless of window focus.\n.PP\n\\fBTk_X\\fR, \\fBTk_Y\\fR, \\fBTk_Width\\fR, and \\fBTk_Height\\fR\nreturn information about \\fItkwin's\\fR location within its\nparent and its size. The location information refers to the\nupper-left pixel in the window, or its border if there is one.\nThe width and height information refers to the interior size\nof the window, not including any border. \\fBTk_Changes\\fR\nreturns a pointer to a structure containing all of the above\ninformation plus a few other fields. \\fBTk_Attributes\\fR\nreturns a pointer to an XSetWindowAttributes structure describing\nall of the attributes of the \\fItkwin\\fR's window, such as background\npixmap, event mask, and so on (Tk keeps track of all this information\nas it is changed by the application). Note that it is essential that\napplications use Tk procedures like \\fBTk_ResizeWindow\\fR instead\nof X procedures like \\fBXResizeWindow\\fR, so that Tk can keep its\ndata structures up-to-date.\n.PP\n\\fBTk_IsContainer\\fR returns a non-zero value if \\fItkwin\\fR\nis a container, and that some other application may be embedding\nitself inside \\fItkwin\\fR.\n.PP\n\\fBTk_IsEmbedded\\fR returns a non-zero value if \\fItkwin\\fR\nis not a free-standing window, but rather is embedded in some\nother application.\n.PP\n\\fBTk_IsMapped\\fR returns a non-zero value if \\fItkwin\\fR\nis mapped and zero if \\fItkwin\\fR is not mapped.\n.PP\n\\fBTk_IsTopLevel\\fR returns a non-zero value if \\fItkwin\\fR\nis a top-level window (its X parent is the root window of the\nscreen) and zero if \\fItkwin\\fR is not a top-level window.\n.PP\n\\fBTk_ReqWidth\\fR and \\fBTk_ReqHeight\\fR return information about\nthe window's requested size. These values correspond to the last\ncall to \\fBTk_GeometryRequest\\fR for \\fItkwin\\fR.\n.PP\n\\fBTk_MinReqWidth\\fR and \\fBTk_MinReqHeight\\fR return information about\nthe window's minimum requested size. These values correspond to the last\ncall to \\fBTk_SetMinimumRequestSize\\fR for \\fItkwin\\fR.\n.PP\n\\fBTk_InternalBorderLeft\\fR, \\fBTk_InternalBorderRight\\fR,\n\\fBTk_InternalBorderTop\\fR and \\fBTk_InternalBorderBottom\\fR\nreturn the width of one side of the internal border\nthat has been requested for \\fItkwin\\fR, or 0 if no internal border was\nrequested. The return value is simply the last value passed to\n\\fBTk_SetInternalBorder\\fR or \\fBTk_SetInternalBorderEx\\fR for \\fItkwin\\fR.\n.PP\n\\fBTk_Visual\\fR, \\fBTk_Depth\\fR, and \\fBTk_Colormap\\fR return\ninformation about the visual characteristics of a window.\n\\fBTk_Visual\\fR returns the visual type for\nthe window, \\fBTk_Depth\\fR returns the number of bits per pixel,\nand \\fBTk_Colormap\\fR returns the current\ncolormap for the window. The visual characteristics are\nnormally set from the defaults for the window's screen, but\nthey may be overridden by calling \\fBTk_SetWindowVisual\\fR.\n.PP\n\\fBTk_NewWindowObj\\fR creates a new \\fBTcl_Obj\\fR from the window.\n.SH KEYWORDS\nattributes, colormap, depth, display, height, geometry manager,\nidentifier, mapped, requested size, screen, top-level,\nvisual, width, window, x, y\n" }, { "path": "doc/accessible.n", "content": ".\\\" Automatically generated by Pandoc 3.6.4\n'\\\"\n'\\\" Copyright (c) 2025 Kevin Walzer\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n.TH tk accessible n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n.SH NAME\naccessible \\- Adds screenreader support for core Tk and ttk widgets.\n.SH SYNOPSIS\n.nf\n\\fBtk accessible set_acc_role \\fIwindow value\\fR\n\\fBtk accessible set_acc_name \\fIwindow value\\fR\n\\fBtk accessible set_acc_description \\fIwindow value\\fR\n\\fBtk accessible set_acc_value \\fIwindow value\\fR\n\\fBtk accessible set_acc_state \\fIwindow value\\fR\n\\fBtk accessible set_acc_action \\fIwindow value\\fR\n\\fBtk accessible set_acc_help \\fIwindow value\\fR\n\\fBtk accessible get_acc_role \\fIwindow \\fR\n\\fBtk accessible get_acc_name \\fIwindow\\fR\n\\fBtk accessible get_acc_description \\fIwindow\\fR\n\\fBtk accessible get_acc_value \\fIwindow \\fR\n\\fBtk accessible get_acc_state \\fIwindow\\fR\n\\fBtk accessible get_acc_action \\fIwindow \\fR\n\\fBtk accessible get_acc_help \\fIwindow\\fR\n\\fBtk accessible add_acc_object \\fIwindow\\fR\n\\fBtk accessible emit_selection_change \\fIwindow\\fR\n\\fBtk accessible emit_focus_change \\fIwindow\\fR\n\\fBtk accessible check_screenreader\\fR\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBtk accessible\\fR command makes core Tk and ttk widgets\naccessible to a screen reader.\n.BE\n.SH INTRODUCTION\n.PP\nAll major computing platforms provide one or more API's to make GUI\napplications accessible to visually-impaired users who work using screen\nreader tools.\nScreen readers provide auditory feedback to users of a GUI application,\nand may provide additional or alternative methods to navigating\nGUI's apart from standard keyboard navigation.\nThe \\fBtk accessible \\fRcommand layers a platform neutral API on top\nof platform-specific API's to support accessibility on Linux/Unix,\nmacOS, and Windows.\n.PP\nThe \\fBtk accessible\\fR command is intended to provide a basic\naccessible-out-of-the-box experience for end users and\nrequires little additional work by developers.\nIf a screen reader is in operation, Tcl/Tk applications will be\naccessible.\nThe \\fBtk accessible \\fRcommand set does allow for additional\ncustomization on the part of developers.\nAnd widgets that are not part of the core Tk widget set can enable\naccessibility by using the tk accessible command set to specific the\naccessible role, name, description, value, state (if applicable), and\naction (if applicable).\n.SH OPERATIONS\n.PP\nThe following operations are available for the \\fBtk accessible\\fR\ncommand:\n.TP\n\\fBtk accessible set_acc_role \\fIwindow value\\fR\n.\nAssigns one of the following accessibility roles to a Tk widget: Button,\nCanvas, Checkbutton, Combobox, Entry, Label, Listbox, Menu, Notebook,\nProgressbar, Scale, Scrollbar, Spinbox, Table, Text, and Tree.\nTk and ttk widgets having similar roles, such as a button and a\nttk::button, will both be assigned the same accessibility role as these\nwidgets are the same from an accessibility standpoint.\n.TP\n\\fBtk accessible set_acc_name \\fIwindow value\\fR\n.\nShort label identifying the widget.\nDefaults to the accessibility role.\n.TP\n\\fBtk accessible set_acc_description\\fI window value\\fR\n.\nLonger string providing additional detail about the widget.\nDepending on the widget, may default to returning the widget's -text\noption or some similar detail.\n.TP\n\\fBtk accessible set_acc_value \\fIwindow value\\fR\n.\nSets the widget's accessibility value.\nFor instance, with a scale widget, will return the current numeric value\nof the scale.\n.TP\n\\fBtk accessible set_acc_state \\fIwindow value\\fR\n.\n\\fI \\fRSets the widget's accessibility state, from one of the\nstandard Tk widget states.\n.TP\n\\fBtk accessible set_acc_action \\fIwindow value\\fR\n.\n\\fI \\fRSets the command associated with the widget, if any.\\fI\n\\fR\n.TP\n\\fBtk accessible set_acc_help \\fIwindow value\\fR\n.\nString providing additional information on the widget and its purpose.\nFor instance, can provide details on specific keyboard navigation for\nthe widget.\n.TP\n\\fBtk accessible get_acc_role \\fIwindow \\fR\n.\nReturns the widget's accessibility role.\n.TP\n\\fBtk accessible get_acc_name \\fIwindow\\fR\n.\nReturns the widget's accessibility name.\n.TP\n\\fBtk accessible get_acc_description \\fIwindow\\fR\n.\nReturns the widget's accessibility description.\n.TP\n\\fBtk accessible get_acc_value \\fIwindow \\fR\n.\nReturns the widget's accessibility value.\n.TP\n\\fBtk accessible get_acc_state \\fIwindow\\fR\n.\nReturns the widget's accessibility state.\n.TP\n\\fBtk accessible get_acc_action \\fIwindow \\fR\n.\nReturns the widget's accessibility action.\n.TP\n\\fBtk accessible get_acc_help \\fIwindow\\fR\n.\nReturns the widget's accessibility help.\\fI \\fR\n.TP\n\\fBtk accessible add_acc_object \\fIwindow\\fR\n.\nRegisters the widget with the platform's accessibility API and\nenables accessibility for the widget.\n.TP\n\\fBtk accessible emit_selection_change \\fIwindow\\fR\n.\nNotifies the system when selection, value or other data associated with\nthe widget changes.\n.TP\n\\fBtk accessible emit_focus_change \\fIwindow\\fR\n.\nNotifies the accessibility system when focus changes.\n.TP\n\\fBtk accessible check_screenreader\\fR\n.\nChecks to see if the system is running a screen reader or other\naccessibility process.\n.PP\n.SH ADDITIONAL NOTES\n.PP\nSome Tk GUI components, such as frames and panedwindows, are not\nincluded in the accessibility API because they are just containers and\ndo not handle actions or data.\nAlso, the canvas is not included in the accessibility API because it is\na purely visual widget; the HTML5 canvas widget is not accessible to web\nAPI's for the same reason.\nDevelopers may choose to provide alternative data to provide information\non the canvas widget, such as labels or help text. Finally,\naccessibility only runs in the main Tk interpreter, because of\npotential conflicts in child interpreters; also, accessibility is not\nsupported under XQuartz (the X11 environment on macOS) because of too\nmany conflicts between the X11 and macOS versions of accessibility.\n.SH KEYWORDS\nwidget, tk\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/attribtable.n", "content": ".\\\"\n.\\\" Copyright (c) 2025 Csaba Nemethi\n.\\\"\n.\\\" See the file \"license.terms\" for information on usage and redistribution\n.\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n.\\\"\n.TH tk attribtable n 9.1 \"\" Tk \"Tk Built-in Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nattribtable \\- Create an attribute table, used to query and modify\narbitrary data attached to any widget.\n.SH SYNOPSIS\n\\fBtk attribtable \\fItableName\\fR\n.BE\n.SH DESCRIPTION\n.PP\nThis command creates an attribute table of the name \\fItableName\\fR,\nimplemented as a hash table and accessible as a command in the namespace of\nthe calling context if not fully qualified, and returns the fully qualified\nname of the command just created.\n.PP\nAn attribute table is used to query and modify arbitrary data attached to any\nwidget. These data are commonly called \\fIattributes\\fR.\n.PP\nIf an attribute table of the given name already exists then it is replaced\nwith the new one and all the attributes of all widgets set using the old table\ninstance will be unset.\n.PP\n\\fBREMARK 1:\\fR When the \\fItableName\\fR command is deleted (via \\fBrename\\fR\n\\fItableName\\fR \"\" or by deleting the containing namespace), all the\nattributes of all widgets set using this command are automatically unset and\nthe underlying hash table is deleted. This will free all the memory used by\nthe table.\n.PP\n\\fBREMARK 2:\\fR When a widget is destroyed, all of its attributes set by all\nattribute table commands are automatically unset. This will free all the\nmemory used by the widget's attributes.\n.PP\nThe command \\fItableName\\fR created by this command has the signature\n.PP\n.CS\n\\fItableName\\fR \\fBset\\fR|\\fBget\\fR|\\fBunset\\fR|\\fBclear\\fR|\\fBexists\\fR|\\fBnames\\fR|\\fBpathnames\\fR \\fIargs\\fR\n.CE\n.PP\nIn the description of the supported forms below, \\fIpathName\\fR specifies a\nwidget whose attributes are being queried or modified via the \\fItableName\\fR\ncommand.\n.\\\" METHOD: set\n.TP\n\\fItableName\\fR \\fBset\\fR \\fIpathName name value\\fR ?\\fIname value\\fR ...?\n.\nSets (i.e., adds or updates) the attributes identified by the \\fIname\\fR\narguments to the values given by the \\fIvalue\\fR arguments. Returns an empty\nstring. Example:\n.RS\n.PP\n.CS\n# Save and then change the button's text\n\\fBtk attribtable\\fR table\ntable \\fBset\\fR .btn prevText [.btn cget -text]\n\\&.btn configure -text \"NewText\"\n.CE\n.RE\n.\\\" METHOD: get\n.TP\n\\fItableName\\fR \\fBget\\fR \\fIpathName\\fR ?\\fIname\\fR ?\\fIdefaultValue\\fR??\n.\nIf \\fIname\\fR is specified then returns the corresponding attribute value, or\nan empty string or \\fIdefaultValue\\fR (if given) if no corresponding value\nexists. Otherwise returns a list consisting of all attribute names and values\nof the widget \\fIpathName\\fR. Example:\n.RS\n.PP\n.CS\n# Restore the button's previous text\n\\&.btn configure -text [table \\fBget\\fR .btn prevText]\n.CE\n.RE\n.\\\" METHOD: unset\n.TP\n\\fItableName\\fR \\fBunset\\fR \\fIpathName name\\fR ?\\fIname\\fR ...?\n.\nUnsets the attributes identified by the \\fIname\\fR arguments. Returns an\nempty string. Example:\n.RS\n.PP\n.CS\ntable \\fBunset\\fR .btn prevText\n.CE\n.RE\n.\\\" METHOD: clear\n.TP\n\\fItableName\\fR \\fBclear\\fR \\fIpathName\\fR\n.\nUnsets all attributes and removes \\fIpathName\\fR from the list of those\nwidgets that have attributes set via \\fItableName\\fR \\fBset\\fR. Returns an\nempty string. Example:\n.RS\n.PP\n.CS\ntable \\fBclear\\fR .btn\n.CE\n.RE\n.\\\" METHOD: exists\n.TP\n\\fItableName\\fR \\fBexists\\fR \\fIpathName\\fR ?\\fIname\\fR?\n.\nIf the optional argument is present then returns \\fB1\\fR if the attribute\nidentified by \\fIname\\fR exists and \\fB0\\fR otherwise. Without the optional\nargument the return value is \\fB1\\fR if the widget \\fIpathName\\fR has at\nleast one attribute set via \\fItableName\\fR \\fBset\\fR and \\fB0\\fR otherwise.\nExample:\n.RS\n.PP\n.CS\nif [table \\fBexists\\fR .btn prevText] {\n # Restore the button's previous text\n \\&.btn configure -text [table \\fBget\\fR .btn prevText]\n}\n.CE\n.RE\n.\\\" METHOD: names\n.TP\n\\fItableName\\fR \\fBnames\\fR \\fIpathName\\fR\n.\nReturns a list consisting of all attribute names of the widget\n\\fIpathName\\fR. Example:\n.RS\n.PP\n.CS\nputs \"attribute names for .btn: [table \\fBnames\\fR .btn]\"\n.CE\n.RE\n.\\\" METHOD: pathnames\n.TP\n\\fItableName\\fR \\fBpathnames\\fR\n.\nReturns a list consisting of the path names of all widgets that have\nattributes set via \\fItableName\\fR \\fBset\\fR.\nExample:\n.RS\n.PP\n.CS\nputs \"widgets in table: [table \\fBpathnames\\fR]\"\n.CE\n.RE\n.SH KEYWORDS\nwidget, attribute, attribute table\n.\\\" Local Variables:\n.\\\" mode: nroff\n.\\\" fill-column: 78\n.\\\" End:\n" }, { "path": "doc/bell.n", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\" Copyright (c) 2000 Ajuba Solutions.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH bell n 8.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nbell \\- Ring a display's bell\n.SH SYNOPSIS\n\\fBbell \\fR?\\fB\\-displayof \\fIwindow\\fR? ?\\fB\\-nice\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThis command rings the bell on the display for \\fIwindow\\fR and\nreturns an empty string.\nIf the \\fB\\-displayof\\fR option is omitted, the display of the\napplication's main window is used by default.\nThe command uses the current bell-related settings for the display, which\nmay be modified with programs such as \\fBxset\\fR.\n.PP\nIf \\fB\\-nice\\fR is not specified, this command also resets the screen saver\nfor the screen. Some screen savers will ignore this, but others will reset\nso that the screen becomes visible again.\n.SH KEYWORDS\nbeep, bell, ring\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/bind.n", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\" Copyright (c) 1998 Scriptics Corporation.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH bind n 8.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nbind \\- Arrange for X events to invoke Tcl scripts\n.SH SYNOPSIS\n\\fBbind\\fI tag\\fR ?\\fIsequence\\fR? ?\\fB+\\fR??\\fIscript\\fR?\n.BE\n.SH \"INTRODUCTION\"\n.PP\nThe \\fBbind\\fR command associates Tcl scripts with X events.\nIf all three arguments are specified, \\fBbind\\fR will\narrange for \\fIscript\\fR (a Tcl script called the\n.QW \"binding script\")\nto be evaluated whenever the event(s) given by \\fIsequence\\fR\noccur in the window(s) identified by \\fItag\\fR.\nIf \\fIscript\\fR is prefixed with a\n.QW + ,\nthen it is appended to\nany existing binding for \\fIsequence\\fR; otherwise \\fIscript\\fR replaces\nany existing binding.\nIf \\fIscript\\fR is an empty string then the current binding for\n\\fIsequence\\fR is destroyed, leaving \\fIsequence\\fR unbound.\nIn all of the cases where a \\fIscript\\fR argument is provided,\n\\fBbind\\fR returns an empty string.\n.PP\nIf \\fIsequence\\fR is specified without a \\fIscript\\fR, then the\nscript currently bound to \\fIsequence\\fR is returned, or\nan empty string is returned if there is no binding for \\fIsequence\\fR.\nIf neither \\fIsequence\\fR nor \\fIscript\\fR is specified, then the\nreturn value is a list whose elements are all the sequences\nfor which there exist bindings for \\fItag\\fR.\n.PP\nThe \\fItag\\fR argument determines which window(s) the binding applies to.\nIf \\fItag\\fR begins with a dot, as in \\fB.a.b.c\\fR, then it must\nbe the path name for a window; otherwise it may be an arbitrary\nstring.\nEach window has an associated list of tags, and a binding applies\nto a particular window if its tag is among those specified for\nthe window.\nAlthough the \\fBbindtags\\fR command may be used to assign an\narbitrary set of binding tags to a window, the default binding\ntags provide the following behavior:\n.IP \\(bu 3\nIf a tag is the name of an internal window the binding applies\nto that window.\n.IP \\(bu 3\nIf the tag is the name of a class of widgets, such as \\fBButton\\fR,\nthe binding applies to all widgets in that class.\n.IP \\(bu 3\nIf the tag is the name of a toplevel window the binding applies\nto the toplevel window and all its internal windows.\n.IP \\(bu 3\nIf \\fItag\\fR has the value \\fBall\\fR,\nthe binding applies to all windows in the application.\n.SH \"EVENT PATTERNS\"\n.PP\nThe \\fIsequence\\fR argument specifies a sequence of one or more\nevent patterns, with optional white space between the patterns. Each\nevent pattern may\ntake one of three forms. In the simplest case it is a single\nprinting ASCII character, such as \\fBa\\fR or \\fB[\\fR. The character\nmay not be a space character or the character \\fB<\\fR. This form of\npattern matches a \\fBKey\\fR event for the particular\ncharacter. The second form of pattern is longer but more general.\nIt has the following syntax:\n.CS\n\\fB<\\fImodifier\\-modifier\\-type\\-detail\\fB>\\fR\n.CE\nThe entire event pattern is surrounded by angle brackets.\nInside the angle brackets are zero or more modifiers, an event\ntype, and an extra piece of information (\\fIdetail\\fR) identifying\na particular button or keysym. Any of the fields may be omitted,\nas long as at least one of \\fItype\\fR and \\fIdetail\\fR is present.\nThe fields must be separated by white space or dashes.\n.PP\nThe third form of pattern is used to specify a user-defined, named virtual\nevent. It has the following syntax:\n.CS\n\\fB<<\\fIname\\fB>>\\fR\n.CE\nThe entire virtual event pattern is surrounded by double angle brackets.\nInside the angle brackets is the user-defined name of the virtual event.\nModifiers, such as \\fBShift\\fR or \\fBControl\\fR, may not be combined with a\nvirtual event to modify it. Bindings on a virtual event may be created\nbefore the virtual event is defined, and if the definition of a virtual\nevent changes dynamically, all windows bound to that virtual event will\nrespond immediately to the new definition.\n.PP\nSome widgets (e.g. \\fBmenu\\fR and \\fBtext\\fR) issue virtual events\nwhen their internal state is updated in some ways. Please see the\nmanual page for each widget for details.\n.SS \"MODIFIERS\"\n.PP\nModifiers consist of any of the following values:\n.DS\n.ta 6c\n\\fBControl\\fR\t\\fBMod1\\fR, \\fBM1\\fR, \\fBCommand\\fR\n\\fBAlt\\fR\t\\fBMod2\\fR, \\fBM2\\fR, \\fBOption\\fR\n\\fBShift\\fR\t\\fBMod3\\fR, \\fBM3\\fR, \\fBNum\\fR\n\\fBLock\\fR\t\\fBMod4\\fR, \\fBM4\\fR, \\fBFn\\fR\n\\fBExtended\\fR\t\\fBMod5\\fR, \\fBM5\\fR\n\\fBButton1\\fR, \\fBB1\\fR\t\\fBMeta\\fR, \\fBM\\fR\n\\fBButton2\\fR, \\fBB2\\fR\t\\fBDouble\\fR\n\\fBButton3\\fR, \\fBB3\\fR\t\\fBTriple\\fR\n\\fBButton4\\fR, \\fBB4\\fR\t\\fBQuadruple\\fR\n\\fBButton5\\fR, \\fBB5\\fR\n.DE\nWhere more than one value is listed, separated by commas, the values\nare equivalent.\nMost of the modifiers have the obvious X meanings.\nFor example, \\fBButton1\\fR requires that\nbutton 1 be depressed when the event occurs.\nFor a binding to match a given event, the modifiers in the event\nmust include all of those specified in the event pattern.\nAn event may also contain additional modifiers not specified in\nthe binding.\nFor example, if button 1 is pressed while the shift and control keys\nare down, the pattern \\fB\\fR will match\nthe event, but \\fB\\fR will not.\nIf no modifiers are specified, then any combination of modifiers may\nbe present in the event.\n.PP\n\\fBMeta\\fR and \\fBM\\fR refer to whichever of the\n\\fBM1\\fR through \\fBM5\\fR modifiers is associated with the Meta\nkey(s) on the keyboard (keysyms \\fBMeta_R\\fR and \\fBMeta_L\\fR).\nIf there are no Meta keys, or if they are not associated with any\nmodifiers, then \\fBMeta\\fR and \\fBM\\fR will not match any events.\nSimilarly, the \\fBAlt\\fR modifier refers to whichever modifier\nis associated with the alt key(s) on the keyboard (keysyms\n\\fBAlt_L\\fR and \\fBAlt_R\\fR).\n.PP\nThe \\fBDouble\\fR, \\fBTriple\\fR and \\fBQuadruple\\fR modifiers are a\nconvenience for specifying double mouse clicks and other repeated\nevents. They cause a particular event pattern to be repeated 2, 3 or 4\ntimes, and also place a time and space requirement on the sequence: for a\nsequence of events to match a \\fBDouble\\fR, \\fBTriple\\fR or \\fBQuadruple\\fR\npattern, all of the events must occur close together in time and without\nsubstantial mouse motion in between. For example, \\fB\\fR\nis equivalent to \\fB\\fR with the extra time and space\nrequirement.\n.PP\nThe \\fBCommand\\fR, \\fBOption\\fR, \\fBNum\\fR and \\fBFn\\fRmodifiers are\nequivalents of \\fBMod1\\fR up to \\fBMod4\\fR; they correspond to\nMacintosh-specific modifier keys.\n.PP\nThe \\fBExtended\\fR modifier is, at present, specific to Windows. It\nappears on events that are associated with the keys on the\n.QW \"extended keyboard\" .\nOn a US keyboard, the extended keys include the \\fBAlt\\fR\nand \\fBControl\\fR keys at the right of the keyboard, the cursor keys\nin the cluster to the left of the numeric pad, the \\fBNumLock\\fR key,\nthe \\fBBreak\\fR key, the \\fBPrintScreen\\fR key, and the \\fB/\\fR and\n\\fBEnter\\fR keys in the numeric keypad.\n.SS \"EVENT TYPES\"\n.PP\nThe \\fItype\\fR field may be any of the standard X event types, with a\nfew extra abbreviations. The \\fItype\\fR field will also accept a\ncouple non-standard X event types that were added to better support\nthe Macintosh and Windows platforms. Below is a list of all the valid\ntypes; where two names appear together, they are synonyms.\n.DS\n.ta \\w'\\fBButton, ButtonPress\\0\\0\\0\\fR'u +\\w'\\fBKey, KeyPress\\0\\0\\0\\fR'u\n\\fBActivate\\fR\t\\fBDestroy\\fR\t\\fBMap\\fR\n\\fBButton\\fR, \\fBButtonPress\\fR\t\\fBEnter\\fR\t\\fBMapRequest\\fR\n\\fBButtonRelease\\fR\t\\fBExpose\\fR\t\\fBMotion\\fR\n\\fBCirculate\\fR\t\\fBFocusIn\\fR\t\\fBMouseWheel\\fR\n\\fBTouchpadScroll\\fR\t\\fBCirculateRequest\\fR\t\\fBFocusOut\\fR\n\\fBProperty\\fR\t\\fBColormap\\fR\t\\fBGravity\\fR\n\\fBReparent\\fR\t\\fBConfigure\\fR\t\\fBKey\\fR, \\fBKeyPress\\fR\n\\fBResizeRequest\\fR\t\\fBConfigureRequest\\fR\t\\fBKeyRelease\\fR\n\\fBUnmap\\fR \\fBCreate\\fR\t\\fBLeave\\fR\t\\fBVisibility\\fR\n\\fBDeactivate\\fR\n.DE\nMost of the above events have the same fields and behaviors as events\nin the X Windowing system. You can find more detailed descriptions of\nthese events in any X window programming book. A couple of the events\nare extensions to the X event system to support features unique to the\nMacintosh and Windows platforms. We provide a little more detail on\nthese events here. These include:\n.IP \"\\fBActivate\\fR, \\fBDeactivate\\fR\" 5\nThese two events are sent to every sub-window of a toplevel when they\nchange state. In addition to the focus Window, the Macintosh platform\nand Windows platforms have a notion of an active window (which often\nhas but is not required to have the focus). On the Macintosh, widgets\nin the active window have a different appearance than widgets in\ndeactive windows. The \\fBActivate\\fR event is sent to all the\nsub-windows in a toplevel when it changes from being deactive to\nactive. Likewise, the \\fBDeactive\\fR event is sent when the window's\nstate changes from active to deactive. There are no useful percent\nsubstitutions you would make when binding to these events.\n.IP \\fBMouseWheel\\fR 5\nMany contemporary mice include a mouse wheel, which is used\nfor scrolling documents without using the scrollbars. By rolling the\nwheel, the system will generate \\fBMouseWheel\\fR events that the\napplication can use to scroll. The event is routed to the\nwindow currently under the mouse pointer. When the event\nis received you can use the \\fB%D\\fR substitution to get the\n\\fIdelta\\fR field for the event, which is an integer value describing how\nthe mouse wheel has moved. The smallest value for which the\nsystem will report is defined by the OS. The sign of the\nvalue determines which direction your widget should scroll. Positive\nvalues should scroll up and negative values should scroll down.\n.RS\n.PP\nHorizontal scrolling uses \\fBShift-MouseWheel\\fR events, with positive\n\\fB%D\\fR \\fIdelta\\fR substitution indicating left scrolling and\nnegative right scrolling. Horizontal scrolling events are generated\ntilt wheels on some mice. Horizontal scrolling can also be emulated\nby holding Shift and scrolling vertically.\n.RE\n.IP \"\\fBTouchpadScroll\\fR\" 5\nOn some platforms (currently Windows and macOS) there is support for\nhigh-resolution scrolling devices, such as touchpads. This is\nprovided via \\fBTouchpadScroll\\fR events. These events store two\n16 bit delta values in the integer provided by the \\fB%D\\fR\nsubstitution. The \\fIX\\fR delta is in the high order 16 bits and the\n\\fIY\\fR delta is in the low order 16 bits. These values can be\nunpacked by using the tk::PreciseScrollDeltas utility procedure. For\nexample:\n.CS\nlassign [tk::PreciseScrollDeltas %D] deltaX deltaY\n.CE\nThe \\fB$#\\fR substitution is a counter for \\fBTouchpadScroll\\fR events\nwhich can be used by widgets that only support scrolling by units to\nignore some portion of the events.\n.IP \"\\fBKeyPress\\fR, \\fBKeyRelease\\fR\" 5\nThe \\fBKeyPress\\fR and \\fBKeyRelease\\fR events are generated\nwhenever a key is pressed or released. \\fBKeyPress\\fR and \\fBKeyRelease\\fR\n.IP \"\\fBKey\\fR, \\fBKeyRelease\\fR\" 5\nThe \\fBKey\\fR and \\fBKeyRelease\\fR events are generated\nwhenever a key is pressed or released. \\fBKey\\fR and \\fBKeyRelease\\fR\nevents are sent to the window which currently has the keyboard focus.\n.IP \"\\fBButton\\fR, \\fBButtonRelease\\fR, \\fBMotion\\fR\" 5\nThe \\fBButton\\fR and \\fBButtonRelease\\fR events\nare generated when the user presses or releases a mouse button.\n\\fBMotion\\fR events are generated whenever the pointer is moved.\n\\fBButton\\fR, \\fBButtonRelease\\fR, and \\fBMotion\\fR events are\nnormally sent to the window containing the pointer.\n.RS\n.PP\nWhen a mouse button is pressed, the window containing the pointer\nautomatically obtains a temporary pointer grab.\nSubsequent \\fBButton\\fR, \\fBButtonRelease\\fR, and \\fBMotion\\fR\nevents will be sent to that window,\nregardless of which window contains the pointer,\nuntil all buttons have been released.\n.RE\n.IP \\fBConfigure\\fR 5\nA \\fBConfigure\\fR event is sent to a window whenever its\nsize, position, or border width changes, and sometimes\nwhen it has changed position in the stacking order.\n.IP \"\\fBMap\\fR, \\fBUnmap\\fR\" 5\nThe \\fBMap\\fR and \\fBUnmap\\fR events are generated whenever the mapping\nstate of a window changes.\n.RS\n.PP\nWindows are created in the unmapped state.\nTop-level windows become mapped when they transition to the\n\\fBnormal\\fR state, and are unmapped in the \\fBwithdrawn\\fR\nand \\fBiconic\\fR states.\nOther windows become mapped when they are placed under control\nof a geometry manager (for example \\fBpack\\fR or \\fBgrid\\fR).\n.PP\nA window is \\fIviewable\\fR only if it and all of its ancestors are mapped.\nNote that geometry managers typically do not map their children until\nthey have been mapped themselves, and unmap all children\nwhen they become unmapped; hence in Tk \\fBMap\\fR and \\fBUnmap\\fR\nevents indicate whether or not a window is viewable.\n.RE\n.IP \\fBVisibility\\fR 5\nA window is said to be \\fIobscured\\fR when another window\nabove it in the stacking order fully or partially overlaps it.\n\\fBVisibility\\fR events are generated whenever a window's\nobscurity state changes; the \\fIstate\\fR field (\\fB%s\\fR)\nspecifies the new state.\n.IP \\fBExpose\\fR 5\nAn \\fBExpose\\fR event is generated whenever all or part of a\nwindow should be redrawn (for example, when a window is\nfirst mapped or if it becomes unobscured).\nIt is normally not necessary for client applications to\nhandle \\fBExpose\\fR events, since Tk handles them internally.\n.IP \\fBDestroy\\fR 5\nA \\fBDestroy\\fR event is delivered to a window when\nit is destroyed.\n.RS\n.PP\nWhen the \\fBDestroy\\fR event is delivered\nto a widget, it is in a\n.QW half-dead\nstate: the widget still exists, but operations that involve it\nmay return invalid results, or return an error.\n.RE\n.IP \"\\fBFocusIn\\fR, \\fBFocusOut\\fR\" 5\nThe \\fBFocusIn\\fR and \\fBFocusOut\\fR events are generated\nwhenever the keyboard focus changes.\nA \\fBFocusOut\\fR event is sent to the old focus window,\nand a \\fBFocusIn\\fR event is sent to the new one.\n.RS\n.PP\nIn addition,\nif the old and new focus windows do not share a common parent,\n.QW \"virtual crossing\"\nfocus events are sent to the intermediate windows in the hierarchy.\nThus a \\fBFocusIn\\fR event indicates\nthat the target window or one of its descendants has acquired the focus,\nand a \\fBFocusOut\\fR event indicates that the focus\nhas been changed to a window outside the target window's hierarchy.\n.PP\nThe keyboard focus may be changed explicitly by a call to \\fBfocus\\fR,\nor implicitly by the window manager.\n.RE\n.IP \"\\fBEnter\\fR, \\fBLeave\\fR\" 5\nAn \\fBEnter\\fR event is sent to a window when the pointer\nenters that window, and a \\fBLeave\\fR event is sent when\nthe pointer leaves it.\n.RS\n.PP\nIf there is a pointer grab in effect, \\fBEnter\\fR and \\fBLeave\\fR\nevents are only delivered to the window owning the grab.\n.PP\nIn addition, when the pointer moves\nbetween two windows, \\fBEnter\\fR and \\fBLeave\\fR\n.QW \"virtual crossing\"\nevents are sent to intermediate windows\nin the hierarchy in the same manner as for \\fBFocusIn\\fR and\n\\fBFocusOut\\fR events.\n.RE\n.IP \\fBProperty\\fR\nA \\fBProperty\\fR event is sent to a window whenever an X property\nbelonging to that window is changed or deleted.\n\\fBProperty\\fR events are not normally delivered to Tk applications as\nthey are handled by the Tk core.\n.IP \\fBColormap\\fR\nA \\fBColormap\\fR event is generated whenever the colormap\nassociated with a window has been changed, installed, or uninstalled.\n.RS\n.PP\nWidgets may be assigned a private colormap by\nspecifying a \\fB\\-colormap\\fR option; the window manager\nis responsible for installing and uninstalling colormaps\nas necessary.\n.PP\nNote that Tk provides no useful details for this event type.\n.RE\n'\\\" The following events were added in TIP#47\n.IP \"\\fBMapRequest\\fR, \\fBCirculateRequest\\fR, \\fBResizeRequest\\fR, \\fBConfigureRequest\\fR, \\fBCreate\\fR\" 5\nThese events are not normally delivered to Tk applications.\nThey are included for completeness, to make it possible to\nwrite X11 window managers in Tk.\n(These events are only delivered when a client has\nselected \\fBSubstructureRedirectMask\\fR on a window;\nthe Tk core does not use this mask.)\n.IP \"\\fBGravity\\fR, \\fBReparent\\fR, \\fBCirculate\\fR\" 5\nThe events \\fBGravity\\fR and \\fBReparent\\fR\nare not normally delivered to Tk applications.\nThey are included for completeness.\n.RS\n.PP\nA \\fBCirculate\\fR event indicates that the window has moved\nto the top or to the bottom of the stacking order as\na result of an \\fBXCirculateSubwindows\\fR protocol request.\nNote that the stacking order may be changed for other reasons\nwhich do not generate a \\fBCirculate\\fR event, and that\nTk does not use \\fBXCirculateSubwindows()\\fR internally.\nThis event type is included only for completeness;\nthere is no reliable way to track changes to a window's\nposition in the stacking order.\n.RE\n.SS \"EVENT DETAILS\"\n.PP\nThe last part of a long event specification is \\fIdetail\\fR. In the\ncase of a \\fBButton\\fR or \\fBButtonRelease\\fR event, it is the\nnumber of a button (1\\-9). If a button number is given, then only an\nevent on that particular button will match; if no button number is\ngiven, then an event on any button will match. Note: giving a\nspecific button number is different than specifying a button modifier;\nin the first case, it refers to a button being pressed or released,\nwhile in the second it refers to some other button that is already\ndepressed when the matching event occurs. If a button\nnumber is given then \\fItype\\fR may be omitted: if will default\nto \\fBButton\\fR. For example, the specifier \\fB<1>\\fR\nis equivalent to \\fB\\fR.\n.PP\nIf the event type is \\fBKey\\fR or \\fBKeyRelease\\fR, then\n\\fIdetail\\fR may be specified in the form of an X keysym. Keysyms\nare textual specifications for particular keys on the keyboard;\nthey include all the alphanumeric ASCII characters (e.g.\n.QW a\nis the keysym for the ASCII character\n.QW a ),\nplus descriptions for non-alphanumeric characters\n.PQ comma \"is the keysym for the comma character\" ,\nplus descriptions for all the non-ASCII keys on the keyboard (e.g.\n.QW Shift_L\nis the keysym for the left shift key, and\n.QW F1\nis the keysym for the F1 function key, if it exists). The\ncomplete list of keysyms is not presented here; it is\navailable in other X documentation and may vary from system to\nsystem.\nIf necessary, you can use the \\fB%K\\fR notation described below\nto print out the keysym name for a particular key.\nIf a keysym \\fIdetail\\fR is given, then the\n\\fItype\\fR field may be omitted; it will default to \\fBKey\\fR.\nFor example, \\fB\\fR is equivalent to\n\\fB\\fR.\n.SH \"BINDING SCRIPTS AND SUBSTITUTIONS\"\n.PP\nThe \\fIscript\\fR argument to \\fBbind\\fR is a Tcl script, called the\n.QW \"binding script\",\nwhich will be executed whenever the given event sequence occurs.\n\\fICommand\\fR will be executed in the same interpreter that the\n\\fBbind\\fR command was executed in, and it will run at global\nlevel (only global variables will be accessible).\nIf \\fIscript\\fR contains\nany \\fB%\\fR characters, then the script will not be\nexecuted directly. Instead, a new script will be\ngenerated by replacing each \\fB%\\fR, and the character following\nit, with information from the current event. The replacement\ndepends on the character following the \\fB%\\fR, as defined in the\nlist below. Unless otherwise indicated, the\nreplacement string is the decimal value of the given field from\nthe current event.\nSome of the substitutions are only valid for\ncertain types of events; if they are used for other types of events\nthe value substituted is undefined.\n.IP \\fB%%\\fR 5\nReplaced with a single percent.\n.IP \\fB%#\\fR 5\nThe number of the last client request processed by the server\n(the \\fIserial\\fR field from the event). Valid for all event\ntypes.\n.IP \\fB%a\\fR 5\nThe \\fIabove\\fR field from the event,\nformatted as a hexadecimal number.\nValid only for \\fBConfigure\\fR events.\nIndicates the sibling window immediately below the receiving window\nin the stacking order, or \\fB0\\fR if the receiving window is at the\nbottom.\n.IP \\fB%b\\fR 5\nThe number of the button that was pressed or released. Valid only\nfor \\fBButton\\fR and \\fBButtonRelease\\fR events.\n.IP \\fB%c\\fR 5\nThe \\fIcount\\fR field from the event. Valid only for \\fBExpose\\fR events.\nIndicates that there are \\fIcount\\fR pending \\fBExpose\\fR events which have not\nyet been delivered to the window.\n.IP \\fB%d\\fR 5\nThe \\fIdetail\\fR or \\fIuser_data\\fR\nfield from the event. The \\fB%d\\fR is replaced by\na string identifying the detail. For \\fBEnter\\fR,\n\\fBLeave\\fR, \\fBFocusIn\\fR, and \\fBFocusOut\\fR events,\nthe string will be one of the following:\n.RS\n.DS\n.ta 6c\n\\fBNotifyAncestor\\fR\t\\fBNotifyNonlinearVirtual\\fR\n\\fBNotifyDetailNone\\fR\t\\fBNotifyPointer\\fR\n\\fBNotifyInferior\\fR\t\\fBNotifyPointerRoot\\fR\n\\fBNotifyNonlinear\\fR\t\\fBNotifyVirtual\\fR\n.DE\nFor \\fBConfigureRequest\\fR events, the string will be one of:\n.DS\n.ta 6c\n\\fBAbove\\fR\t\\fBOpposite\\fR\n\\fBBelow\\fR\t\\fBNone\\fR\n\\fBBottomIf\\fR\t\\fBTopIf\\fR\n.DE\nFor virtual events, the string will be whatever value is stored in the\n\\fIuser_data\\fR field when the event was created (typically with\n\\fBevent generate\\fR), or the empty string if the field is NULL.\nVirtual events corresponding to key sequence presses (see \\fBevent\nadd\\fR for details) set the \\fIuser_data\\fR to NULL.\nFor events other than these, the substituted string is undefined.\n.RE\n.IP \\fB%f\\fR 5\nThe \\fIfocus\\fR field from the event (\\fB0\\fR or \\fB1\\fR). Valid only\nfor \\fBEnter\\fR and \\fBLeave\\fR events. \\fB1\\fR if the receiving\nwindow is the focus window or a descendant of the focus window,\n\\fB0\\fR otherwise.\n.IP \\fB%h\\fR 5\nThe \\fIheight\\fR field from the event. Valid for the \\fBConfigure\\fR,\n\\fBConfigureRequest\\fR, \\fBCreate\\fR, \\fBResizeRequest\\fR, and\n\\fBExpose\\fR events.\nIndicates the new or requested height of the window.\n.IP \\fB%i\\fR 5\nThe \\fIwindow\\fR field from the event, represented as a hexadecimal\ninteger. Valid for all event types.\n.IP \\fB%k\\fR 5\nThe \\fIkeycode\\fR field from the event. Valid only for \\fBKey\\fR\nand \\fBKeyRelease\\fR events.\n.IP \\fB%m\\fR 5\nThe \\fImode\\fR field from the event. The substituted string is one of\n\\fBNotifyNormal\\fR, \\fBNotifyGrab\\fR, \\fBNotifyUngrab\\fR, or\n\\fBNotifyWhileGrabbed\\fR. Valid only for \\fBEnter\\fR,\n\\fBFocusIn\\fR, \\fBFocusOut\\fR, and \\fBLeave\\fR events.\n.IP \\fB%o\\fR 5\nThe \\fIoverride_redirect\\fR field from the event. Valid only for\n\\fBMap\\fR, \\fBReparent\\fR, and \\fBConfigure\\fR events.\n.IP \\fB%p\\fR 5\nThe \\fIplace\\fR field from the event, substituted as one of the\nstrings \\fBPlaceOnTop\\fR or \\fBPlaceOnBottom\\fR. Valid only\nfor \\fBCirculate\\fR and \\fBCirculateRequest\\fR events.\n.IP \\fB%s\\fR 5\nThe \\fIstate\\fR field from the event. For \\fBButton\\fR,\n\\fBButtonRelease\\fR, \\fBEnter\\fR, \\fBKey\\fR, \\fBKeyRelease\\fR,\n\\fBLeave\\fR, and \\fBMotion\\fR events, a decimal string\nis substituted. For \\fBVisibility\\fR, one of the strings\n\\fBVisibilityUnobscured\\fR, \\fBVisibilityPartiallyObscured\\fR,\nand \\fBVisibilityFullyObscured\\fR is substituted.\nFor \\fBProperty\\fR events, substituted with\neither the string \\fBNewValue\\fR (indicating that the property\nhas been created or modified) or \\fBDelete\\fR (indicating that\nthe property has been removed).\n.IP \\fB%t\\fR 5\nThe \\fItime\\fR field from the event.\nThis is the X server timestamp (typically the time since\nthe last server reset) in milliseconds, when the event occurred.\nValid for most events.\n.IP \\fB%w\\fR 5\nThe \\fIwidth\\fR field from the event.\nIndicates the new or requested width of the window.\nValid only for\n\\fBConfigure\\fR, \\fBConfigureRequest\\fR, \\fBCreate\\fR,\n\\fBResizeRequest\\fR, and \\fBExpose\\fR events.\n.IP \"\\fB%x\\fR, \\fB%y\\fR\" 5\nThe \\fIx\\fR and \\fIy\\fR fields from the event.\nFor \\fBButton\\fR, \\fBButtonRelease\\fR, \\fBMotion\\fR,\n\\fBKey\\fR, \\fBKeyRelease\\fR, and \\fBMouseWheel\\fR events,\n\\fB%x\\fR and \\fB%y\\fR indicate the position of the mouse pointer\nrelative to the receiving window.\nFor key events on the Macintosh these are the coordinates of the\nmouse at the moment when an X11 KeyEvent is sent to Tk, which could\nbe slightly later than the time of the physical press or release.\nFor \\fBEnter\\fR and \\fBLeave\\fR events, the position where the\nmouse pointer crossed the window, relative to the receiving window.\nFor \\fBConfigure\\fR and \\fBCreate\\fR requests, the \\fIx\\fR and \\fIy\\fR\ncoordinates of the window relative to its parent window.\n.IP \\fB%A\\fR 5\nSubstitutes the UNICODE character corresponding to the event, or\nthe empty string if the event does not correspond to a UNICODE character\n(e.g. the shift key was pressed). On X11, \\fBXmbLookupString\\fR (or\n\\fBXLookupString\\fR when input method support is turned off) does all\nthe work of translating from the event to a UNICODE character.\nOn X11, valid only for \\fBKey\\fR event. On Windows and macOS/aqua,\nvalid only for \\fBKey\\fR and \\fBKeyRelease\\fR events.\n.IP \\fB%B\\fR 5\nThe \\fIborder_width\\fR field from the event. Valid only for\n\\fBConfigure\\fR, \\fBConfigureRequest\\fR, and \\fBCreate\\fR events.\n.IP \\fB%D\\fR 5\nThis reports the \\fIdelta\\fR value of a \\fBMouseWheel\\fR event. The\n\\fIdelta\\fR value represents the rotation units the mouse wheel has\nbeen moved. The sign of the value represents the direction the mouse\nwheel was scrolled.\n.IP \\fB%E\\fR 5\nThe \\fIsend_event\\fR field from the event. Valid for all event types.\n\\fB0\\fR indicates that this is a\n.QW normal\nevent, \\fB1\\fR indicates that it is a\n.QW synthetic\nevent generated by \\fBSendEvent\\fR.\n.IP \\fB%K\\fR 5\nThe keysym corresponding to the event, substituted as a textual\nstring. Valid only for \\fBKey\\fR and \\fBKeyRelease\\fR events.\n.IP \\fB%M\\fR 5\nThe number of script-based binding patterns matched so far for the\nevent. Valid for all event types.\n.IP \\fB%N\\fR 5\nThe keysym corresponding to the event, substituted as a decimal\nnumber. Valid only for \\fBKey\\fR and \\fBKeyRelease\\fR events.\n.IP \\fB%P\\fR 5\nThe name of the property being updated or deleted (which\nmay be converted to an XAtom using \\fBwinfo atom\\fR.) Valid\nonly for \\fBProperty\\fR events.\n.IP \\fB%R\\fR 5\nThe \\fIroot\\fR window identifier from the event. Valid only for\nevents containing a \\fIroot\\fR field.\n.IP \\fB%S\\fR 5\nThe \\fIsubwindow\\fR window identifier from the event,\nformatted as a hexadecimal number.\nValid only for events containing a \\fIsubwindow\\fR field.\n.IP \\fB%T\\fR 5\nThe \\fItype\\fR field from the event. Valid for all event types.\n.IP \\fB%W\\fR 5\nThe path name of the window to which the event was reported (the\n\\fIwindow\\fR field from the event). Valid for all event types.\n.IP \"\\fB%X\\fR, \\fB%Y\\fR\" 5\nThe \\fIx_root\\fR and \\fIy_root\\fR fields from the event.\nIf a virtual-root window manager is being used then the substituted\nvalues are the corresponding x-coordinate and y-coordinate in the virtual root.\nValid only for\n\\fBButton\\fR, \\fBButtonRelease\\fR, \\fBEnter\\fR, \\fBKey\\fR,\n\\fBKeyRelease\\fR, \\fBLeave\\fR and \\fBMotion\\fR events.\nSame meaning as \\fB%x\\fR and \\fB%y\\fR, except relative to the (virtual) root\nwindow.\n.LP\nThe replacement string for a %-replacement is formatted as a proper\nTcl list element.\nThis means that spaces or special characters such as \\fB$\\fR and\n\\fB{\\fR may be preceded by backslashes.\nThis guarantees that the string will be passed through the Tcl\nparser when the binding script is evaluated.\nMost replacements are numbers or well-defined strings such\nas \\fBAbove\\fR; for these replacements no special formatting\nis ever necessary.\nThe most common case where reformatting occurs is for the \\fB%A\\fR\nsubstitution. For example, if \\fIscript\\fR is\n.CS\n\\fBinsert\\0%A\\fR\n.CE\nand the character typed is an open square bracket, then the script\nactually executed will be\n.CS\n\\fBinsert\\0\\e[\\fR\n.CE\nThis will cause the \\fBinsert\\fR to receive the original replacement\nstring (open square bracket) as its first argument.\nIf the extra backslash had not been added, Tcl would not have been\nable to parse the script correctly.\n.SH \"MULTIPLE MATCHES\"\n.PP\nIt is possible for several bindings to match a given X event.\nIf the bindings are associated with different \\fItag\\fR's,\nthen each of the bindings will be executed, in order.\nBy default, a binding for the widget will be executed first, followed\nby a class binding, a binding for its toplevel, and\nan \\fBall\\fR binding.\nThe \\fBbindtags\\fR command may be used to change this order for\na particular window or to associate additional binding tags with\nthe window.\n.PP\nThe \\fBcontinue\\fR and \\fBbreak\\fR commands may be used inside a\nbinding script to control the processing of matching scripts.\nIf \\fBcontinue\\fR is invoked within a binding script, then this\nbinding script, including all other\n.QW +\nappended scripts, is terminated but Tk will continue processing\nbinding scripts associated with other \\fItag\\fR's.\nIf the \\fBbreak\\fR command is invoked within a binding script,\nthen that script terminates and no other scripts will be invoked\nfor the event.\n.PP\nWithin a script called from the binding script, \\fBreturn\\fR\n\\fB\\-code ok\\fR may be used to continue processing (including\n.QW +\nappended scripts), or \\fBreturn\\fR \\fB\\-code break\\fR may be used to\nstop processing all other binding scripts.\n.PP\nIf more than one binding matches a particular event and they\nhave the same \\fItag\\fR, then the most specific binding\nis chosen and its script is evaluated.\nThe following tests are applied, in order, to determine which of\nseveral matching sequences is more specific:\n.RS\n.IP (a)\nan event pattern that specifies a specific button or key is more specific\nthan one that does not;\n.IP (b)\na sequence with the most highest-ordered patterns (in term of highest\nrepetition count) is more specific than a sequence with less\nhighest-ordered patterns;\n.IP (c)\nif the modifiers specified in one pattern are a subset of the\nmodifiers in another pattern, then the pattern with more modifiers\nis more specific;\n.IP (d)\na virtual event whose physical pattern matches the sequence is less\nspecific than the same physical pattern that is not associated with a\nvirtual event;\n.IP (e)\ngiven a sequence that matches two or more virtual events, one\nof the virtual events will be chosen, but the order is undefined.\n.RE\n.PP\nIf the matching sequences contain more than one event, then tests\n(c)\\-(e) are applied in order from the most recent event to the least recent\nevent in the sequences. If these tests fail to determine a winner, then the\nmost recently registered sequence is the winner.\n.PP\nIf there are two (or more) virtual events that are both triggered by the\nsame sequence, and both of those virtual events are bound to the same window\ntag, then only one of the virtual events will be triggered, and it will\nbe picked at random:\n.CS\nevent add <> \nevent add <> \nevent add <> \n\\fBbind\\fR Entry <> {puts Paste}\n\\fBbind\\fR Entry <> {puts Scroll}\n.CE\nIf the user types Control\\-y, the \\fB<>\\fR binding\nwill be invoked, but if the user presses button 2 then one of\neither the \\fB<>\\fR or the \\fB<>\\fR bindings will\nbe invoked, but exactly which one gets invoked is undefined.\n.PP\nIf an X event does not match any of the existing bindings, then the\nevent is ignored.\nAn unbound event is not considered to be an error.\n.SH \"MULTI-EVENT SEQUENCES AND IGNORED EVENTS\"\n.PP\nWhen a \\fIsequence\\fR specified in a \\fBbind\\fR command contains\nmore than one event pattern, then its script is executed whenever\nthe recent events (leading up to and including the current event)\nmatch the given sequence. This means, for example, that if button 1 is\nclicked repeatedly the sequence \\fB\\fR will match\neach button press but the first.\nIf extraneous events that would prevent a match occur in the middle\nof an event sequence then the extraneous events are\nignored unless they are \\fBKey\\fR or \\fBButton\\fR events.\nFor example, \\fB\\fR will match a sequence of\npresses of button 1, even though there will be \\fBButtonRelease\\fR\nevents (and possibly \\fBMotion\\fR events) between the\n\\fBButton\\fR events.\nFurthermore, a \\fBKey\\fR event may be preceded by any number\nof other \\fBKey\\fR events for modifier keys without the\nmodifier keys preventing a match.\nFor example, the event sequence \\fBaB\\fR will match a press of the\n\\fBa\\fR key, a release of the \\fBa\\fR key, a press of the \\fBShift\\fR\nkey, and a press of the \\fBb\\fR key: the press of \\fBShift\\fR is\nignored because it is a modifier key.\nFinally, if several \\fBMotion\\fR events occur in a row, only\nthe last one is used for purposes of matching binding sequences.\n.SH \"ERRORS\"\n.PP\nIf an error occurs in executing the script for a binding then the\n\\fBbgerror\\fR mechanism is used to report the error.\nThe \\fBbgerror\\fR command will be executed at global level\n(outside the context of any Tcl procedure).\n.SH \"EXAMPLES\"\n.PP\nArrange for a string describing the motion of the mouse to be printed\nout when the mouse is double-clicked:\n.CS\n\\fBbind\\fR . {\n puts \"hi from (%x,%y)\"\n}\n.CE\n.PP\nA little GUI that displays what the keysym name of the last key\npressed is:\n.CS\nset keysym \"Press any key\"\npack [label .l -textvariable keysym -padx 2m -pady 1m]\n\\fBbind\\fR . {\n set keysym \"You pressed %K\"\n}\n.CE\n.SH \"SEE ALSO\"\nbgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n)\n.SH KEYWORDS\nbinding, event\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/bindtags.n", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH bindtags n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nbindtags \\- Determine which bindings apply to a window, and order of evaluation\n.SH SYNOPSIS\n\\fBbindtags \\fIwindow \\fR?\\fItagList\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nWhen a binding is created with the \\fBbind\\fR command, it is\nassociated either with a particular window such as \\fB.a.b.c\\fR,\na class name such as \\fBButton\\fR, the keyword \\fBall\\fR, or any\nother string.\nAll of these forms are called \\fIbinding tags\\fR.\nEach window contains a list of binding tags that determine how\nevents are processed for the window.\nWhen an event occurs in a window, it is applied to each of the\nwindow's tags in order: for each tag, the most specific binding\nthat matches the given tag and event is executed.\nSee the \\fBbind\\fR command for more information on the matching\nprocess.\n.PP\nBy default, each window has four binding tags consisting of the\nname of the window, the window's class name, the name of the window's\nnearest toplevel ancestor, and \\fBall\\fR, in that order.\nToplevel windows have only three tags by default, since the toplevel\nname is the same as that of the window.\nThe \\fBbindtags\\fR command allows the binding tags for a window to be\nread and modified.\n.PP\nIf \\fBbindtags\\fR is invoked with only one argument, then the\ncurrent set of binding tags for \\fIwindow\\fR is returned as a list.\nIf the \\fItagList\\fR argument is specified to \\fBbindtags\\fR,\nthen it must be a proper list; the tags for \\fIwindow\\fR are changed\nto the elements of the list.\nThe elements of \\fItagList\\fR may be arbitrary strings; however,\nany tag starting with a dot is treated as the name of a window; if\nno window by that name exists at the time an event is processed,\nthen the tag is ignored for that event.\nThe order of the elements in \\fItagList\\fR determines the order in\nwhich binding scripts are executed in response to events.\nFor example, the command\n.CS\n\\fBbindtags .b {all . Button .b}\\fR\n.CE\nreverses the order in which binding scripts will be evaluated for\na button named \\fB.b\\fR so that \\fBall\\fR bindings are invoked\nfirst, following by bindings for \\fB.b\\fR's toplevel\n.PQ . \"\" ,\nfollowed by class bindings, followed by bindings for \\fB.b\\fR.\nIf \\fItagList\\fR is an empty list then the binding tags for \\fIwindow\\fR\nare returned to the default state described above.\n.PP\nThe \\fBbindtags\\fR command may be used to introduce arbitrary\nadditional binding tags for a window, or to remove standard tags.\nFor example, the command\n.CS\n\\fBbindtags .b {.b TrickyButton . all}\\fR\n.CE\nreplaces the \\fBButton\\fR tag for \\fB.b\\fR with \\fBTrickyButton\\fR.\nThis means that the default widget bindings for buttons, which are\nassociated with the \\fBButton\\fR tag, will no longer apply to \\fB.b\\fR,\nbut any bindings associated with \\fBTrickyButton\\fR (perhaps some\nnew button behavior) will apply.\n.SH EXAMPLE\n.PP\nIf you have a set of nested \\fBframe\\fR widgets and you want events\nsent to a \\fBbutton\\fR widget to also be delivered to all the widgets\nup to the current \\fBtoplevel\\fR (in contrast to Tk's default\nbehavior, where events are not delivered to those intermediate\nwindows) to make it easier to have accelerators that are only active\nfor part of a window, you could use a helper procedure like this to\nhelp set things up:\n.CS\nproc setupBindtagsForTreeDelivery {widget} {\n set tags [list $widget [winfo class $widget]]\n set w $widget\n set t [winfo toplevel $w]\n while {$w ne $t} {\n set w [winfo parent $w]\n lappend tags $w\n }\n lappend tags all\n \\fBbindtags\\fR $widget $tags\n}\n.CE\n.SH \"SEE ALSO\"\nbind(n)\n.SH KEYWORDS\nbinding, event, tag\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/bitmap.n", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH bitmap n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nbitmap \\- Images that display two colors\n.SH SYNOPSIS\n.nf\n\\fBimage create bitmap \\fR?\\fIname\\fR? ?\\fIoptions\\fR?\n\n\\fIimageName \\fBcget\\fI option\\fR\n\\fIimageName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nA bitmap is an image whose pixels can display either of two colors\nor be transparent.\nA bitmap image is defined by four things: a background color,\na foreground color, and two bitmaps, called the \\fIsource\\fR\nand the \\fImask\\fR.\nEach of the bitmaps specifies 0/1 values for a rectangular\narray of pixels, and the two bitmaps must have the same\ndimensions.\nFor pixels where the mask is zero, the image displays nothing,\nproducing a transparent effect.\nFor other pixels, the image displays the foreground color if\nthe source data is one and the background color if the source\ndata is zero.\n.SH \"CREATING BITMAPS\"\n.PP\nLike all images, bitmaps are created using the \\fBimage create\\fR\ncommand.\nBitmaps support the following \\fIoptions\\fR:\n.\\\" OPTION: -background\n.TP\n\\fB\\-background \\fIcolor\\fR\n.\nSpecifies a background color for the image in any of the standard\nways accepted by Tk. If this option is set to an empty string\nthen the background pixels will be transparent. This effect\nis achieved by using the source bitmap as the mask bitmap, ignoring\nany \\fB\\-maskdata\\fR or \\fB\\-maskfile\\fR options.\n.\\\" OPTION: -data\n.TP\n\\fB\\-data \\fIstring\\fR\n.\nSpecifies the contents of the source bitmap as a string.\nThe string must adhere to X11 bitmap format (e.g., as generated\nby the \\fBbitmap\\fR program).\nIf both the \\fB\\-data\\fR and \\fB\\-file\\fR options are specified,\nthe \\fB\\-data\\fR option takes precedence.\n.\\\" OPTION: -file\n.TP\n\\fB\\-file \\fIname\\fR\n.\n\\fIname\\fR gives the name of a file whose contents define the\nsource bitmap.\nThe file must adhere to X11 bitmap format (e.g., as generated\nby the \\fBbitmap\\fR program).\n.\\\" OPTION: -foreground\n.TP\n\\fB\\-foreground \\fIcolor\\fR\n.\nSpecifies a foreground color for the image in any of the standard\nways accepted by Tk.\n.\\\" OPTION: -maskdata\n.TP\n\\fB\\-maskdata \\fIstring\\fR\n.\nSpecifies the contents of the mask as a string.\nThe string must adhere to X11 bitmap format (e.g., as generated\nby the \\fBbitmap\\fR program).\nIf both the \\fB\\-maskdata\\fR and \\fB\\-maskfile\\fR options are specified,\nthe \\fB\\-maskdata\\fR option takes precedence.\n.\\\" OPTION: -maskfile\n.TP\n\\fB\\-maskfile \\fIname\\fR\n.\n\\fIname\\fR gives the name of a file whose contents define the\nmask.\nThe file must adhere to X11 bitmap format (e.g., as generated\nby the \\fBbitmap\\fR program).\n.SH \"IMAGE COMMAND\"\n.PP\nWhen a bitmap image is created, Tk also creates a new command\nwhose name is the same as the image.\nThis command may be used to invoke various operations\non the image.\nIt has the following general form:\n.CS\n\\fIimageName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for bitmap images:\n.\\\" METHOD: cget\n.TP\n\\fIimageName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the\n\\fBimage create\\fR \\fBbitmap\\fR command.\n.\\\" METHOD: configure\n.TP\n\\fIimageName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options for the image.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIimageName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the\n\\fBimage create\\fR \\fBbitmap\\fR command.\n.SH KEYWORDS\nbitmap, image\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/busy.n", "content": "'\\\"\n'\\\" Copyright (c) 1993-1998 Lucent Technologies, Inc.\n'\\\" Copyright (c) 2008 Jos Decoster\n'\\\"\n'\\\" Permission to use, copy, modify, and distribute this software and its\n'\\\" documentation for any purpose and without fee is hereby granted, provided\n'\\\" that the above copyright notice appear in all copies and that both that\n'\\\" the copyright notice and warranty disclaimer appear in supporting\n'\\\" documentation, and that the names of Lucent Technologies any of their\n'\\\" entities not be used in advertising or publicity pertaining to\n'\\\" distribution of the software without specific, written prior permission.\n'\\\"\n'\\\" Lucent Technologies disclaims all warranties with regard to this software,\n'\\\" including all implied warranties of merchantability and fitness. In no\n'\\\" event shall Lucent Technologies be liable for any special, indirect or\n'\\\" consequential damages or any damages whatsoever resulting from loss of\n'\\\" use, data or profits, whether in an action of contract, negligence or\n'\\\" other tortuous action, arising out of or in connection with the use or\n'\\\" performance of this software.\n'\\\"\n'\\\" BLT::busy command created by George Howlett.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH busy n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nbusy \\- Make Tk widgets busy, temporarily blocking user interactions\n.SH SYNOPSIS\n.nf\n\\fBtk busy\\fI window \\fR?\\fIoptions\\fR?\n\\fBtk busy busywindow \\fIwindow\\fR\n\\fBtk busy hold\\fI window \\fR?\\fIoptions\\fR?\n\\fBtk busy configure \\fIwindow\\fR ?\\fIoption value\\fR?...\n\\fBtk busy forget\\fI window \\fR?\\fIwindow \\fR?...\n\\fBtk busy current\\fR ?\\fIpattern\\fR?\n\\fBtk busy status \\fIwindow\\fR\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBtk busy\\fR command provides a simple means to block mouse pointer events\nfrom Tk widgets, while overriding the widget's cursor with a configurable busy\ncursor. Note this command does not prevent keyboard events from being sent to\nthe widgets made busy.\n.SH INTRODUCTION\n.PP\nThere are many times in applications where you want to temporarily restrict\nwhat actions the user can take. For example, an application could have a\n.QW Run\nbutton that when pressed causes some processing to occur. However, while the\napplication is busy processing, you probably don't want the user to be\nable to click the\n.QW Run\nbutton again. You may also want restrict the user from other tasks such as\nclicking a\n.QW Print\nbutton.\n.PP\nThe \\fBtk busy\\fR command lets you make Tk widgets busy. This means that user\ninteractions such as button clicks, moving the mouse, typing at the keyboard,\netc.\\0are ignored by the widget. You can set a special cursor (like a watch)\nthat overrides the widget's normal cursor, providing feedback that the\napplication (widget) is temporarily busy.\n.PP\nWhen a widget is made busy, the widget and all of its descendants will ignore\npointer events. It's easy to make an entire panel of widgets busy. You can\nsimply make the toplevel widget (such as\n.QW . )\nbusy. This is easier and far much more efficient than recursively traversing\nthe widget hierarchy, disabling each widget and re-configuring its cursor.\n.PP\nOften, the \\fBtk busy\\fR command can be used instead of Tk's \\fBgrab\\fR\ncommand. Unlike \\fBgrab\\fR which restricts all user interactions to one\nwidget, with the \\fBtk busy\\fR command you can have more than one widget\nactive (for example, a\n.QW Cancel\ndialog and a\n.QW Help\nbutton).\n.SS EXAMPLE\n.PP\nYou can make several widgets busy by simply making its ancestor widget busy\nusing the \\fBhold\\fR operation.\n.PP\n.CS\nframe .top\nbutton .top.button; canvas .top.canvas\npack .top.button .top.canvas\npack .top\n# . . .\n\\fBtk busy\\fR hold .top\nupdate\n.CE\n.PP\nAll the widgets within \\fB.top\\fR (including \\fB.top\\fR) are now busy. Using\n\\fBupdate\\fR insures that \\fBtk busy\\fR command will take effect before any\nother user events can occur.\n.PP\nWhen the application is no longer busy processing, you can allow user\ninteractions again and free any resources it allocated by the \\fBforget\\fR\noperation.\n.PP\n.CS\n\\fBtk busy\\fR forget .top\n.CE\n.PP\nThe busy window has a configurable cursor. You can change the busy cursor\nusing the \\fBconfigure\\fR operation.\n.PP\n.CS\n\\fBtk busy\\fR configure .top -cursor \"watch\"\n.CE\n.PP\nDestroying the widget will also clean up any resources allocated by the \\fBtk\nbusy\\fR command.\n.PP\n.SH OPERATIONS\n.PP\nThe following operations are available for the \\fBtk busy\\fR command:\n.TP\n\\fBtk busy \\fIwindow\\fR ?\\fIoption value\\fR?...\n.\nShortcut for \\fBtk busy hold\\fR command.\n.\\\" METHOD: busywindow\n.TP\n\\fBtk busy busywindow \\fIwindow\\fR\n.\nReturns the pathname of the busy window (i.e. the transparent window\nshielding the window appearing busy) created by the \\fBtk busy hold\\fR\ncommand for \\fIwindow\\fR, or the empty string if \\fIwindow\\fR is not busy.\n.\\\" METHOD: cget\n.TP\n\\fBtk busy cget \\fIwindow option\\fR\n.\nQueries the \\fBtk busy\\fR command configuration options for \\fIwindow\\fR.\n\\fIWindow\\fR must be the path name of a widget previously made busy by the\n\\fBhold\\fR operation. The command returns the present value of the specified\n\\fIoption\\fR. \\fIOption\\fR may have any of the values accepted by the\n\\fBhold\\fR operation.\n.\\\" METHOD: configure\n.TP\n\\fBtk busy configure \\fIwindow\\fR ?\\fIoption value\\fR?...\n.\nQueries or modifies the \\fBtk busy\\fR command configuration options for\n\\fIwindow\\fR. \\fIWindow\\fR must be the path name of a widget previously made\nbusy by the \\fBhold\\fR operation. If no options are specified, a list\ndescribing all of the available options for \\fIwindow\\fR (see\n\\fBTk_ConfigureInfo\\fR for information on the format of this list) is\nreturned. If \\fIoption\\fR is specified with no \\fIvalue\\fR, then the command\nreturns a list describing the one named option (this list will be identical to\nthe corresponding sublist of the value returned if no \\fIoption\\fR is\nspecified). If one or more \\fIoption\\-value\\fR pairs are specified, then the\ncommand modifies the given widget option(s) to have the given value(s); in\nthis case the command returns the empty string. \\fIOption\\fR may have any of\nthe values accepted by the \\fBhold\\fR operation.\n.RS\n.PP\nPlease note that the option database is referenced through \\fIwindow\\fR. For\nexample, if the widget \\fB.frame\\fR is to be made busy, the busy cursor can be\nspecified for it by either \\fBoption\\fR command:\n.PP\n.CS\noption add *frame.busyCursor gumby\noption add *Frame.BusyCursor gumby\n.CE\n.RE\n.\\\" METHOD: current\n.TP\n\\fBtk busy current \\fR?\\fIpattern\\fR?\n.\nReturns the pathnames of all widgets that are currently busy. If a\n\\fIpattern\\fR is given, only the path names of busy widgets matching\n\\fIpattern\\fR are returned.\n.\\\" METHOD: forget\n.TP\n\\fBtk busy forget \\fIwindow\\fR ?\\fIwindow\\fR?...\n.\nReleases resources allocated by the \\fBtk busy\\fR command for \\fIwindow\\fR,\nincluding the transparent window. User events will again be received by\n\\fIwindow\\fR. Resources are also released when \\fIwindow\\fR is destroyed.\n\\fIWindow\\fR must be the name of a widget specified in the \\fBhold\\fR\noperation, otherwise an error is reported.\n.\\\" METHOD: hold\n.TP\n\\fBtk busy hold \\fIwindow\\fR ?\\fIoption value\\fR?...\n.\nMakes the specified \\fIwindow\\fR (and its descendants in the Tk window\nhierarchy) appear busy. \\fIWindow\\fR must be a valid path name of a Tk widget.\nA transparent window is put in front of the specified window. This transparent\nwindow is mapped the next time idle tasks are processed, and the specified\nwindow and its descendants will be blocked from user interactions. Normally\n\\fBupdate\\fR should be called immediately afterward to insure that the hold\noperation is in effect before the application starts its processing. The\ncommand returns the pathname of the busy window that was created (i.e. the\ntransparent window shielding the window appearing busy). The following\nconfiguration options are valid:\n.RS\n.\\\" OPTION: -cursor\n.TP\n\\fB\\-cursor \\fIcursorName\\fR\n.\nSpecifies the cursor to be displayed when the widget is made busy.\n\\fICursorName\\fR can be in any form accepted by \\fBTk_GetCursor\\fR. The\ndefault cursor is \\fBwait\\fR on Windows and \\fBwatch\\fR on other platforms.\n.RE\n.\\\" METHOD: status\n.TP\n\\fBtk busy status \\fIwindow\\fR\n.\nReturns the status of a widget \\fIwindow\\fR. If \\fIwindow\\fR presently can not\nreceive user interactions, \\fB1\\fR is returned, otherwise \\fB0\\fR.\n.SH \"EVENT HANDLING\"\n.SS BINDINGS\n.PP\nThe event blocking feature is implemented by creating and mapping a\ntransparent window that completely covers the widget. When the busy window is\nmapped, it invisibly shields the widget and its hierarchy from all events that\nmay be sent. Like Tk widgets, busy windows have widget names in the Tk window\nhierarchy. This means that you can use the \\fBbind\\fR command to handle\nevents in the busy window:\n.PP\n.CS\n\\fBtk busy\\fR hold .frame.canvas\nbind [\\fBtk busy\\fR busywindow .frame.canvas] { ... }\n.CE\n.PP\nor\n.CS\nset busyWin [\\fBtk busy\\fR hold .frame.canvas]\nbind $busyWin { ... }\n.CE\n.SS \"ENTER/LEAVE EVENTS\"\n.PP\nMapping and unmapping busy windows generates Enter/Leave events for all\nwidgets they cover. Please note this if you are tracking Enter/Leave events in\nwidgets.\n.SS \"KEYBOARD EVENTS\"\n.PP\nWhen a widget is made busy, the widget is prevented from gaining the keyboard\nfocus by a user clicking on it by the busy window. But if the widget already had\nfocus, it still may receive keyboard events. The widget can also still receive\nfocus through keyboard traversal. To prevent this, you must move\nfocus to another window and make sure the focus can not go back to the widgets\nmade busy (e.g. but restricting focus to a cancel button).\n.PP\n.CS\npack [frame .frame]\npack [text .frame.text]\n\\fBtk busy\\fR hold .frame\npack [button .cancel -text \"Cancel\" -command exit]\nfocus .cancel\nbind .cancel {break}\nbind .cancel {break}\nupdate\n.CE\n.PP\nThe above example moves the focus from .frame immediately after invoking the\n\\fBhold\\fR so that no keyboard events will be sent to \\fB.frame\\fR or any of\nits descendants. It also makes sure it's not possible to leave button\n\\fB.cancel\\fR using the keyboard.\n.SH PORTABILITY\n.PP\nNote that the \\fBtk busy\\fR command does not currently have any effect on macOS\nwhen Tk is built using Aqua support.\n.SH \"SEE ALSO\"\ngrab(n)\n.SH KEYWORDS\nbusy, keyboard events, pointer events, window\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/button.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH button n 4.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nbutton \\- Create and manipulate 'button' action widgets\n.SH SYNOPSIS\n\\fBbutton\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-activebackground\t\\-font\t\\-relief\n\\-activeforeground\t\\-foreground\t\\-repeatdelay\n\\-anchor\t\\-highlightbackground\t\\-repeatinterval\n\\-background\t\\-highlightcolor\t\\-takefocus\n\\-bitmap\t\\-highlightthickness\t\\-text\n\\-borderwidth\t\\-image\t\\-textvariable\n\\-compound\t\\-justify\t\\-underline\n\\-cursor\t\\-padx\t\\-wraplength\n\\-disabledforeground\t\\-pady\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-command command Command\nSpecifies a Tcl command to associate with the button. This command\nis typically invoked when mouse button 1 is released over the button\nwindow.\n.OP \\-default default Default\nSpecifies one of three states for the default ring: \\fBnormal\\fR,\n\\fBactive\\fR, or \\fBdisabled\\fR. In active state, the button is drawn\nwith the platform specific appearance for a default button. In normal\nstate, the button is drawn with the platform specific appearance for a\nnon-default button, leaving enough space to draw the default button\nappearance. The normal and active states will result in buttons of\nthe same size. In disabled state, the button is drawn with the\nnon-default button appearance without leaving space for the default\nappearance. The disabled state may result in a smaller button than\nthe active state.\n.OP \\-height height Height\nSpecifies a desired height for the button.\nIf an image or bitmap is being displayed in the button then the value is in\nscreen units (i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR);\nfor text it is in lines of text.\nIf this option is not specified, the button's desired height is computed\nfrom the size of the image or bitmap or text being displayed in it.\n.OP \\-overrelief overRelief OverRelief\nSpecifies an alternative relief for the button, to be used when the\nmouse cursor is over the widget. This option can be used to make\ntoolbar buttons, by configuring \\fB\\-relief flat \\-overrelief\nraised\\fR. If the value of this option is the empty string, then no\nalternative relief is used when the mouse cursor is over the button.\nThe empty string is the default value.\n.OP \\-state state State\nSpecifies one of three states for the button: \\fBnormal\\fR, \\fBactive\\fR,\nor \\fBdisabled\\fR. In normal state the button is displayed using the\n\\fB\\-foreground\\fR and \\fB\\-background\\fR options. The active state is\ntypically used when the pointer is over the button. In active state\nthe button is displayed using the \\fB\\-activeforeground\\fR and\n\\fB\\-activebackground\\fR options. Disabled state means that the button\nshould be insensitive: the default bindings will refuse to activate\nthe widget and will ignore mouse button presses.\nIn this state the \\fB\\-disabledforeground\\fR and\n\\fB\\-background\\fR options determine how the button is displayed.\n.OP \\-width width Width\nSpecifies a desired width for the button.\nIf an image or bitmap is being displayed in the button then the value is in\nscreen units (i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR).\nFor a text button (no image or with \\fB\\-compound none\\fR) then the width\nspecifies how much space in characters to allocate for the text label.\nIf the width is negative then this specifies a minimum width.\nIf this option is not specified, the button's desired width is computed\nfrom the size of the image or bitmap or text being displayed in it.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBbutton\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a button widget.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the button such as its colors, font,\ntext, and initial relief. The \\fBbutton\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nA button is a widget that displays a textual string, bitmap or image.\nIf text is displayed, it must all be in a single font, but it\ncan occupy multiple lines on the screen (if it contains newlines\nor if wrapping occurs because of the \\fB\\-wraplength\\fR option) and\none of the characters may optionally be underlined using the\n\\fB\\-underline\\fR option.\nIt can display itself in either of three different ways, according\nto\nthe \\fB\\-state\\fR option;\nit can be made to appear raised, sunken, or flat;\nand it can be made to flash. When a user invokes the\nbutton (by pressing mouse button 1 with the cursor over the\nbutton), then the Tcl command specified in the \\fB\\-command\\fR\noption is invoked.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBbutton\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for button widgets:\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBbutton\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBbutton\\fR\ncommand.\n.\\\" METHOD: flash\n.TP\n\\fIpathName \\fBflash\\fR\n.\nFlash the button. This is accomplished by redisplaying the button\nseveral times, alternating between the configured activebackground\nand background colors. At the end of the flash the button is left\nin the same normal/active state as when the command was invoked.\nThis command is ignored if the button's state is \\fBdisabled\\fR.\n.\\\" METHOD: invoke\n.TP\n\\fIpathName \\fBinvoke\\fR\n.\nInvoke the Tcl command associated with the button, if there is one.\nThe return value is the return value from the Tcl command, or an\nempty string if there is no command associated with the button.\nThis command is ignored if the button's state is \\fBdisabled\\fR.\n.SH \"DEFAULT BINDINGS\"\n.PP\nTk automatically creates class bindings for buttons that give them\ndefault behavior:\n.IP [1]\nA button activates whenever the mouse passes over it and deactivates\nwhenever the mouse leaves the button.\nUnder Windows, this binding is only active when mouse button 1 has\nbeen pressed over the button.\n.IP [2]\nA button's relief is changed to sunken whenever mouse button 1 is\npressed over the button, and the relief is restored to its original\nvalue when button 1 is later released.\n.IP [3]\nIf mouse button 1 is pressed over a button and later released over\nthe button, the button is invoked. However, if the mouse is not\nover the button when button 1 is released, then no invocation occurs.\n.IP [4]\nWhen a button has the input focus, the space key causes the button\nto be invoked.\n.PP\nIf the button's state is \\fBdisabled\\fR then none of the above\nactions occur: the button is completely non-responsive.\n.PP\nThe behavior of buttons can be changed by defining new bindings for\nindividual widgets or by redefining the class bindings.\n.SH \"PLATFORM NOTES\"\n.PP\nOn Aqua/macOS, some configuration options are ignored for the purpose of\ndrawing of the widget because they would otherwise conflict with platform\nguidelines. The \\fBconfigure\\fR and \\fBcget\\fR subcommands can still\nmanipulate the values, but do not cause any variation to the look of the\nwidget. The options affected notably include \\fB\\-background\\fR and\n\\fB\\-relief\\fR.\n.SH EXAMPLES\n.PP\nThis is the classic Tk\n.QW \"Hello, World!\"\ndemonstration:\n.PP\n.CS\n\\fBbutton\\fR .b -text \"Hello, World!\" -command exit\npack .b\n.CE\n.PP\nThis example demonstrates how to handle button accelerators:\n.PP\n.CS\n\\fBbutton\\fR .b1 -text Hello -underline 0\n\\fBbutton\\fR .b2 -text World -underline 0\nbind . {.b1 flash; .b1 invoke}\nbind . {.b2 flash; .b2 invoke}\npack .b1 .b2\n.CE\n.SH \"SEE ALSO\"\nttk::button(n)\n.SH KEYWORDS\nbutton, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/canvas.n", "content": "'\\\"\n'\\\" Copyright (c) 1992-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\" Copyright (c) 1997-1999 Scriptics Corporation.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH canvas n 8.3 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ncanvas \\- Create and manipulate 'canvas' hypergraphics drawing surface widgets\n.SH SYNOPSIS\n\\fBcanvas\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-background\t\\-borderwidth\t\\-cursor\n\\-highlightbackground\t\\-highlightcolor\t\\-highlightthickness\n\\-insertbackground\t\\-insertborderwidth\t\\-insertofftime\n\\-insertontime\t\\-insertwidth\t\\-relief\n\\-selectbackground\t\\-selectborderwidth\t\\-selectforeground\n\\-takefocus\t\\-xscrollcommand\t\\-yscrollcommand\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-closeenough closeEnough CloseEnough\nSpecifies a floating-point value indicating how close the mouse cursor\nmust be to an item before it is considered to be\n.QW inside\nthe item. Defaults to 1.0.\n.OP \\-confine confine Confine\nSpecifies a boolean value that indicates whether or not it should be\nallowable to set the canvas's view outside the region defined by the\n\\fBscrollRegion\\fR argument.\nDefaults to true, which means that the view will\nbe constrained within the scroll region.\n.OP \\-height height Height\nSpecifies a desired window height that the canvas widget should request from\nits geometry manager. The value may be specified in any\nof the forms described in the \\fBCOORDINATES\\fR section below.\n.OP \\-scrollregion scrollRegion ScrollRegion\nSpecifies a list with four coordinates describing the left, top, right, and\nbottom coordinates of a rectangular region.\nThis region is used for scrolling purposes and is considered to be\nthe boundary of the information in the canvas.\nEach of the coordinates may be specified\nin any of the forms given in the \\fBCOORDINATES\\fR section below.\n.OP \\-state state State\nModifies the default state of the canvas where \\fIstate\\fR may be set to\none of: \\fBnormal\\fR, \\fBdisabled\\fR, or \\fBhidden\\fR. Individual canvas\nobjects all have their own state option which may override the default\nstate. Many options can take separate specifications such that the\nappearance of the item can be different in different situations. The\noptions that start with \\fBactive\\fR control the appearance when the mouse\npointer is over it, while the option starting with \\fBdisabled\\fR controls\nthe appearance when the state is disabled. Canvas items which are\n\\fBdisabled\\fR will not react to canvas bindings.\n.OP \\-width width width\nSpecifies a desired window width that the canvas widget should request from\nits geometry manager. The value may be specified in any\nof the forms described in the \\fBCOORDINATES\\fR section below.\n.OP \\-xscrollincrement xScrollIncrement ScrollIncrement\nSpecifies an increment for horizontal scrolling, in any of the usual forms\npermitted for screen distances. If the value of this option is greater\nthan zero, the horizontal view in the window will be constrained so that\nthe canvas x coordinate at the left edge of the window is always an even\nmultiple of \\fBxScrollIncrement\\fR; furthermore, the units for scrolling\n(e.g., the change in view when the left and right arrows of a scrollbar\nare selected) will also be \\fBxScrollIncrement\\fR. If the value of\nthis option is negative or zero, then horizontal scrolling\nis unconstrained.\n.OP \\-yscrollincrement yScrollIncrement ScrollIncrement\nSpecifies an increment for vertical scrolling, in any of the usual forms\npermitted for screen distances. If the value of this option is greater\nthan zero, the vertical view in the window will be constrained so that\nthe canvas y coordinate at the top edge of the window is always an even\nmultiple of \\fByScrollIncrement\\fR; furthermore, the units for scrolling\n(e.g., the change in view when the top and bottom arrows of a scrollbar\nare selected) will also be \\fByScrollIncrement\\fR. If the value of\nthis option is negative or zero, then vertical scrolling\nis unconstrained.\n.BE\n.SH INTRODUCTION\n.PP\nThe \\fBcanvas\\fR command creates a new window (given\nby the \\fIpathName\\fR argument) and makes it into a canvas widget.\nAdditional options, described above, may be specified on the\ncommand line or in the option database\nto configure aspects of the canvas such as its colors and 3-D relief.\nThe \\fBcanvas\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nCanvas widgets implement structured graphics.\nA canvas displays any number of \\fIitems\\fR, which may be things like\nrectangles, circles, lines, and text.\nItems may be manipulated (e.g. moved or re-colored) and commands may\nbe associated with items in much the same way that the \\fBbind\\fR\ncommand allows commands to be bound to widgets. For example,\na particular command may be associated with the event\nso that the command is invoked whenever button 1 is pressed with\nthe mouse cursor over an item.\nThis means that items in a canvas can have behaviors defined by\nthe Tcl scripts bound to them.\n.SH \"DISPLAY LIST\"\n.PP\nThe items in a canvas are ordered for purposes of display,\nwith the first item in the display list being displayed\nfirst, followed by the next item in the list, and so on.\nItems later in the display list obscure those that are\nearlier in the display list and are sometimes referred to as being\n.QW \"on top\"\nof earlier items.\nWhen a new item is created it is placed at the end of the\ndisplay list, on top of everything else.\nWidget commands may be used to re-arrange the order of the\ndisplay list.\n.PP\nWindow items are an exception to the above rules. The underlying\nwindow systems require them always to be drawn on top of other items.\nIn addition, the stacking order of window items\nis not affected by any of the canvas widget commands; you must use\nthe Tk \\fBraise\\fR command and \\fBlower\\fR command instead.\n.SH \"ITEM IDS AND TAGS\"\n.PP\nItems in a canvas widget may be named in either of two ways:\nby id or by tag.\nEach item has a unique identifying number, which is assigned to\nthat item when it is created. The id of an item never changes\nand id numbers are never re-used within the lifetime of a\ncanvas widget.\n.PP\nEach item may also have any number of \\fItags\\fR associated\nwith it. A tag is just a string of characters, and it may\ntake any form except that of an integer.\nFor example,\n.QW x123\nis OK but\n.QW 123\nis not.\nThe same tag may be associated with many different items.\nThis is commonly done to group items in various interesting\nways; for example, all selected items might be given the tag\n.QW selected .\n.PP\nThe tag \\fBall\\fR is implicitly associated with every item\nin the canvas; it may be used to invoke operations on\nall the items in the canvas.\n.PP\nThe tag \\fBcurrent\\fR is managed automatically by Tk;\nit applies to the \\fIcurrent item\\fR, which is the\ntopmost item whose drawn area covers the position of\nthe mouse cursor (different item types interpret this in varying ways; see the\nindividual item type documentation for details).\nIf the mouse is not in the canvas widget or is not over\nan item, then no item has the \\fBcurrent\\fR tag.\n.PP\nWhen specifying items in canvas widget commands, if the\nspecifier is an integer then it is assumed to refer to\nthe single item with that id.\nIf the specifier is not an integer, then it is assumed to\nrefer to all of the items in the canvas that have a tag\nmatching the specifier.\nThe symbol \\fItagOrId\\fR is used below to indicate that\nan argument specifies either an id that selects a single\nitem or a tag that selects zero or more items.\n.PP\n\\fItagOrId\\fR may contain a logical expressions of\ntags by using operators:\n.QW \\fB&&\\fR ,\n.QW \\fB||\\fR ,\n.QW \\fB^\\fR ,\n.QW \\fB!\\fR ,\nand parenthesized subexpressions. For example:\n.CS\n .c find withtag {(a&&!b)||(!a&&b)}\n.CE\nor equivalently:\n.CS\n .c find withtag {a^b}\n.CE\nwill find only those items with either\n.QW a\nor\n.QW b\ntags, but not both.\n.PP\nSome widget commands only operate on a single item at a\ntime; if \\fItagOrId\\fR is specified in a way that\nnames multiple items, then the normal behavior is for\nthe command to use the first (lowest) of these items in\nthe display list that is suitable for the command.\nExceptions are noted in the widget command descriptions\nbelow.\n.SH \"COORDINATES\"\n.PP\nAll coordinates related to canvases are stored as floating-point\nnumbers.\nCoordinates and distances are specified in screen units,\nwhich are floating-point numbers optionally followed\nby one of several letters.\nIf no letter is supplied then the distance is in pixels.\nIf the letter is \\fBm\\fR then the distance is in millimeters on\nthe screen; if it is \\fBc\\fR then the distance is in centimeters;\n\\fBi\\fR means inches, and \\fBp\\fR means printers points (1/72 inch).\nLarger y-coordinates refer to points lower on the screen; larger\nx-coordinates refer to points farther to the right.\nCoordinates can be specified either as an even number of parameters,\nor as a single list parameter containing an even number of x and y\ncoordinate values.\n.SS TRANSFORMATIONS\n.PP\nNormally the origin of the canvas coordinate system is at the\nupper-left corner of the window containing the canvas.\nIt is possible to adjust the origin of the canvas\ncoordinate system relative to the origin of the window using the\n\\fBxview\\fR and \\fByview\\fR widget commands; this is typically used\nfor scrolling.\nCanvases do not support scaling or rotation of the canvas coordinate\nsystem relative to the window coordinate system.\n.PP\nIndividual items may be moved, scaled\n.VS \"9.0, TIP164\"\nor rotated\n.VE \"9.0, TIP164\"\nusing widget commands\ndescribed below.\n.PP\nNote that the default origin of the canvas's visible area is\ncoincident with the origin for the whole window as that makes bindings\nusing the mouse position easier to work with; you only need to use the\n\\fBcanvasx\\fR and \\fBcanvasy\\fR widget commands if you adjust the\norigin of the visible area. However, this also means that any focus\nring (as controlled by the \\fB\\-highlightthickness\\fR option) and\nwindow border (as controlled by the \\fB\\-borderwidth\\fR option) must\nbe taken into account before you get to the visible area of the\ncanvas.\n.SH \"INDICES\"\n.PP\nText items support the notion of an \\fIindex\\fR for identifying\nparticular positions within the item.\nIn a similar fashion, line and polygon items support \\fIindex\\fR for\nidentifying, inserting and deleting subsets of their coordinates.\nIndices are used for commands such as inserting or deleting\na range of characters or coordinates, and setting the insertion\ncursor position. An index may be specified in any of a number\nof ways, and different types of items may support different forms\nfor specifying indices.\nText items support the following forms for an index; if you\ndefine new types of text-like items, it would be advisable to\nsupport as many of these forms as practical.\nNote that it is possible to refer to the character just after\nthe last one in the text item; this is necessary for such\ntasks as inserting new text at the end of the item.\nLines and Polygons do not support the insertion cursor\nand the selection. Their indices are supposed to be even\nalways, because coordinates always appear in pairs.\n.IP \\fInumber\\fR 10\nA decimal number giving the position of the desired character\nwithin the text item.\n0 refers to the first character, 1 to the next character, and\nso on. If indexes are odd for lines and polygons, they will be\nautomatically decremented by one.\nA negative number is treated as if it were zero, and a\nnumber greater than the length of the text item is treated\nas if it were equal to the length of the text item. For\npolygons, negative numbers or numbers greater than the length\nof the coordinate list will be adjusted by adding or subtracting\nthe length until the result is between zero and the length,\ninclusive.\n.IP \\fBend\\fR 10\nRefers to the character or coordinate just after the last one\nin the item (same as the number of characters or coordinates\nin the item).\n.IP \\fBinsert\\fR 10\nRefers to the character just before which the insertion cursor\nis drawn in this item. Not valid for lines and polygons.\n.IP \\fBsel.first\\fR 10\nRefers to the first selected character in the item.\nIf the selection is not in this item then this form is illegal.\n.IP \\fBsel.last\\fR 10\nRefers to the last selected character in the item.\nIf the selection is not in this item then this form is illegal.\n.IP \\fB@\\fIx,y\\fR 10\nRefers to the character or coordinate at the point given by \\fIx\\fR and\n\\fIy\\fR, where \\fIx\\fR and \\fIy\\fR are specified in the coordinate\nsystem of the canvas.\nIf \\fIx\\fR and \\fIy\\fR lie outside the coordinates covered by the\ntext item, then they refer to the first or last character in the\nline that is closest to the given point.\n.SH \"DASH PATTERNS\"\n.PP\nMany items support the notion of a dash pattern for outlines.\n.PP\nThe first possible syntax is a list of integers. Each element\nrepresents the number of pixels of a line segment. Only the odd\nsegments are drawn using the\n.QW outline\ncolor. The other segments are drawn transparent.\n.PP\nThe second possible syntax is a character list containing only\n5 possible characters\n.QW \"\\fB.,-_ \\fR\" .\nThe space can be used\nto enlarge the space between other line elements, and cannot\noccur as the first position in the string. Some examples:\n.PP\n.CS\n\\-dash . \\(-> \\-dash {2 4}\n\\-dash - \\(-> \\-dash {6 4}\n\\-dash -. \\(-> \\-dash {6 4 2 4}\n\\-dash -.. \\(-> \\-dash {6 4 2 4 2 4}\n\\-dash {. } \\(-> \\-dash {2 8}\n\\-dash , \\(-> \\-dash {4 4}\n.CE\n.PP\nThe main difference of this syntax with the previous is that it\nis shape-conserving. This means that all values in the dash\nlist will be multiplied by the line width before display. This\nassures that\n.QW .\nwill always be displayed as a dot and\n.QW -\nalways as a dash regardless of the line width.\n.PP\nOn systems which support only a limited set of dash patterns, the dash\npattern will be displayed as the closest dash pattern that is available.\nFor example, on Windows only the first 4 of the above examples are\navailable. The last 2 examples will be displayed identically to the first\none.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBcanvas\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command.\nThe following widget commands are possible for canvas widgets:\n.\\\" METHOD: addtag\n.TP\n\\fIpathName \\fBaddtag \\fItag searchSpec \\fR?\\fIarg ...\\fR?\n.\nFor each item that meets the constraints specified by\n\\fIsearchSpec\\fR and the \\fIarg\\fRs, add\n\\fItag\\fR to the list of tags associated with the item if it\nis not already present on that list.\nIt is possible that no items will satisfy the constraints\ngiven by \\fIsearchSpec\\fR and \\fIarg\\fRs, in which case the\ncommand has no effect.\nThis command returns an empty string as result.\n\\fISearchSpec\\fR and \\fIarg\\fR's may take any of the following\nforms:\n.RS\n.IP \"\\fBabove \\fItagOrId\\fR\"\nSelects the item just after (above) the one given by \\fItagOrId\\fR\nin the display list.\nIf \\fItagOrId\\fR denotes more than one item, then the last (topmost)\nof these items in the display list is used.\n.IP \\fBall\\fR\nSelects all the items in the canvas.\n.IP \"\\fBbelow \\fItagOrId\\fR\"\nSelects the item just before (below) the one given by \\fItagOrId\\fR\nin the display list.\nIf \\fItagOrId\\fR denotes more than one item, then the first (lowest)\nof these items in the display list is used.\n.IP \"\\fBclosest \\fIx y \\fR?\\fIhalo\\fR? ?\\fIstart\\fR?\"\nSelects the item closest to the point given by \\fIx\\fR and \\fIy\\fR.\nIf more than one item is at the same closest distance (e.g. two\nitems overlap the point), then the top-most of these items (the\nlast one in the display list) is used.\nIf \\fIhalo\\fR is specified, then it must be a non-negative\nvalue.\nAny item closer than \\fIhalo\\fR to the point is considered to\noverlap it.\nThe \\fIstart\\fR argument may be used to step circularly through\nall the closest items.\nIf \\fIstart\\fR is specified, it names an item using a tag or id\n(if by tag, it selects the first item in the display list with\nthe given tag).\nInstead of selecting the topmost closest item, this form will\nselect the topmost closest item that is below \\fIstart\\fR in\nthe display list; if no such item exists, then the selection\nbehaves as if the \\fIstart\\fR argument had not been specified.\n.IP \"\\fBenclosed\\fI x1 y1 x2 y2\\fR\"\nSelects all the items completely enclosed within the rectangular\nregion given by \\fIx1\\fR, \\fIy1\\fR, \\fIx2\\fR, and \\fIy2\\fR.\n\\fIX1\\fR must be no greater than \\fIx2\\fR and \\fIy1\\fR must be\nno greater than \\fIy2\\fR.\n.IP \"\\fBoverlapping\\fI x1 y1 x2 y2\\fR\"\nSelects all the items that overlap or are enclosed within the\nrectangular region given by \\fIx1\\fR, \\fIy1\\fR, \\fIx2\\fR,\nand \\fIy2\\fR.\n\\fIX1\\fR must be no greater than \\fIx2\\fR and \\fIy1\\fR must be\nno greater than \\fIy2\\fR.\n.IP \"\\fBwithtag \\fItagOrId\\fR\"\nSelects all the items given by \\fItagOrId\\fR.\n.RE\n.\\\" METHOD: bbox\n.TP\n\\fIpathName \\fBbbox \\fItagOrId\\fR ?\\fItagOrId tagOrId ...\\fR?\n.\nReturns a list with four elements giving an approximate bounding box\nfor all the items named by the \\fItagOrId\\fR arguments.\nThe list has the form\n.QW \"\\fIx1 y1 x2 y2\\fR\"\nsuch that the drawn\nareas of all the named elements are within the region bounded by\n\\fIx1\\fR on the left, \\fIx2\\fR on the right, \\fIy1\\fR on the top,\nand \\fIy2\\fR on the bottom.\nThe return value may overestimate the actual bounding box by\na few pixels.\nIf no items match any of the \\fItagOrId\\fR arguments or if the\nmatching items have empty bounding boxes (i.e. they have nothing\nto display)\nthen an empty string is returned.\n.\\\" METHOD: bind\n.TP\n\\fIpathName \\fBbind \\fItagOrId\\fR ?\\fIsequence\\fR? ?\\fIcommand\\fR?\n.\nThis command associates \\fIcommand\\fR with all the items given by\n\\fItagOrId\\fR such that whenever the event sequence given by\n\\fIsequence\\fR occurs for one of the items the command will\nbe invoked.\nThis widget command is similar to the \\fBbind\\fR command except that\nit operates on items in a canvas rather than entire widgets.\nSee the \\fBbind\\fR manual entry for complete details\non the syntax of \\fIsequence\\fR and the substitutions performed\non \\fIcommand\\fR before invoking it.\nIf all arguments are specified then a new binding is created, replacing\nany existing binding for the same \\fIsequence\\fR and \\fItagOrId\\fR\n(if the first character of \\fIcommand\\fR is\n.QW +\nthen \\fIcommand\\fR augments an existing binding rather than replacing it).\nIn this case the return value is an empty string.\nIf \\fIcommand\\fR is omitted then the command returns the \\fIcommand\\fR\nassociated with \\fItagOrId\\fR and \\fIsequence\\fR (an error occurs\nif there is no such binding).\nIf both \\fIcommand\\fR and \\fIsequence\\fR are omitted then the command\nreturns a list of all the sequences for which bindings have been\ndefined for \\fItagOrId\\fR.\n.RS\n.PP\nThe only events for which bindings may be specified are those related to\nthe mouse and keyboard (such as \\fBEnter\\fR, \\fBLeave\\fR,\n\\fBButton\\fR, \\fBMotion\\fR, and \\fBKey\\fR) or virtual events.\nThe handling of events in canvases uses the current item defined in\n\\fBITEM IDS AND TAGS\\fR above. \\fBEnter\\fR and \\fBLeave\\fR events\ntrigger for an\nitem when it becomes the current item or ceases to be the current item;\nnote that these events are different than \\fBEnter\\fR and \\fBLeave\\fR\nevents for windows. Mouse-related events are directed to the current\nitem, if any. Keyboard-related events are directed to the focus item, if\nany (see the \\fBfocus\\fR widget command below for more on this). If a\nvirtual event is used in a binding, that binding can trigger only if the\nvirtual event is defined by an underlying mouse-related or\nkeyboard-related event.\n.PP\nIt is possible for multiple bindings to match a particular event.\nThis could occur, for example, if one binding is associated with the\nitem's id and another is associated with one of the item's tags.\nWhen this occurs, all of the matching bindings are invoked.\nA binding associated with the \\fBall\\fR tag is invoked first,\nfollowed by one binding for each of the item's tags (in order),\nfollowed by a binding associated with the item's id.\nIf there are multiple matching bindings for a single tag,\nthen only the most specific binding is invoked.\nA \\fBcontinue\\fR command in a binding script terminates that\nscript, and a \\fBbreak\\fR command terminates that script\nand skips any remaining scripts for the event, just as for the\n\\fBbind\\fR command.\n.PP\nIf bindings have been created for a canvas window using the \\fBbind\\fR\ncommand, then they are invoked in addition to bindings created for\nthe canvas's items using the \\fBbind\\fR widget command.\nThe bindings for items will be invoked before any of the bindings\nfor the window as a whole.\n.RE\n.\\\" METHOD: canvasx\n.TP\n\\fIpathName \\fBcanvasx \\fIscreenx\\fR ?\\fIgridspacing\\fR?\n.\nGiven a window x-coordinate in the canvas \\fIscreenx\\fR, this command returns\nthe canvas x-coordinate that is displayed at that location.\nIf \\fIgridspacing\\fR is specified, then the canvas coordinate is\nrounded to the nearest multiple of \\fIgridspacing\\fR units.\n.\\\" METHOD: canvasy\n.TP\n\\fIpathName \\fBcanvasy \\fIscreeny\\fR ?\\fIgridspacing\\fR?\n.\nGiven a window y-coordinate in the canvas \\fIscreeny\\fR this command returns\nthe canvas y-coordinate that is displayed at that location.\nIf \\fIgridspacing\\fR is specified, then the canvas coordinate is\nrounded to the nearest multiple of \\fIgridspacing\\fR units.\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBcanvas\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure ?\\fIoption\\fR? ?\\fIvalue\\fR? ?\\fIoption value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBcanvas\\fR\ncommand.\n.\\\" METHOD: coords\n.TP\n\\fIpathName \\fBcoords \\fItagOrId \\fR?\\fIx0 y0 ...\\fR?\n.TP\n\\fIpathName \\fBcoords \\fItagOrId \\fR?\\fIcoordList\\fR?\n.\nQuery or modify the coordinates that define an item.\nIf no coordinates are specified, this command returns a list\nwhose elements are the coordinates of the item named by\n\\fItagOrId\\fR.\nIf coordinates are specified, then they replace the current\ncoordinates for the named item.\nIf \\fItagOrId\\fR refers to multiple items, then\nthe first one in the display list is used.\n.RS\n.PP\nNote that for rectangles, ovals and arcs the returned list of coordinates\nhas a fixed order, namely the left, top, right and bottom coordinates,\nwhich may not be the order originally given. Also the coordinates are always\nreturned in screen units with no units (that is, in pixels). So if the\noriginal coordinates were specified for instance in centimeters or inches,\nthe returned values will nevertheless be in pixels.\n.RE\n.\\\" METHOD: create\n.TP\n\\fIpathName \\fBcreate \\fItype x y \\fR?\\fIx y ...\\fR? ?\\fIoption value ...\\fR?\n.TP\n\\fIpathName \\fBcreate \\fItype coordList \\fR?\\fIoption value ...\\fR?\n.\nCreate a new item in \\fIpathName\\fR of type \\fItype\\fR.\nThe exact format of the arguments after \\fItype\\fR depends\non \\fItype\\fR, but usually they consist of the coordinates for\none or more points, followed by specifications for zero or\nmore item options.\nSee the subsections on individual item types below for more\non the syntax of this command.\nThis command returns the id for the new item.\n.\\\" METHOD: dchars\n.TP\n\\fIpathName \\fBdchars \\fItagOrId first \\fR?\\fIlast\\fR?\n.\nFor each item given by \\fItagOrId\\fR, delete the characters, or coordinates,\nin the range given by \\fIfirst\\fR and \\fIlast\\fR, inclusive.\nIf some of the items given by \\fItagOrId\\fR do not support\nindexing operations then they ignore this operation.\nText items interpret \\fIfirst\\fR and \\fIlast\\fR as indices to a character,\nline and polygon items interpret them as indices to a coordinate (an x,y pair).\nIndices are described in \\fBINDICES\\fR above.\nIf \\fIlast\\fR is omitted, it defaults to \\fIfirst\\fR.\nThis command returns an empty string.\n.\\\" METHOD: delete\n.TP\n\\fIpathName \\fBdelete \\fR?\\fItagOrId tagOrId ...\\fR?\n.\nDelete each of the items given by each \\fItagOrId\\fR, and return\nan empty string.\n.\\\" METHOD: dtag\n.TP\n\\fIpathName \\fBdtag \\fItagOrId \\fR?\\fItagToDelete\\fR?\n.\nFor each of the items given by \\fItagOrId\\fR, delete the\ntag given by \\fItagToDelete\\fR from the list of those\nassociated with the item.\nIf an item does not have the tag \\fItagToDelete\\fR then\nthe item is unaffected by the command.\nIf \\fItagToDelete\\fR is omitted then it defaults to \\fItagOrId\\fR.\nThis command returns an empty string.\n.\\\" METHOD: find\n.TP\n\\fIpathName \\fBfind \\fIsearchCommand \\fR?\\fIarg ...\\fR?\n.\nThis command returns a list consisting of all the items that\nmeet the constraints specified by \\fIsearchCommand\\fR and\n\\fIarg\\fR's.\n\\fISearchCommand\\fR and \\fIargs\\fR have any of the forms\naccepted by the \\fBaddtag\\fR command.\nThe items are returned in stacking order, with the lowest item first.\n.\\\" METHOD: focus\n.TP\n\\fIpathName \\fBfocus \\fR?\\fItagOrId\\fR?\n.\nSet the keyboard focus for the canvas widget to the item given by\n\\fItagOrId\\fR.\nIf \\fItagOrId\\fR refers to several items, then the focus is set\nto the first such item in the display list that supports the\ninsertion cursor.\nIf \\fItagOrId\\fR does not refer to any items, or if none of them\nsupport the insertion cursor, then the focus is not changed.\nIf \\fItagOrId\\fR is an empty\nstring, then the focus item is reset so that no item has the focus.\nIf \\fItagOrId\\fR is not specified then the command returns the\nid for the item that currently has the focus, or an empty string\nif no item has the focus.\n.RS\n.PP\nOnce the focus has been set to an item, the item will display\nthe insertion cursor and all keyboard events will be directed\nto that item.\nThe focus item within a canvas and the focus window on the\nscreen (set with the \\fBfocus\\fR command) are totally independent:\na given item does not actually have the input focus unless (a)\nits canvas is the focus window and (b) the item is the focus item\nwithin the canvas.\nIn most cases it is advisable to follow the \\fBfocus\\fR widget\ncommand with the \\fBfocus\\fR command to set the focus window to\nthe canvas (if it was not there already).\n.RE\n.\\\" METHOD: gettags\n.TP\n\\fIpathName \\fBgettags\\fI tagOrId\\fR\n.\nReturn a list whose elements are the tags associated with the\nitem given by \\fItagOrId\\fR.\nIf \\fItagOrId\\fR refers to more than one item, then the tags\nare returned from the first such item in the display list.\nIf \\fItagOrId\\fR does not refer to any items, or if the item\ncontains no tags, then an empty string is returned.\n.\\\" METHOD: icursor\n.TP\n\\fIpathName \\fBicursor \\fItagOrId index\\fR\n.\nSet the position of the insertion cursor for the item(s) given by \\fItagOrId\\fR\nto just before the character whose position is given by \\fIindex\\fR.\nIf some or all of the items given by \\fItagOrId\\fR do not support\nan insertion cursor then this command has no effect on them.\nSee \\fBINDICES\\fR above for a description of the\nlegal forms for \\fIindex\\fR.\n.RS\n.PP\nNote that the insertion cursor is only displayed in an item if\nthat item currently has the keyboard focus (see the \\fBfocus\\fR widget\ncommand, above), but the cursor position may\nbe set even when the item does not have the focus.\n.PP\nThis command returns an empty string.\n.RE\n.\\\" METHOD: image\n.TP\n\\fIpathName \\fBimage \\fIimagename\\fR ?\\fIsubsample\\fR? ?\\fIzoom\\fR?\n.\nDraw the canvas into the Tk photo image named \\fIimagename\\fR.\nIf a \\fB\\-scrollregion\\fR has been defined then this will be the boundaries\nof the canvas region drawn and the final size of the photo image. Otherwise\nthe widget width and height with an origin of 0,0 will be the size of the\ncanvas region drawn and the final size of the photo image. Optionally an\ninteger \\fIsubsample\\fR factor may be given and the photo image\nwill be reduced in size.\n.RS\n.PP\nIn addition to the \\fIsubsample\\fR an integer \\fIzoom\\fR factor can also\nbe given and the photo image will be enlarged. The image background will\nbe filled with the canvas background colour. The canvas widget does not\nneed to be mapped for this widget command to work, but at least one of\nit's ancestors must be mapped.\n.PP\nThis command returns an empty string.\n.RE\n.\\\" METHOD: imove\n.TP\n\\fIpathName \\fBimove \\fItagOrId index x y\\fR\n.\nThis command causes the \\fIindex\\fR'th coordinate of each of the items\nindicated by \\fItagOrId\\fR to be relocated to the location (\\fIx\\fR,\\fIy\\fR).\nEach item interprets \\fIindex\\fR independently according to the rules\ndescribed in \\fBINDICES\\fR above. Out of the standard set of items, only line\nand polygon items may have their coordinates relocated this way.\n.\\\" METHOD: index\n.TP\n\\fIpathName \\fBindex \\fItagOrId index\\fR\n.\nThis command returns a decimal string giving the numerical index\nwithin \\fItagOrId\\fR corresponding to \\fIindex\\fR.\n\\fIIndex\\fR gives a textual description of the desired position\nas described in \\fBINDICES\\fR above.\nText items interpret \\fIindex\\fR as an index to a character,\nline and polygon items interpret it as an index to a coordinate (an x,y pair).\nThe return value is guaranteed to lie between 0 and the number\nof characters, or coordinates, within the item, inclusive.\nIf \\fItagOrId\\fR refers to multiple items, then the index\nis processed in the first of these items that supports indexing\noperations (in display list order).\n.\\\" METHOD: insert\n.TP\n\\fIpathName \\fBinsert \\fItagOrId beforeThis string\\fR\n.\nFor each of the items given by \\fItagOrId\\fR, if the item supports\ntext or coordinate, insertion then \\fIstring\\fR is inserted into the item's\ntext just before the character, or coordinate, whose index is \\fIbeforeThis\\fR.\nText items interpret \\fIbeforeThis\\fR as an index to a character,\nline and polygon items interpret it as an index to a coordinate (an x,y pair).\nFor lines and polygons the \\fIstring\\fR must be a valid coordinate\nsequence.\n.RS\n.PP\nSee \\fBINDICES\\fR above for information about the forms allowed\nfor \\fIbeforeThis\\fR.\n.PP\nThis command returns an empty string.\n.RE\n.\\\" METHOD: itemcget\n.TP\n\\fIpathName \\fBitemcget\\fI tagOrId option\\fR\n.\nReturns the current value of the configuration option for the\nitem given by \\fItagOrId\\fR whose name is \\fIoption\\fR.\nThis command is similar to the \\fBcget\\fR widget command except that\nit applies to a particular item rather than the widget as a whole.\n\\fIOption\\fR may have any of the values accepted by the \\fBcreate\\fR\nwidget command when the item was created.\nIf \\fItagOrId\\fR is a tag that refers to more than one item,\nthe first (lowest) such item is used.\n.\\\" METHOD: itemconfigure\n.TP\n\\fIpathName \\fBitemconfigure \\fItagOrId\\fR ?\\fIoption\\fR? ?\\fIvalue\\fR? ?\\fIoption value ...\\fR?\n.\nThis command is similar to the \\fBconfigure\\fR widget command except\nthat it modifies item-specific options for the items given by\n\\fItagOrId\\fR instead of modifying options for the overall\ncanvas widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for the first item given by \\fItagOrId\\fR\n(see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s) in\neach of the items given by \\fItagOrId\\fR; in\nthis case the command returns an empty string.\nThe \\fIoption\\fRs and \\fIvalue\\fRs are the same as those permissible\nin the \\fBcreate\\fR widget command when the item(s) were created;\nsee the sections describing individual item types below for details\non the legal options.\n.\\\" METHOD: lower\n.TP\n\\fIpathName \\fBlower \\fItagOrId \\fR?\\fIbelowThis\\fR?\n.\nMove all of the items given by \\fItagOrId\\fR to a new position\nin the display list just before the item given by \\fIbelowThis\\fR.\nIf \\fItagOrId\\fR refers to more than one item then all are moved\nbut the relative order of the moved items will not be changed.\n\\fIBelowThis\\fR is a tag or id; if it refers to more than one\nitem then the first (lowest) of these items in the display list is used\nas the destination location for the moved items.\nNote that this command has no effect on window items. Window items always\nobscure other item types, and the stacking order of window items is\ndetermined by the \\fBraise\\fR command and \\fBlower\\fR command, not the\n\\fBraise\\fR widget command and \\fBlower\\fR widget command for canvases.\nThis command returns an empty string.\n.\\\" METHOD: move\n.TP\n\\fIpathName \\fBmove \\fItagOrId xAmount yAmount\\fR\n.\nMove each of the items given by \\fItagOrId\\fR in the canvas coordinate\nspace by adding \\fIxAmount\\fR to the x-coordinate of each point\nassociated with the item and \\fIyAmount\\fR to the y-coordinate of\neach point associated with the item.\nThis command returns an empty string.\n.\\\" METHOD: moveto\n.TP\n\\fIpathName \\fBmoveto \\fItagOrId xPos yPos\\fR\n.\nMove the items given by \\fItagOrId\\fR in the canvas coordinate\nspace so that the first coordinate pair (the upper-left corner of the\nbounding box) of the first item (the lowest in the display list) with\ntag \\fItagOrId\\fR is located at\nposition (\\fIxPos\\fR,\\fIyPos\\fR). \\fIxPos\\fR and \\fIyPos\\fR may be\nthe empty string, in which case the corresponding coordinate\nwill be unchanged. All items matching\n\\fItagOrId\\fR remain in the same positions relative to each other.\nThis command returns an empty string.\n.\\\" METHOD: postscript\n.TP\n\\fIpathName \\fBpostscript \\fR?\\fIoption value option value ...\\fR?\n.\nGenerate a Postscript representation for part or all of the canvas.\nIf the \\fB\\-file\\fR option is specified then the Postscript is written\nto a file and an empty string is returned; otherwise the Postscript\nis returned as the result of the command.\nIf the interpreter that owns the canvas is marked as safe, the operation\nwill fail because safe interpreters are not allowed to write files.\nIf the \\fB\\-channel\\fR option is specified, the argument denotes the name\nof a channel already opened for writing. The Postscript is written to\nthat channel, and the channel is left open for further writing at the end\nof the operation.\nThe Postscript is created in Encapsulated Postscript form using\nversion 3.0 of the Document Structuring Conventions.\nNote: by default Postscript is only generated for information that\nappears in the canvas's window on the screen. If the canvas is\nfreshly created it may still have its initial size of 1x1 pixel\nso nothing will appear in the Postscript. To get around this problem\neither invoke the \\fBupdate\\fR command to wait for the canvas window\nto reach its final size, or else use the \\fB\\-width\\fR and \\fB\\-height\\fR\noptions to specify the area of the canvas to print.\nThe \\fIoption\\fR\\-\\fIvalue\\fR argument pairs provide additional\ninformation to control the generation of Postscript. The following\noptions are supported:\n.RS\n.\\\" OPTION: -channel\n.TP\n\\fB\\-channel \\fIchannelName\\fR\n.\nSpecifies the name of the channel to which to write the Postscript.\nIf this option and the \\fB\\-file\\fR option are\nnot specified then the Postscript is returned as the\nresult of the command.\n.\\\" OPTION: -colormap\n.TP\n\\fB\\-colormap \\fIvarName\\fR\n.\n\\fIVarName\\fR must be the name of an array variable\nthat specifies a color mapping to use in the Postscript.\nEach element of \\fIvarName\\fR must consist of Postscript\ncode to set a particular color value (e.g.\n.QW \"\\fB1.0 1.0 0.0 setrgbcolor\\fR\" ).\nWhen outputting color information in the Postscript, Tk checks\nto see if there is an element of \\fIvarName\\fR with the same\nname as the color.\nIf so, Tk uses the value of the element as the Postscript command\nto set the color.\n.RS\n.PP\nIf this option has not been specified, or if there is no entry\nin \\fIvarName\\fR for a given color, then Tk uses the red, green,\nand blue intensities from the X color.\n.RE\n.\\\" OPTION: -colormode\n.TP\n\\fB\\-colormode \\fImode\\fR\n.\nSpecifies how to output color information. \\fIMode\\fR must be either\n\\fBcolor\\fR (for full color output), \\fBgray\\fR (convert all colors\nto their gray-scale equivalents) or \\fBmono\\fR (convert all colors\nto black or white).\n.\\\" OPTION: -file\n.TP\n\\fB\\-file \\fIfileName\\fR\n.\nSpecifies the name of the file in which to write the Postscript.\nIf this option and the \\fB\\-channel\\fR option are\nnot specified then the Postscript is returned as the\nresult of the command.\n.\\\" OPTION: -fontmap\n.TP\n\\fB\\-fontmap \\fIvarName\\fR\n.\n\\fIVarName\\fR must be the name of an array variable\nthat specifies a font mapping to use in the Postscript.\nEach element of \\fIvarName\\fR must consist of a Tcl list with\ntwo elements, which are the name and point size of a Postscript font.\nWhen outputting Postscript commands for a particular font, Tk\nchecks to see if \\fIvarName\\fR contains an element with the same\nname as the font.\nIf there is such an element, then the font information contained in\nthat element is used in the Postscript.\nOtherwise Tk attempts to guess what Postscript font to use.\nTk's guesses generally only work for well-known fonts such as\nTimes and Helvetica and Courier, and only if the X font name does not\nomit any dashes up through the point size.\n.RS\n.PP\nFor example, \\fB\\-*\\-Courier\\-Bold\\-R\\-Normal\\-\\-*\\-120\\-*\\fR will work but\n\\fB*Courier\\-Bold\\-R\\-Normal*120*\\fR will not; Tk needs the dashes to\nparse the font name).\n.RE\n.\\\" OPTION: -height\n.TP\n\\fB\\-height \\fIsize\\fR\n.\nSpecifies the height of the area of the canvas to print.\nDefaults to the height of the canvas window.\n.\\\" OPTION: -pageanchor\n.TP\n\\fB\\-pageanchor \\fIanchor\\fR\n.\nSpecifies which point of the printed area of the canvas should appear over\nthe positioning point on the page (which is given by the \\fB\\-pagex\\fR\nand \\fB\\-pagey\\fR options).\n.RS\n.PP\nFor example, \\fB\\-pageanchor n\\fR means that the top center of the\narea of the canvas being printed (as it appears in the canvas window)\nshould be over the positioning point. Defaults to \\fBcenter\\fR.\n.RE\n.\\\" OPTION: -pageheight\n.TP\n\\fB\\-pageheight \\fIsize\\fR\n.\nSpecifies that the Postscript should be scaled in both x and y so\nthat the printed area is \\fIsize\\fR high on the Postscript page.\n\\fISize\\fR consists of a floating-point number followed by\n\\fBc\\fR for centimeters, \\fBi\\fR for inches, \\fBm\\fR for millimeters,\nor \\fBp\\fR or nothing for printer's points (1/72 inch).\nDefaults to the height of the printed area on the screen.\nIf both \\fB\\-pageheight\\fR and \\fB\\-pagewidth\\fR are specified then\nthe scale factor from \\fB\\-pagewidth\\fR is used (non-uniform scaling\nis not implemented).\n.\\\" OPTION: -pagewidth\n.TP\n\\fB\\-pagewidth \\fIsize\\fR\n.\nSpecifies that the Postscript should be scaled in both x and y so\nthat the printed area is \\fIsize\\fR wide on the Postscript page.\n\\fISize\\fR has the same form as for \\fB\\-pageheight\\fR.\nDefaults to the width of the printed area on the screen.\nIf both \\fB\\-pageheight\\fR and \\fB\\-pagewidth\\fR are specified then\nthe scale factor from \\fB\\-pagewidth\\fR is used (non-uniform scaling\nis not implemented).\n.\\\" OPTION: -pagex\n.TP\n\\fB\\-pagex \\fIposition\\fR\n.\n\\fIPosition\\fR gives the x-coordinate of the positioning point on\nthe Postscript page, using any of the forms allowed for \\fB\\-pageheight\\fR.\nUsed in conjunction with the \\fB\\-pagey\\fR and \\fB\\-pageanchor\\fR options\nto determine where the printed area appears on the Postscript page.\nDefaults to the center of the page.\n.\\\" OPTION: -pagey\n.TP\n\\fB\\-pagey \\fIposition\\fR\n.\n\\fIPosition\\fR gives the y-coordinate of the positioning point on\nthe Postscript page, using any of the forms allowed for \\fB\\-pageheight\\fR.\nUsed in conjunction with the \\fB\\-pagex\\fR and \\fB\\-pageanchor\\fR options\nto determine where the printed area appears on the Postscript page.\nDefaults to the center of the page.\n.\\\" OPTION: -rotate\n.TP\n\\fB\\-rotate \\fIboolean\\fR\n.\n\\fIBoolean\\fR specifies whether the printed area is to be rotated 90\ndegrees.\nIn non-rotated output the x-axis of the printed area runs along\nthe short dimension of the page\n.PQ portrait \" orientation\" ;\nin rotated output the x-axis runs along the long dimension of the page\n.PQ landscape \" orientation\" .\nDefaults to non-rotated.\n.\\\" OPTION: -width\n.TP\n\\fB\\-width \\fIsize\\fR\n.\nSpecifies the width of the area of the canvas to print.\nDefaults to the width of the canvas window.\n.\\\" OPTION: -x\n.TP\n\\fB\\-x \\fIposition\\fR\n.\nSpecifies the x-coordinate of the left edge of the area of the\ncanvas that is to be printed, in canvas coordinates, not window\ncoordinates.\nDefaults to the coordinate of the left edge of the window.\n.\\\" OPTION: -y\n.TP\n\\fB\\-y \\fIposition\\fR\n.\nSpecifies the y-coordinate of the top edge of the area of the\ncanvas that is to be printed, in canvas coordinates, not window\ncoordinates.\nDefaults to the coordinate of the top edge of the window.\n.RE\n.\\\" METHOD: raise\n.TP\n\\fIpathName \\fBraise \\fItagOrId \\fR?\\fIaboveThis\\fR?\n.\nMove all of the items given by \\fItagOrId\\fR to a new position\nin the display list just after the item given by \\fIaboveThis\\fR.\nIf \\fItagOrId\\fR refers to more than one item then all are moved\nbut the relative order of the moved items will not be changed.\n\\fIAboveThis\\fR is a tag or id; if it refers to more than one\nitem then the last (topmost) of these items in the display list is used\nas the destination location for the moved items.\nThis command returns an empty string.\n.RS\n.PP\nNote this this command has no effect on window items. Window items always\nobscure other item types, and the stacking order of window items is\ndetermined by the \\fBraise\\fR command and \\fBlower\\fR command, not the\n\\fBraise\\fR widget command and \\fBlower\\fR widget command for canvases.\n.RE\n.\\\" METHOD: rchars\n.TP\n\\fIpathName \\fBrchars \\fItagOrId first last string\\fR\n.\nThis command causes the text or coordinates between \\fIfirst\\fR and \\fIlast\\fR\nfor each of the items indicated by \\fItagOrId\\fR to be replaced by\n\\fIstring\\fR. Each item interprets \\fIfirst\\fR and \\fIlast\\fR independently\naccording to the rules described in \\fBINDICES\\fR above. Out of the standard\nset of items, text items support this operation by altering their text as\ndirected, and line and polygon items support this operation by altering their\ncoordinate list (in which case \\fIstring\\fR should be a list of coordinates to\nuse as a replacement). The other items ignore this operation.\n.\\\" METHOD: rotate\n.TP\n\\fIpathName \\fBrotate \\fItagOrId xOrigin yOrigin angle\\fR\n.VS \"9.0, TIP164\"\nRotate the coordinates of all of the items given by \\fItagOrId\\fR in canvas\ncoordinate space.\n\\fIXOrigin\\fR and \\fIyOrigin\\fR identify the origin for the rotation\noperation and \\fIangle\\fR identifies the amount to rotate the coordinates\nanticlockwise, in degrees. (Negative values rotate clockwise.)\nThis command returns an empty string.\n.RS\n.PP\nImplementation note: not all item types work the same with rotations. In\nparticular,\\fB bitmap\\fR,\\fB image\\fR,\\fB text\\fR and\\fB window\\fR items only\nrotate their anchor points and do not rotate the items themselves about those\npoints, and the \\fBarc\\fR, \\fBoval\\fR and \\fBrectangle\\fR types rotate about a\ncomputed center point instead of moving the bounding box coordinates directly.\n.PP\nSome items (currently \\fBarc\\fR and\\fB text\\fR) have angles in their options;\nthis command \\fIdoes not\\fR affect those options.\n.RE\n.VE \"9.0, TIP164\"\n.\\\" METHOD: scale\n.TP\n\\fIpathName \\fBscale \\fItagOrId xOrigin yOrigin xScale yScale\\fR\n.\nRescale the coordinates of all of the items given by \\fItagOrId\\fR in canvas\ncoordinate space.\n\\fIXOrigin\\fR and \\fIyOrigin\\fR identify the origin for the scaling\noperation and \\fIxScale\\fR and \\fIyScale\\fR identify the scale\nfactors for x- and y-coordinates, respectively (a scale factor of\n1.0 implies no change to that coordinate).\nFor each of the points defining each item, the x-coordinate is\nadjusted to change the distance from \\fIxOrigin\\fR by a factor\nof \\fIxScale\\fR.\nSimilarly, each y-coordinate is adjusted to change the distance\nfrom \\fIyOrigin\\fR by a factor of \\fIyScale\\fR.\nThis command returns an empty string.\n.RS\n.PP\nNote that some items have only a single pair of coordinates (e.g., text,\nimages and windows) and so scaling of them by this command can only move them\naround.\n.RE\n.\\\" METHOD: scan\n.TP\n\\fIpathName \\fBscan\\fI option args\\fR\n.\nThis command is used to implement scanning on canvases. It has\ntwo forms, depending on \\fIoption\\fR:\n.RS\n.TP\n\\fIpathName \\fBscan mark \\fIx y\\fR\n.\nRecords \\fIx\\fR and \\fIy\\fR and the canvas's current view; used\nin conjunction with later \\fBscan dragto\\fR commands.\nTypically this command is associated with a mouse button press in\nthe widget and \\fIx\\fR and \\fIy\\fR are the coordinates of the\nmouse. It returns an empty string.\n.TP\n\\fIpathName \\fBscan dragto \\fIx y ?gain?\\fR\n.\nThis command computes the difference between its \\fIx\\fR and \\fIy\\fR\narguments (which are typically mouse coordinates) and the \\fIx\\fR and\n\\fIy\\fR arguments to the last \\fBscan mark\\fR command for the widget.\nIt then adjusts the view by \\fIgain\\fR times the\ndifference in coordinates, where \\fIgain\\fR defaults to 10.\nThis command is typically associated\nwith mouse motion events in the widget, to produce the effect of\ndragging the canvas at high speed through its window. The return\nvalue is an empty string.\n.RE\n.\\\" METHOD: select\n.TP\n\\fIpathName \\fBselect \\fIoption\\fR ?\\fItagOrId arg\\fR?\n.\nManipulates the selection in one of several ways, depending on\n\\fIoption\\fR.\nThe command may take any of the forms described below.\nIn all of the descriptions below, \\fItagOrId\\fR must refer to\nan item that supports indexing and selection; if it refers to\nmultiple items then the first of\nthese that supports indexing and the selection is used.\n\\fIIndex\\fR gives a textual description of a position\nwithin \\fItagOrId\\fR, as described in \\fBINDICES\\fR above.\n.RS\n.TP\n\\fIpathName \\fBselect adjust \\fItagOrId index\\fR\n.\nLocate the end of the selection in \\fItagOrId\\fR nearest\nto the character given by \\fIindex\\fR, and adjust that\nend of the selection to be at \\fIindex\\fR (i.e. including\nbut not going beyond \\fIindex\\fR).\nThe other end of the selection is made the anchor point\nfor future \\fBselect to\\fR commands.\nIf the selection is not currently in \\fItagOrId\\fR then\nthis command behaves the same as the \\fBselect to\\fR widget\ncommand.\nReturns an empty string.\n.TP\n\\fIpathName \\fBselect clear\\fR\n.\nClear the selection if it is in this widget.\nIf the selection is not in this widget then the command\nhas no effect.\nReturns an empty string.\n.TP\n\\fIpathName \\fBselect from \\fItagOrId index\\fR\n.\nSet the selection anchor point for the widget to be just\nbefore the character\ngiven by \\fIindex\\fR in the item given by \\fItagOrId\\fR.\nThis command does not change the selection; it just sets\nthe fixed end of the selection for future \\fBselect to\\fR\ncommands.\nReturns an empty string.\n.TP\n\\fIpathName \\fBselect item\\fR\n.\nReturns the id of the selected item, if the selection is in an\nitem in this canvas.\nIf the selection is not in this canvas then an empty string\nis returned.\n.TP\n\\fIpathName \\fBselect to \\fItagOrId index\\fR\n.\nSet the selection to consist of those characters of \\fItagOrId\\fR\nbetween the selection anchor point and\n\\fIindex\\fR.\nThe new selection will include the character given by \\fIindex\\fR;\nit will include the character given by the anchor point only if\n\\fIindex\\fR is greater than or equal to the anchor point.\nThe anchor point is determined by the most recent \\fBselect adjust\\fR\nor \\fBselect from\\fR command for this widget.\nIf the selection anchor point for the widget is not currently in\n\\fItagOrId\\fR, then it is set to the same character given\nby \\fIindex\\fR.\nReturns an empty string.\n.RE\n.\\\" METHOD: type\n.TP\n\\fIpathName \\fBtype\\fI tagOrId\\fR\n.\nReturns the type of the item given by \\fItagOrId\\fR, such as\n\\fBrectangle\\fR or \\fBtext\\fR.\nIf \\fItagOrId\\fR refers to more than one item, then the type\nof the first item in the display list is returned.\nIf \\fItagOrId\\fR does not refer to any items at all then\nan empty string is returned.\n.\\\" METHOD: xview\n.TP\n\\fIpathName \\fBxview \\fR?\\fIargs\\fR?\n.\nThis command is used to query and change the horizontal position of the\ninformation displayed in the canvas's window.\nIt can take any of the following forms:\n.RS\n.TP\n\\fIpathName \\fBxview\\fR\n.\nReturns a list containing two elements.\nEach element is a real fraction between 0 and 1; together they describe\nthe horizontal span that is visible in the window.\nFor example, if the first element is .2 and the second element is .6,\n20% of the canvas's area (as defined by the \\fB\\-scrollregion\\fR option)\nis off-screen to the left, the middle 40% is visible\nin the window, and 40% of the canvas is off-screen to the right.\nThese are the same values passed to scrollbars via the \\fB\\-xscrollcommand\\fR\noption.\n.TP\n\\fIpathName \\fBxview moveto\\fI fraction\\fR\n.\nAdjusts the view in the window so that \\fIfraction\\fR of the\ntotal width of the canvas is off-screen to the left.\n\\fIFraction\\fR must be a fraction between 0 and 1.\n.TP\n\\fIpathName \\fBxview scroll \\fInumber what\\fR\n.\nThis command shifts the view in the window left or right according to\n\\fInumber\\fR and \\fIwhat\\fR.\n\\fINumber\\fR must be an integer or a float, but if it is a float then\nit is converted to an integer, rounded away from 0.\n\\fIWhat\\fR must be either \\fBpages\\fR or \\fBunits\\fR or an abbreviation\nof one of these.\nIf \\fIwhat is \\fBpages\\fR then the view\nadjusts in units of nine-tenths the window's width.\nIf \\fInumber\\fR is negative then information farther to the left\nbecomes visible; if it is positive then information farther to the right\nbecomes visible.\nIf \\fIwhat\\fR is \\fBunits\\fR, the view adjusts left or right in units\nof the \\fBxScrollIncrement\\fR option, if it is greater than zero,\nor in units of one-tenth the window's width otherwise.\n.RE\n.\\\" METHOD: yview\n.TP\n\\fIpathName \\fByview ?\\fIargs\\fR?\n.\nThis command is used to query and change the vertical position of the\ninformation displayed in the canvas's window.\nIt can take any of the following forms:\n.RS\n.TP\n\\fIpathName \\fByview\\fR\n.\nReturns a list containing two elements.\nEach element is a real fraction between 0 and 1; together they describe\nthe vertical span that is visible in the window.\nFor example, if the first element is .6 and the second element is 1.0,\nthe lowest 40% of the canvas's area (as defined by the \\fB\\-scrollregion\\fR\noption) is visible in the window.\nThese are the same values passed to scrollbars via the \\fB\\-yscrollcommand\\fR\noption.\n.TP\n\\fIpathName \\fByview moveto\\fI fraction\\fR\n.\nAdjusts the view in the window so that \\fIfraction\\fR of the canvas's\narea is off-screen to the top.\n\\fIFraction\\fR is a fraction between 0 and 1.\n.TP\n\\fIpathName \\fByview scroll \\fInumber what\\fR\n.\nThis command adjusts the view in the window up or down according to\n\\fInumber\\fR and \\fIwhat\\fR.\n\\fINumber\\fR must be an integer or a float, but if it is a float then\nit is converted to an integer, rounded away from 0.\n\\fIWhat\\fR must be either \\fBpages\\fR or \\fBunits\\fR.\nIf \\fIwhat\\fR is \\fBpages\\fR then\nthe view adjusts in units of nine-tenths the window's height.\nIf \\fInumber\\fR is negative then higher information becomes\nvisible; if it is positive then lower information\nbecomes visible.\nIf \\fIwhat\\fR is \\fBunits\\fR, the view adjusts up or down in units\nof the \\fByScrollIncrement\\fR option, if it is greater than zero,\nor in units of one-tenth the window's height otherwise.\n.RE\n.SH \"OVERVIEW OF ITEM TYPES\"\n.PP\nThe sections below describe the various types of items supported\nby canvas widgets. Each item type is characterized by two things:\nfirst, the form of the \\fBcreate\\fR command used to create\ninstances of the type; and second, a set of configuration options\nfor items of that type, which may be used in the\n\\fBcreate\\fR and \\fBitemconfigure\\fR widget commands.\nMost items do not support indexing or selection or the commands\nrelated to them, such as \\fBindex\\fR and \\fBinsert\\fR.\nWhere items do support these facilities, it is noted explicitly\nin the descriptions below.\nAt present, text, line and polygon items provide this support.\nFor lines and polygons the indexing facility is used to manipulate\nthe coordinates of the item.\n.SS \"COMMON ITEM OPTIONS\"\n.PP\nMany items share a common set of options. These options are\nexplained here, and then referred to be each widget type for brevity.\n.\\\" OPTION: -anchor\n.TP\n\\fB\\-anchor \\fIanchorPos\\fR\n.\n\\fIAnchorPos\\fR tells how to position the item relative to the\npositioning point for the item; it may have any of the forms\naccepted by \\fBTk_GetAnchor\\fR. For example, if \\fIanchorPos\\fR\nis \\fBcenter\\fR then the item is centered on the point; if\n\\fIanchorPos\\fR is \\fBn\\fR then the item will be drawn so that\nits top center point is at the positioning point.\nThis option defaults to \\fBcenter\\fR.\n.\\\" OPTION: -dash\n.TP\n\\fB\\-dash \\fIpattern\\fR\n.\\\" OPTION: -activedash\n.TP\n\\fB\\-activedash \\fIpattern\\fR\n.\\\" OPTION: -disableddash\n.TP\n\\fB\\-disableddash \\fIpattern\\fR\n.\nThese options specify dash patterns for the normal, active\nstate, and disabled state of an item.\n\\fIpattern\\fR may have any of the forms accepted by \\fBTk_GetDash\\fR.\nIf the dash options are omitted then the default is a solid outline.\nSee \\fBDASH PATTERNS\\fR for more information.\n.\\\" OPTION: -dashoffset\n.TP\n\\fB\\-dashoffset \\fIoffset\\fR\n.\nThe starting \\fIoffset\\fR in pixels into the pattern provided by the\n\\fB\\-dash\\fR option. \\fB\\-dashoffset\\fR is ignored if there is no\n\\fB\\-dash\\fR pattern. The \\fIoffset\\fR may have any of the forms described\nin the \\fBCOORDINATES\\fR section above.\n.\\\" OPTION: -fill\n.TP\n\\fB\\-fill \\fIcolor\\fR\n.\\\" OPTION: -activefill\n.TP\n\\fB\\-activefill \\fIcolor\\fR\n.\\\" OPTION: -disabledfill\n.TP\n\\fB\\-disabledfill \\fIcolor\\fR\n.\nThese options specify the color to be used to fill item's area.\nin its normal, active, and disabled states.\nThe even-odd fill rule is used.\n\\fIColor\\fR may have any of the forms accepted by \\fBTk_GetColor\\fR.\nFor the line item, it specifies the color of the line drawn.\nFor the text item, it specifies the foreground color of the text.\nIf \\fIcolor\\fR is an empty string (the default for all canvas items\nexcept line and text), then the item will not be filled.\n.\\\" OPTION: -outline\n.TP\n\\fB\\-outline \\fIcolor\\fR\n.\\\" OPTION: -activeoutline\n.TP\n\\fB\\-activeoutline \\fIcolor\\fR\n.\\\" OPTION: -disabledoutline\n.TP\n\\fB\\-disabledoutline \\fIcolor\\fR\n.\nThese options specify the color that should be used to draw the\noutline of the item in its normal, active and disabled states.\n\\fIColor\\fR may have any of the forms accepted by \\fBTk_GetColor\\fR.\nIf \\fIcolor\\fR is specified as an empty string then no outline is drawn\nfor the item.\n.\\\" OPTION: -offset\n.TP\n\\fB\\-offset \\fIoffset\\fR\n.\nSpecifies the offset of stipples. The offset value can be of the form\n\\fBx,y\\fR or \\fIside\\fR, where side can be \\fBn\\fR, \\fBne\\fR, \\fBe\\fR,\n\\fBse\\fR, \\fBs\\fR, \\fBsw\\fR, \\fBw\\fR, \\fBnw\\fR, or \\fBcenter\\fR. In the\nfirst case the origin is the origin of the toplevel of the current window.\nFor the canvas itself and canvas objects the origin is the canvas origin,\nbut putting \\fB#\\fR in front of the coordinate pair indicates using the\ntoplevel origin instead. For canvas objects, the \\fB\\-offset\\fR option is\nused for stippling as well. For the line and polygon canvas items you can\nalso specify an index as argument, which connects the stipple origin to one\nof the coordinate points of the line/polygon. Note that stipple offsets are\n\\fIonly supported on X11\\fR; they are silently ignored on other platforms.\n.\\\" OPTION: -outlinestipple\n.TP\n\\fB\\-outlinestipple \\fIbitmap\\fR\n.\\\" OPTION: -activeoutlinestipple\n.TP\n\\fB\\-activeoutlinestipple \\fIbitmap\\fR\n.\\\" OPTION: -disabledoutlinestipple\n.TP\n\\fB\\-disabledoutlinestipple \\fIbitmap\\fR\n.\nThese options specify stipple patterns that should be used to draw the\noutline of the item in its normal, active and disabled states.\nIndicates that the outline for the item should be drawn with a stipple pattern;\n\\fIbitmap\\fR specifies the stipple pattern to use, in any of the\nforms accepted by \\fBTk_GetBitmap\\fR.\nIf the \\fB\\-outline\\fR option has not been specified then this option\nhas no effect.\nIf \\fIbitmap\\fR is an empty string (the default), then the outline is drawn\nin a solid fashion.\n\\fINote that stipples are not well supported on platforms that do not\nuse X11 as their drawing API.\\fR\n.\\\" OPTION: -outlineoffset\n.TP\n\\fB\\-outlineoffset \\fIoffset\\fR\n.\nSpecifies the offset of the stipple pattern used for outlines, in the same way\nthat the \\fB\\-outline\\fR option controls fill stipples. (See the\n\\fB\\-outline\\fR option for a description of the syntax of \\fIoffset\\fR.)\n.\\\" OPTION: -stipple\n.TP\n\\fB\\-stipple \\fIbitmap\\fR\n.\\\" OPTION: -activestipple\n.TP\n\\fB\\-activestipple \\fIbitmap\\fR\n.\\\" OPTION: -disabledstipple\n.TP\n\\fB\\-disabledstipple \\fIbitmap\\fR\n.\nThese options specify stipple patterns that should be used to fill\nthe item in its normal, active and disabled states.\n\\fIbitmap\\fR specifies the stipple pattern to use, in any of the\nforms accepted by \\fBTk_GetBitmap\\fR.\nIf the \\fB\\-fill\\fR option has not been specified then this option\nhas no effect.\nIf \\fIbitmap\\fR is an empty string (the default), then filling is done\nin a solid fashion.\nFor the text item, it affects the actual text.\n\\fINote that stipples are not well supported on platforms that do not\nuse X11 as their drawing API.\\fR\n.\\\" OPTION: -state\n.TP\n\\fB\\-state \\fIstate\\fR\n.\nThis allows an item to override the canvas widget's global \\fIstate\\fR\noption. It takes the same values:\n\\fInormal\\fR, \\fIdisabled\\fR or \\fIhidden\\fR.\n.\\\" OPTION: -tags\n.TP\n\\fB\\-tags \\fItagList\\fR\n.\nSpecifies a set of tags to apply to the item.\n\\fITagList\\fR consists of a list of tag names, which replace any\nexisting tags for the item. \\fITagList\\fR may be an empty list.\n.\\\" OPTION: -width\n.TP\n\\fB\\-width \\fIoutlineWidth\\fR\n.\\\" OPTION: -activewidth\n.TP\n\\fB\\-activewidth \\fIoutlineWidth\\fR\n.\\\" OPTION: -disabledwidth\n.TP\n\\fB\\-disabledwidth \\fIoutlineWidth\\fR\n.\nThese options specify the width of the outline to be drawn around\nthe item's region, in its normal, active and disabled states.\n\\fIoutlineWidth\\fR may be in any of the forms described in the\n\\fBCOORDINATES\\fR section above.\nIf the \\fB\\-outline\\fR option has been specified as an empty string then\nthis option has no effect. This option defaults to 1.0.\nFor arcs, wide outlines will be drawn centered on the edges of the\narc's region.\n.SH \"STANDARD ITEM TYPES\"\n.SS \"ARC ITEMS\"\n.PP\nItems of type \\fBarc\\fR appear on the display as arc-shaped regions.\nAn arc is a section of an oval delimited by two angles (specified\nby either the \\fB\\-start\\fR and \\fB\\-extent\\fR options or the \\fB\\-height\\fR\noption) and displayed in one of several ways (specified by the \\fB\\-style\\fR\noption).\nArcs are created with widget commands of the following form:\n.CS\n\\fIpathName \\fBcreate arc \\fIx1 y1 x2 y2 \\fR?\\fIoption value ...\\fR?\n\\fIpathName \\fBcreate arc \\fIcoordList\\fR ?\\fIoption value ...\\fR?\n.CE\nThe arguments \\fIx1\\fR, \\fIy1\\fR, \\fIx2\\fR, and \\fIy2\\fR or \\fIcoordList\\fR give\nthe coordinates of two diagonally opposite corners of a\nrectangular region enclosing the oval that defines the arc (except when\n\\fB\\-height\\fR is specified - see below).\n.\nAfter the coordinates there may be any number of \\fIoption\\fR\\-\\fIvalue\\fR\npairs, each of which sets one of the configuration options\nfor the item. These same \\fIoption\\fR\\-\\fIvalue\\fR pairs may be\nused in \\fBitemconfigure\\fR widget commands to change the item's\nconfiguration. An arc item becomes the current item when the mouse pointer is\nover any part that is painted or (when fully transparent) that would be\npainted if both the \\fB\\-fill\\fR and \\fB\\-outline\\fR options were non-empty.\n.PP\nThe following standard options are supported by arcs:\n.DS\n.ta 3i\n\\fB\\-dash\\fR\t\\fB\\-activedash\\fR\n\\fB\\-disableddash\\fR\t\\fB\\-dashoffset\\fR\n\\fB\\-fill\\fR\t\\fB\\-activefill\\fR\n\\fB\\-disabledfill\\fR\t\\fB\\-offset\\fR\n\\fB\\-outline\\fR\t\\fB\\-activeoutline\\fR\n\\fB\\-disabledoutline\\fR\t\\fB\\-outlineoffset\\fR\n\\fB\\-outlinestipple\\fR\t\\fB\\-activeoutlinestipple\\fR\n\\fB\\-disabledoutlinestipple\\fR\t\\fB\\-stipple\\fR\n\\fB\\-activestipple\\fR\t\\fB\\-disabledstipple\\fR\n\\fB\\-state\\fR\t\\fB\\-tags\\fR\n\\fB\\-width\\fR\t\\fB\\-activewidth\\fR\n\\fB\\-disabledwidth\\fR\n.DE\nThe following extra options are supported for arcs:\n.\\\" OPTION: -extent\n.TP\n\\fB\\-extent \\fIdegrees\\fR\n.\nSpecifies the size of the angular range occupied by the arc.\nThe arc's range extends for \\fIdegrees\\fR degrees counter-clockwise\nfrom the starting angle given by the \\fB\\-start\\fR option.\n\\fIDegrees\\fR may be negative.\nIf it is greater than 360 or less than \\-360, then \\fIdegrees\\fR\nmodulo 360 is used as the extent.\n.\\\" OPTION: -start\n.TP\n\\fB\\-start \\fIdegrees\\fR\n.\nSpecifies the beginning of the angular range occupied by the\narc.\n\\fIDegrees\\fR is given in units of degrees measured counter-clockwise\nfrom the 3-o'clock position; it may be either positive or negative.\n.\\\" OPTION: -height\n.TP\n\\fB\\-height \\fIdistance\\fR\n.\nProvides a shortcut for creating a circular arc segment by defining the\ndistance of the mid-point of the arc from its chord. When this option\nis used the coordinates are interpreted as the start and end coordinates\nof the chord, and the options \\fB\\-start\\fR and \\fB\\-extent\\fR are ignored.\nThe value of \\fIdistance\\fR has the following meaning:\n.RS\n.PP\n.RS\n\\fIdistance\\fR > 0 creates a clockwise arc\n.br\n\\fIdistance\\fR < 0 creates an counter-clockwise arc\n.br\n\\fIdistance\\fR = 0 creates an arc as if this option had not been specified\n.RE\n.PP\nIf you want the arc to have a specific radius, \\fIr\\fR, use the formula:\n.PP\n.RS\n\\fIdistance\\fR = \\fIr\\fR \\(+- sqrt(\\fIr\\fR**2 - (chordLength / 2)**2)\n.RE\n.PP\nchoosing the minus sign for the minor arc and the plus sign for the major arc.\n.PP\nNote that \\fBitemcget \\-height\\fR always returns 0 so that introspection code\ncan be kept simple.\n.RE\n.\\\" OPTION: -style\n.TP\n\\fB\\-style \\fItype\\fR\n.\nSpecifies how to draw the arc. If \\fItype\\fR is \\fBpieslice\\fR\n(the default) then the arc's region is defined by a section\nof the oval's perimeter plus two line segments, one between the center\nof the oval and each end of the perimeter section.\nIf \\fItype\\fR is \\fBchord\\fR then the arc's region is defined\nby a section of the oval's perimeter plus a single line segment\nconnecting the two end points of the perimeter section.\nIf \\fItype\\fR is \\fBarc\\fR then the arc's region consists of\na section of the perimeter alone.\nIn this last case the \\fB\\-fill\\fR option is ignored.\n.SS \"BITMAP ITEMS\"\n.PP\nItems of type \\fBbitmap\\fR appear on the display as images with\ntwo colors, foreground and background.\nBitmaps are created with widget commands of the following form:\n.CS\n\\fIpathName \\fBcreate bitmap \\fIx y \\fR?\\fIoption value ...\\fR?\n\\fIpathName \\fBcreate bitmap \\fIcoordList\\fR ?\\fIoption value ...\\fR?\n.CE\nThe arguments \\fIx\\fR and \\fIy\\fR or \\fIcoordList\\fR (which must have two\nelements) specify the coordinates of a\npoint used to position the bitmap on the display, as controlled by the\n\\fB\\-anchor\\fR option.\nAfter the coordinates there may be any number of \\fIoption\\fR\\-\\fIvalue\\fR\npairs, each of which sets one of the configuration options\nfor the item. These same \\fIoption\\fR\\-\\fIvalue\\fR pairs may be\nused in \\fBitemconfigure\\fR widget commands to change the item's\nconfiguration. A bitmap item becomes the current item when the mouse pointer\nis over any part of its bounding box.\n.PP\nThe following standard options are supported by bitmaps:\n.DS\n.ta 3i\n\\fB\\-anchor\\fR\t\\fB\\-state\\fR\n\\fB\\-tags\\fR\n.DE\nThe following extra options are supported for bitmaps:\n.\\\" OPTION: -background\n.TP\n\\fB\\-background \\fIcolor\\fR\n.\\\" OPTION: -activebackground\n.TP\n\\fB\\-activebackground \\fIcolor\\fR\n.\\\" OPTION: -disabledbackground\n.TP\n\\fB\\-disabledbackground \\fIcolor\\fR\n.\nSpecifies the color to use for each of the bitmap's\n.QW 0\nvalued pixels in its normal, active and disabled states.\n\\fIColor\\fR may have any of the forms accepted by \\fBTk_GetColor\\fR.\nIf this option is not specified, or if it is specified as an empty\nstring, then nothing is displayed where the bitmap pixels are 0; this\nproduces a transparent effect.\n.\\\" OPTION: -bitmap\n.TP\n\\fB\\-bitmap \\fIbitmap\\fR\n.\\\" OPTION: -activebitmap\n.TP\n\\fB\\-activebitmap \\fIbitmap\\fR\n.\\\" OPTION: -disabledbitmap\n.TP\n\\fB\\-disabledbitmap \\fIbitmap\\fR\n.\nThese options specify the bitmaps to display in the item in its normal,\nactive and disabled states.\n\\fIBitmap\\fR may have any of the forms accepted by \\fBTk_GetBitmap\\fR.\n.\\\" OPTION: -foreground\n.TP\n\\fB\\-foreground \\fIcolor\\fR\n.\\\" OPTION: -activeforeground\n.TP\n\\fB\\-activeforeground \\fIcolor\\fR\n.\\\" OPTION: -disabledforeground\n.TP\n\\fB\\-disabledforeground \\fIcolor\\fR\n.\nThese options specify the color to use for each of the bitmap's\n.QW 1\nvalued pixels in its normal, active and disabled states.\n\\fIColor\\fR may have any of the forms accepted by \\fBTk_GetColor\\fR.\n.SS \"IMAGE ITEMS\"\n.PP\nItems of type \\fBimage\\fR are used to display images on a\ncanvas.\nImages are created with widget commands of the following form:\n.CS\n\\fIpathName \\fBcreate image \\fIx y \\fR?\\fIoption value ...\\fR?\n\\fIpathName \\fBcreate image \\fIcoordList\\fR ?\\fIoption value ...\\fR?\n.CE\nThe arguments \\fIx\\fR and \\fIy\\fR or \\fIcoordList\\fR specify the coordinates of a\npoint used to position the image on the display, as controlled by the\n\\fB\\-anchor\\fR option.\nAfter the coordinates there may be any number of \\fIoption\\fR\\-\\fIvalue\\fR\npairs, each of which sets one of the configuration options\nfor the item. These same \\fIoption\\fR\\-\\fIvalue\\fR pairs may be\nused in \\fBitemconfigure\\fR widget commands to change the item's\nconfiguration. An image item becomes the current item when the mouse pointer\nis over any part of its bounding box.\n.PP\nThe following standard options are supported by images:\n.DS\n.ta 3i\n\\fB\\-anchor\\fR\t\\fB\\-state\\fR\n\\fB\\-tags\\fR\n.DE\nThe following extra options are supported for images:\n.\\\" OPTION: -image\n.TP\n\\fB\\-image \\fIname\\fR\n.\\\" OPTION: -activeimage\n.TP\n\\fB\\-activeimage \\fIname\\fR\n.\\\" OPTION: -disabledimage\n.TP\n\\fB\\-disabledimage \\fIname\\fR\n.\nSpecifies the name of the images to display in the item in is normal,\nactive and disabled states.\nThis image must have been created previously with the\n\\fBimage create\\fR command.\n.SS \"LINE ITEMS\"\n.PP\nItems of type \\fBline\\fR appear on the display as one or more connected\nline segments or curves.\nLine items support coordinate indexing operations using the \\fBdchars\\fR,\n\\fBindex\\fR and \\fBinsert\\fR widget commands.\nLines are created with widget commands of the following form:\n.CS\n\\fIpathName \\fBcreate line \\fIx1 y1... xn yn \\fR?\\fIoption value ...\\fR?\n\\fIpathName \\fBcreate line \\fIcoordList\\fR ?\\fIoption value ...\\fR?\n.CE\nThe arguments \\fIx1\\fR through \\fIyn\\fR or \\fIcoordList\\fR give\nthe coordinates for a series of two or more points that describe\na series of connected line segments.\nAfter the coordinates there may be any number of \\fIoption\\fR\\-\\fIvalue\\fR\npairs, each of which sets one of the configuration options\nfor the item. These same \\fIoption\\fR\\-\\fIvalue\\fR pairs may be\nused in \\fBitemconfigure\\fR widget commands to change the item's\nconfiguration. A line item is the current item whenever the mouse pointer is\nover any segment of the line, whether drawn or not and whether or not the line\nis smoothed.\n.PP\nThe following standard options are supported by lines:\n.DS\n.ta 3i\n\\fB\\-dash\\fR\t\\fB\\-activedash\\fR\n\\fB\\-disableddash\\fR\t\\fB\\-dashoffset\\fR\n\\fB\\-fill\\fR\t\\fB\\-activefill\\fR\n\\fB\\-disabledfill\\fR\t\\fB\\-stipple\\fR\n\\fB\\-activestipple\\fR\t\\fB\\-disabledstipple\\fR\n\\fB\\-state\\fR\t\\fB\\-tags\\fR\n\\fB\\-width\\fR\t\\fB\\-activewidth\\fR\n\\fB\\-disabledwidth\\fR\n.DE\nThe following extra options are supported for lines:\n.\\\" OPTION: -arrow\n.TP\n\\fB\\-arrow \\fIwhere\\fR\n.\nIndicates whether or not arrowheads are to be drawn at one or both\nends of the line.\n\\fIWhere\\fR must have one of the values \\fBnone\\fR (for no arrowheads),\n\\fBfirst\\fR (for an arrowhead at the first point of the line),\n\\fBlast\\fR (for an arrowhead at the last point of the line), or\n\\fBboth\\fR (for arrowheads at both ends).\nThis option defaults to \\fBnone\\fR.\nWhen requested to draw an arrowhead, Tk internally adjusts the corresponding\nline end point so that the rendered line ends at the neck of the arrowhead\nrather than at its tip so that the line doesn't extend past the edge of the\narrowhead. This may trigger a \\fBLeave\\fR event if the mouse is hovering this\nline end. Conversely, when removing an arrowhead Tk adjusts the corresponding\nline point the other way round, which may trigger an \\fBEnter\\fR event.\n.\\\" OPTION: -arrowshape\n.TP\n\\fB\\-arrowshape \\fIshape\\fR\n.\nThis option indicates how to draw arrowheads.\nThe \\fIshape\\fR argument must be a list with three elements, each\nspecifying a distance in any of the forms described in\nthe \\fBCOORDINATES\\fR section above.\nThe first element of the list gives the distance along the line\nfrom the neck of the arrowhead to its tip.\nThe second element gives the distance along the line from the\ntrailing points of the arrowhead to the tip, and the third\nelement gives the distance from the outside edge of the line to the\ntrailing points.\nIf this option is not specified then Tk picks a\n.QW reasonable\nshape.\n.\\\" OPTION: -capstyle\n.TP\n\\fB\\-capstyle \\fIstyle\\fR\n.\nSpecifies the ways in which caps are to be drawn at the endpoints\nof the line.\n\\fIStyle\\fR may have any of the forms accepted by \\fBTk_GetCapStyle\\fR\n(\\fBbutt\\fR, \\fBprojecting\\fR, or \\fBround\\fR).\nIf this option is not specified then it defaults to \\fBbutt\\fR.\nWhere arrowheads are drawn the cap style is ignored.\n.\\\" OPTION: -joinstyle\n.TP\n\\fB\\-joinstyle \\fIstyle\\fR\n.\nSpecifies the ways in which joints are to be drawn at the vertices\nof the line.\n\\fIStyle\\fR may have any of the forms accepted by \\fBTk_GetJoinStyle\\fR\n(\\fBbevel\\fR, \\fBmiter\\fR, or \\fBround\\fR).\nIf this option is not specified then it defaults to \\fBround\\fR.\nIf the line only contains two points then this option is\nirrelevant.\n.\\\" OPTION: -smooth\n.TP\n\\fB\\-smooth \\fIsmoothMethod\\fR\n.\n\\fIsmoothMethod\\fR must have one of the forms accepted by\n\\fBTcl_GetBoolean\\fR or a line smoothing method.\nOnly \\fBtrue\\fR and \\fBraw\\fR are\nsupported in the core (with \\fBbezier\\fR being an alias for \\fBtrue\\fR),\nbut more can be added at runtime. If a boolean\nfalse value or empty string is given, no smoothing is applied. A boolean\ntruth value assumes \\fBtrue\\fR smoothing.\nIf the smoothing method is \\fBtrue\\fR, this indicates that the line\nshould be drawn as a curve, rendered as a set of quadratic splines: one spline\nis drawn for the first and second line segments, one for the second\nand third, and so on. Straight-line segments can be generated within\na curve by duplicating the end-points of the desired line segment.\nIf the smoothing method is \\fBraw\\fR, this indicates that the line\nshould also be drawn as a curve but where the list of coordinates is\nsuch that the first coordinate pair (and every third coordinate pair\nthereafter) is a knot point on a cubic Bezier curve, and the other\ncoordinates are control points on the cubic Bezier curve. Straight\nline segments can be generated within a curve by making control points\nequal to their neighbouring knot points. If the last point is a\ncontrol point and not a knot point, the point is repeated (one or two\ntimes) so that it also becomes a knot point.\n.\\\" OPTION: -splinesteps\n.TP\n\\fB\\-splinesteps \\fInumber\\fR\n.\nSpecifies the degree of smoothness desired for curves: each spline\nwill be approximated with \\fInumber\\fR line segments. This\noption is ignored unless the \\fB\\-smooth\\fR option is true or \\fBraw\\fR.\n.SS \"OVAL ITEMS\"\n.PP\nItems of type \\fBoval\\fR appear as circular or oval regions on\nthe display. Each oval may have an outline, a fill, or\nboth. Ovals are created with widget commands of the\nfollowing form:\n.CS\n\\fIpathName \\fBcreate oval \\fIx1 y1 x2 y2 \\fR?\\fIoption value ...\\fR?\n\\fIpathName \\fBcreate oval \\fIcoordList\\fR ?\\fIoption value ...\\fR?\n.CE\nThe arguments \\fIx1\\fR, \\fIy1\\fR, \\fIx2\\fR, and \\fIy2\\fR or \\fIcoordList\\fR give\nthe coordinates of two diagonally opposite corners of a\nrectangular region enclosing the oval.\nThe oval will include the top and left edges of the rectangle\nnot the lower or right edges.\nIf the region is square then the resulting oval is circular;\notherwise it is elongated in shape.\nAfter the coordinates there may be any number of \\fIoption\\fR\\-\\fIvalue\\fR\npairs, each of which sets one of the configuration options\nfor the item. These same \\fIoption\\fR\\-\\fIvalue\\fR pairs may be\nused in \\fBitemconfigure\\fR widget commands to change the item's\nconfiguration. An oval item becomes the current item when the mouse pointer is\nover any part that is painted or (when fully transparent) that would be\npainted if both the \\fB\\-fill\\fR and \\fB\\-outline\\fR options were non-empty.\n.PP\nThe following standard options are supported by ovals:\n.DS\n.ta 3i\n\\fB\\-dash\\fR\t\\fB\\-activedash\\fR\n\\fB\\-disableddash\\fR\t\\fB\\-dashoffset\\fR\n\\fB\\-fill\\fR\t\\fB\\-activefill\\fR\n\\fB\\-disabledfill\\fR\t\\fB\\-offset\\fR\n\\fB\\-outline\\fR\t\\fB\\-activeoutline\\fR\n\\fB\\-disabledoutline\\fR\t\\fB\\-outlineoffset\\fR\n\\fB\\-outlinestipple\\fR\t\\fB\\-activeoutlinestipple\\fR\n\\fB\\-disabledoutlinestipple\\fR\t\\fB\\-stipple\\fR\n\\fB\\-activestipple\\fR\t\\fB\\-disabledstipple\\fR\n\\fB\\-state\\fR\t\\fB\\-tags\\fR\n\\fB\\-width\\fR\t\\fB\\-activewidth\\fR\n\\fB\\-disabledwidth\\fR\n.DE\nThere are no oval-specific options.\n.SS \"POLYGON ITEMS\"\n.PP\nItems of type \\fBpolygon\\fR appear as polygonal or curved filled regions\non the display.\nPolygon items support coordinate indexing operations using the \\fBdchars\\fR,\n\\fBindex\\fR and \\fBinsert\\fR widget commands.\nPolygons are created with widget commands of the following form:\n.CS\n\\fIpathName \\fBcreate polygon \\fIx1 y1 ... xn yn \\fR?\\fIoption value ...\\fR?\n\\fIpathName \\fBcreate polygon \\fIcoordList\\fR ?\\fIoption value ...\\fR?\n.CE\nThe arguments \\fIx1\\fR through \\fIyn\\fR or \\fIcoordList\\fR specify the\ncoordinates for three or more points that define a polygon.\nThe first point should not be repeated as the last to\nclose the shape; Tk will automatically close the periphery between\nthe first and last points.\nAfter the coordinates there may be any number of \\fIoption\\fR\\-\\fIvalue\\fR\npairs, each of which sets one of the configuration options\nfor the item. These same \\fIoption\\fR\\-\\fIvalue\\fR pairs may be\nused in \\fBitemconfigure\\fR widget commands to change the item's\nconfiguration. A polygon item is the current item whenever the mouse pointer\nis over any part of the polygon, whether drawn or not and whether or not the\noutline is smoothed.\n.PP\nThe following standard options are supported by polygons:\n.DS\n.ta 3i\n\\fB\\-dash\\fR\t\\fB\\-activedash\\fR\n\\fB\\-disableddash\\fR\t\\fB\\-dashoffset\\fR\n\\fB\\-fill\\fR\t\\fB\\-activefill\\fR\n\\fB\\-disabledfill\\fR\t\\fB\\-offset\\fR\n\\fB\\-outline\\fR\t\\fB\\-activeoutline\\fR\n\\fB\\-disabledoutline\\fR\t\\fB\\-outlineoffset\\fR\n\\fB\\-outlinestipple\\fR\t\\fB\\-activeoutlinestipple\\fR\n\\fB\\-disabledoutlinestipple\\fR\t\\fB\\-stipple\\fR\n\\fB\\-activestipple\\fR\t\\fB\\-disabledstipple\\fR\n\\fB\\-state\\fR\t\\fB\\-tags\\fR\n\\fB\\-width\\fR\t\\fB\\-activewidth\\fR\n\\fB\\-disabledwidth\\fR\n.DE\nThe following extra options are supported for polygons:\n.\\\" OPTION: -joinstyle\n.TP\n\\fB\\-joinstyle \\fIstyle\\fR\n.\nSpecifies the ways in which joints are to be drawn at the vertices\nof the outline.\n\\fIStyle\\fR may have any of the forms accepted by \\fBTk_GetJoinStyle\\fR\n(\\fBbevel\\fR, \\fBmiter\\fR, or \\fBround\\fR).\nIf this option is not specified then it defaults to \\fBround\\fR.\n.\\\" OPTION: -smooth\n.TP\n\\fB\\-smooth \\fIboolean\\fR\n.\n\\fIBoolean\\fR must have one of the forms accepted by \\fBTcl_GetBoolean\\fR\nor a line smoothing method. Only \\fBtrue\\fR and \\fBraw\\fR are\nsupported in the core (with \\fBbezier\\fR being an alias for \\fBtrue\\fR),\nbut more can be added at runtime. If a boolean\nfalse value or empty string is given, no smoothing is applied. A boolean\ntruth value assumes \\fBtrue\\fR smoothing.\nIf the smoothing method is \\fBtrue\\fR, this indicates that the polygon\nshould be drawn as a curve, rendered as a set of quadratic splines: one spline\nis drawn for the first and second line segments, one for the second\nand third, and so on. Straight-line segments can be generated within\na curve by duplicating the end-points of the desired line segment.\nIf the smoothing method is \\fBraw\\fR, this indicates that the polygon\nshould also be drawn as a curve but where the list of coordinates is\nsuch that the first coordinate pair (and every third coordinate pair\nthereafter) is a knot point on a cubic Bezier curve, and the other\ncoordinates are control points on the cubic Bezier curve. Straight\nline segments can be generated within a curve by making control points\nequal to their neighbouring knot points. If the last point is not the\nsecond point of a pair of control points, the point is repeated (one or two\ntimes) so that it also becomes the second point of a pair of control\npoints (the associated knot point will be the first control point).\n.\\\" OPTION: -splinesteps\n.TP\n\\fB\\-splinesteps \\fInumber\\fR\n.\nSpecifies the degree of smoothness desired for curves: each spline\nwill be approximated with \\fInumber\\fR line segments. This\noption is ignored unless the \\fB\\-smooth\\fR option is true or \\fBraw\\fR.\n.PP\nPolygon items are different from other items such as rectangles, ovals\nand arcs in that interior points are considered to be\n.QW inside\na polygon (e.g. for purposes of the \\fBfind closest\\fR and\n\\fBfind overlapping\\fR widget commands) even if it is not filled.\nFor most other item types, an\ninterior point is considered to be inside the item only if the item\nis filled or if it has neither a fill nor an outline. If you would\nlike an unfilled polygon whose interior points are not considered\nto be inside the polygon, use a line item instead.\n.SS \"RECTANGLE ITEMS\"\n.PP\nItems of type \\fBrectangle\\fR appear as rectangular regions on\nthe display. Each rectangle may have an outline, a fill, or\nboth. Rectangles are created with widget commands of the\nfollowing form:\n.CS\n\\fIpathName \\fBcreate rectangle \\fIx1 y1 x2 y2 \\fR?\\fIoption value ...\\fR?\n\\fIpathName \\fBcreate rectangle \\fIcoordList\\fR ?\\fIoption value ...\\fR?\n.CE\nThe arguments \\fIx1\\fR, \\fIy1\\fR, \\fIx2\\fR, and \\fIy2\\fR or \\fIcoordList\\fR\n(which must have four elements) give\nthe coordinates of two diagonally opposite corners of the rectangle\n(the rectangle will include its upper and left edges but not\nits lower or right edges).\nAfter the coordinates there may be any number of \\fIoption\\fR\\-\\fIvalue\\fR\npairs, each of which sets one of the configuration options\nfor the item. These same \\fIoption\\fR\\-\\fIvalue\\fR pairs may be\nused in \\fBitemconfigure\\fR widget commands to change the item's\nconfiguration. A rectangle item becomes the current item when the mouse\npointer is over any part that is painted or (when fully transparent) that\nwould be painted if both the \\fB\\-fill\\fR and \\fB\\-outline\\fR options were\nnon-empty.\n.PP\nThe following standard options are supported by rectangles:\n.DS\n.ta 3i\n\\fB\\-dash\\fR\t\\fB\\-activedash\\fR\n\\fB\\-disableddash\\fR\t\\fB\\-dashoffset\\fR\n\\fB\\-fill\\fR\t\\fB\\-activefill\\fR\n\\fB\\-disabledfill\\fR\t\\fB\\-offset\\fR\n\\fB\\-outline\\fR\t\\fB\\-activeoutline\\fR\n\\fB\\-disabledoutline\\fR\t\\fB\\-outlineoffset\\fR\n\\fB\\-outlinestipple\\fR\t\\fB\\-activeoutlinestipple\\fR\n\\fB\\-disabledoutlinestipple\\fR\t\\fB\\-stipple\\fR\n\\fB\\-activestipple\\fR\t\\fB\\-disabledstipple\\fR\n\\fB\\-state\\fR\t\\fB\\-tags\\fR\n\\fB\\-width\\fR\t\\fB\\-activewidth\\fR\n\\fB\\-disabledwidth\\fR\n.DE\nThere are no rectangle-specific options.\n.SS \"TEXT ITEMS\"\n.PP\nA text item displays a string of characters on the screen in one\nor more lines.\nText items support indexing, editing and selection through the \\fBdchars\\fR\nwidget command, the \\fBfocus\\fR widget command, the \\fBicursor\\fR widget\ncommand, the \\fBindex\\fR widget command, the \\fBinsert\\fR widget command, and\nthe \\fBselect\\fR widget command.\nText items are created with widget commands of the following\nform:\n.CS\n\\fIpathName \\fBcreate text \\fIx y \\fR?\\fIoption value ...\\fR?\n\\fIpathName \\fBcreate text \\fIcoordList\\fR ?\\fIoption value ...\\fR?\n.CE\nThe arguments \\fIx\\fR and \\fIy\\fR or \\fIcoordList\\fR (which must have two\nelements) specify the coordinates of a\npoint used to position the text on the display (see the options\nbelow for more information on how text is displayed).\nAfter the coordinates there may be any number of \\fIoption\\fR\\-\\fIvalue\\fR\npairs, each of which sets one of the configuration options\nfor the item. These same \\fIoption\\fR\\-\\fIvalue\\fR pairs may be\nused in \\fBitemconfigure\\fR widget commands to change the item's\nconfiguration. A text item becomes the current item when the mouse pointer\nis over any part of its bounding box.\n.PP\nThe following standard options are supported by text items:\n.DS\n.ta 3i\n\\fB\\-anchor\\fR\t\\fB\\-fill\\fR\n\\fB\\-activefill\\fR\t\\fB\\-disabledfill\\fR\n\\fB\\-stipple\\fR\t\\fB\\-activestipple\\fR\n\\fB\\-disabledstipple\\fR\t\\fB\\-state\\fR\n\\fB\\-tags\\fR\n.DE\nThe following extra options are supported for text items:\n.\\\" OPTION: -angle\n.TP\n\\fB\\-angle \\fIrotationDegrees\\fR\n.\n\\fIRotationDegrees\\fR tells how many degrees to rotate the text anticlockwise\nabout the positioning point for the text; it may have any floating-point value\nfrom 0.0 to 360.0. For example, if \\fIrotationDegrees\\fR is \\fB90\\fR, then the\ntext will be drawn vertically from bottom to top.\nThis option defaults to \\fB0.0\\fR.\n.\\\" OPTION: -font\n.TP\n\\fB\\-font \\fIfontName\\fR\n.\nSpecifies the font to use for the text item.\n\\fIFontName\\fR may be any string acceptable to \\fBTk_GetFont\\fR.\nIf this option is not specified, it defaults to a system-dependent\nfont.\n.\\\" OPTION: -justify\n.TP\n\\fB\\-justify \\fIhow\\fR\n.\nSpecifies how to justify the text within its bounding region.\n\\fIHow\\fR must be one of the values \\fBleft\\fR, \\fBright\\fR,\nor \\fBcenter\\fR.\nThis option will only matter if the text is displayed as multiple\nlines.\nIf the option is omitted, it defaults to \\fBleft\\fR.\n.\\\" OPTION: -text\n.TP\n\\fB\\-text \\fIstring\\fR\n.\n\\fIString\\fR specifies the characters to be displayed in the text item.\nNewline characters cause line breaks.\nThe characters in the item may also be changed with the\n\\fBinsert\\fR and \\fBdelete\\fR widget commands.\nThis option defaults to an empty string.\n.\\\" OPTION: -underline\n.TP\n\\fB\\-underline \\fInumber\\fR\n.\nSpecifies the integer index of a character within the text to be\nunderlined. 0 corresponds to the first character of the text\ndisplayed, 1 to the next character, and so on. \\-1 means that no\nunderline should be drawn (if the whole text item is to be underlined,\nthe appropriate font should be used instead).\n.\\\" OPTION: -width\n.TP\n\\fB\\-width \\fIlineLength\\fR\n.\nSpecifies a maximum line length for the text, in any of the forms\ndescribed in the \\fBCOORDINATES\\fR section above.\nIf this option is zero (the default) the text is broken into\nlines only at newline characters.\nHowever, if this option is non-zero then any line that would\nbe longer than \\fIlineLength\\fR is broken just before a space\ncharacter to make the line shorter than \\fIlineLength\\fR; the\nspace character is treated as if it were a newline\ncharacter.\n.SS \"WINDOW ITEMS\"\n.PP\nItems of type \\fBwindow\\fR cause a particular window to be displayed\nat a given position on the canvas.\nWindow items are created with widget commands of the following form:\n.CS\n\\fIpathName \\fBcreate window \\fIx y \\fR?\\fIoption value ...\\fR?\n\\fIpathName \\fBcreate window \\fIcoordList\\fR ?\\fIoption value ...\\fR?\n.CE\nThe arguments \\fIx\\fR and \\fIy\\fR or \\fIcoordList\\fR (which must have two\nelements) specify the coordinates of a\npoint used to position the window on the display, as controlled by the\n\\fB\\-anchor\\fR option.\nAfter the coordinates there may be any number of \\fIoption\\fR\\-\\fIvalue\\fR\npairs, each of which sets one of the configuration options\nfor the item. These same \\fIoption\\fR\\-\\fIvalue\\fR pairs may be\nused in \\fBitemconfigure\\fR widget commands to change the item's\nconfiguration. Theoretically, a window item becomes the current item when the\nmouse pointer is over any part of its bounding box, but in practice this\ntypically does not happen because the mouse pointer ceases to be over the\ncanvas at that point.\n.PP\nThe following standard options are supported by window items:\n.DS\n.ta 3i\n\\fB\\-anchor\\fR\t\\fB\\-state\\fR\n\\fB\\-tags\\fR\n.DE\nThe following extra options are supported for window items:\n.\\\" OPTION: -height\n.TP\n\\fB\\-height \\fIpixels\\fR\n.\nSpecifies the height to assign to the item's window.\n\\fIPixels\\fR may have any of the\nforms described in the \\fBCOORDINATES\\fR section above.\nIf this option is not specified, or if it is specified as zero,\nthen the window is given whatever height it requests internally.\n.\\\" OPTION: -width\n.TP\n\\fB\\-width \\fIpixels\\fR\n.\nSpecifies the width to assign to the item's window.\n\\fIPixels\\fR may have any of the\nforms described in the \\fBCOORDINATES\\fR section above.\nIf this option is not specified, or if it is specified as zero,\nthen the window is given whatever width it requests internally.\n.\\\" OPTION: -window\n.TP\n\\fB\\-window \\fIpathName\\fR\n.\nSpecifies the window to associate with this item.\nThe window specified by \\fIpathName\\fR must either be a child of\nthe canvas widget or a child of some ancestor of the canvas widget.\n\\fIPathName\\fR may not refer to a top-level window.\n.PP\nNote that, due to restrictions in the ways that windows are managed, it is not\npossible to draw other graphical items (such as lines and images) on top\nof window items. A window item always obscures any graphics that\noverlap it, regardless of their order in the display list. Also note that\nwindow items, unlike other canvas items, are not clipped for display by their\ncontaining canvas's border, and are instead clipped by the parent widget of\nthe window specified by the \\fB\\-window\\fR option; when the parent widget is\nthe canvas, this means that the window item can overlap the canvas's border.\n.SH \"APPLICATION-DEFINED ITEM TYPES\"\n.PP\nIt is possible for individual applications to define new item\ntypes for canvas widgets using C code.\nSee the documentation for \\fBTk_CreateItemType\\fR.\n.SH BINDINGS\n.PP\nIn the current implementation, new canvases are not given any\ndefault behavior: you will have to execute explicit Tcl commands\nto give the canvas its behavior.\n.SH CREDITS\n.PP\nTk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's\n\\fIezd\\fR program. \\fIEzd\\fR provides structured graphics in a Scheme\nenvironment and preceded canvases by a year or two. Its simple\nmechanisms for placing and animating graphical objects inspired the\nfunctions of canvases.\n.SH \"SEE ALSO\"\nbind(n), font(n), image(n), scrollbar(n)\n.SH KEYWORDS\ncanvas, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" fill-column: 78\n'\\\" End:\n" }, { "path": "doc/checkbutton.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH checkbutton n 4.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ncheckbutton \\- Create and manipulate 'checkbutton' boolean selection widgets\n.SH SYNOPSIS\n\\fBcheckbutton\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-activebackground\t\\-disabledforeground\t\\-padx\n\\-activeforeground\t\\-font\t\\-pady\n\\-anchor\t\\-foreground\t\\-relief\n\\-background\t\\-highlightbackground\t\\-takefocus\n\\-bitmap\t\\-highlightcolor\t\\-text\n\\-borderwidth\t\\-highlightthickness\t\\-textvariable\n\\-compound\t\\-image\t\\-underline\n\\-cursor\t\\-justify\t\\-wraplength\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-command command Command\nSpecifies a Tcl command to associate with the button. This command\nis typically invoked when mouse button 1 is released over the button\nwindow. The button's global variable (\\fB\\-variable\\fR option) will\nbe updated before the command is invoked.\n.OP \\-height height Height\nSpecifies a desired height for the button.\nIf an image or bitmap is being displayed in the button then the value is in\nscreen units (i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR);\nfor text it is in lines of text.\nIf this option is not specified, the button's desired height is computed\nfrom the size of the image or bitmap or text being displayed in it.\n.OP \\-indicatoron indicatorOn IndicatorOn\nSpecifies whether or not the indicator should be drawn. Must be a\nproper boolean value. If false, the \\fB\\-relief\\fR option is\nignored and the widget's relief is always sunken if the widget is\nselected and raised otherwise.\n.OP \\-offrelief offRelief OffRelief\nSpecifies the relief for the checkbutton when the indicator is not drawn and\nthe checkbutton is off. The default value is\n.QW raised .\nBy setting this option to\n.QW flat\nand setting \\fB\\-indicatoron\\fR to false and \\fB\\-overrelief\\fR to\n.QW raised ,\nthe effect is achieved\nof having a flat button that raises on mouse-over and which is\ndepressed when activated. This is the behavior typically exhibited by\nthe Bold, Italic, and Underline checkbuttons on the toolbar of a\nword-processor, for example.\n.OP \\-offvalue offValue Value\nSpecifies value to store in the button's associated variable whenever\nthis button is deselected. Defaults to\n.QW 0 .\n.OP \\-onvalue onValue Value\nSpecifies value to store in the button's associated variable whenever\nthis button is selected. Defaults to\n.QW 1 .\n.OP \\-overrelief overRelief OverRelief\nSpecifies an alternative relief for the checkbutton, to be used when the\nmouse cursor is over the widget. This option can be used to make\ntoolbar buttons, by configuring \\fB\\-relief flat \\-overrelief\nraised\\fR. If the value of this option is the empty string, then no\nalternative relief is used when the mouse cursor is over the checkbutton.\nThe empty string is the default value.\n.OP \\-selectcolor selectColor Background\nSpecifies a background color to use when the button is selected.\nIf \\fBindicatorOn\\fR is true then the color is used as the background for\nthe indicator regardless of the select state.\nIf \\fBindicatorOn\\fR is false, this color is used as the background\nfor the entire widget, in place of \\fBbackground\\fR or \\fBactiveBackground\\fR,\nwhenever the widget is selected.\nIf specified as an empty string then no special color is used for\ndisplaying when the widget is selected.\n.OP \\-selectimage selectImage SelectImage\nSpecifies an image to display (in place of the \\fB\\-image\\fR option)\nwhen the checkbutton is selected.\nThis option is ignored unless the \\fB\\-image\\fR option has been\nspecified.\n.OP \\-state state State\nSpecifies one of three states for the checkbutton: \\fBnormal\\fR, \\fBactive\\fR,\nor \\fBdisabled\\fR. In normal state the checkbutton is displayed using the\n\\fB\\-foreground\\fR and \\fB\\-background\\fR options. The active state is\ntypically used when the pointer is over the checkbutton. In active state\nthe checkbutton is displayed using the \\fB\\-activeforeground\\fR and\n\\fB\\-activebackground\\fR options. Disabled state means that the checkbutton\nshould be insensitive: the default bindings will refuse to activate\nthe widget and will ignore mouse button presses.\nIn this state the \\fB\\-disabledforeground\\fR and\n\\fB\\-background\\fR options determine how the checkbutton is displayed.\n.OP \\-tristateimage tristateImage TristateImage\nSpecifies an image to display (in place of the \\fB\\-image\\fR option)\nwhen the checkbutton is in tri-state mode.\nThis option is ignored unless the \\fB\\-image\\fR option has been\nspecified.\n.OP \\-tristatevalue tristateValue Value\nSpecifies the value that causes the checkbutton to display the multi-value\nselection, also known as the tri-state mode. Defaults to\n.QW \"\" .\n.OP \\-variable variable Variable\nSpecifies the name of a global variable to set to indicate whether\nor not this button is selected. Defaults to the name of the\nbutton within its parent (i.e. the last element of the button\nwindow's path name).\n.OP \\-width width Width\nSpecifies a desired width for the button.\nIf an image or bitmap is being displayed in the button then the value is in\nscreen units (i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR);\nfor text it is in characters.\nIf this option is not specified, the button's desired width is computed\nfrom the size of the image or bitmap or text being displayed in it.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBcheckbutton\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a checkbutton widget.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the checkbutton such as its colors, font,\ntext, and initial relief. The \\fBcheckbutton\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nA checkbutton is a widget\nthat displays a textual string, bitmap or image\nand a square called an \\fIindicator\\fR.\nIf text is displayed, it must all be in a single font, but it\ncan occupy multiple lines on the screen (if it contains newlines\nor if wrapping occurs because of the \\fB\\-wraplength\\fR option) and\none of the characters may optionally be underlined using the\n\\fB\\-underline\\fR option.\nA checkbutton has\nall of the behavior of a simple button, including the\nfollowing: it can display itself in either of three different\nways, according to the \\fB\\-state\\fR option;\nit can be made to appear\nraised, sunken, or flat; it can be made to flash; and it invokes\na Tcl command whenever mouse button 1 is clicked over the\ncheckbutton.\n.PP\nIn addition, checkbuttons can be \\fIselected\\fR.\nIf a checkbutton is selected then the indicator is normally\ndrawn with a selected appearance, and\na Tcl variable associated with the checkbutton is set to a particular\nvalue (normally 1).\nThe indicator is drawn with a check mark inside.\nIf the checkbutton is not selected, then the indicator is drawn with a\ndeselected appearance, and the associated variable is\nset to a different value (typically 0).\nThe indicator is drawn without a check mark inside. In the special case\nwhere the variable (if specified) has a value that matches the tristatevalue,\nthe indicator is drawn with a tri-state appearance and is in the tri-state\nmode indicating mixed or multiple values. (This is used when the check\nbox represents the state of multiple items.)\nThe indicator is drawn in a platform dependent manner. Under Unix and\nWindows, the background interior of the box is\n.QW grayed .\nUnder Mac, the indicator is drawn with a dash mark inside.\nBy default, the name of the variable associated with a checkbutton is the\nsame as the \\fIname\\fR used to create the checkbutton.\nThe variable name, and the\n.QW on ,\n.QW off\nand\n.QW tristate\nvalues stored in it, may be modified with options on the command line\nor in the option database.\nConfiguration options may also be used to modify the way the\nindicator is displayed (or whether it is displayed at all).\nBy default a checkbutton is configured to select and deselect\nitself on alternate button clicks.\nIn addition, each checkbutton monitors its associated variable and\nautomatically selects and deselects itself when the variables value\nchanges to and from the button's\n.QW on ,\n.QW off\nand\n.QW tristate\nvalues.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBcheckbutton\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for checkbutton widgets:\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBcheckbutton\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBcheckbutton\\fR\ncommand.\n.\\\" METHOD: deselect\n.TP\n\\fIpathName \\fBdeselect\\fR\n.\nDeselects the checkbutton and sets the associated variable to its\n.QW off\nvalue.\n.\\\" METHOD: flash\n.TP\n\\fIpathName \\fBflash\\fR\n.\nFlashes the checkbutton. This is accomplished by redisplaying the checkbutton\nseveral times, alternating between active and normal colors. At\nthe end of the flash the checkbutton is left in the same normal/active\nstate as when the command was invoked.\nThis command is ignored if the checkbutton's state is \\fBdisabled\\fR.\n.\\\" METHOD: invoke\n.TP\n\\fIpathName \\fBinvoke\\fR\n.\nDoes just what would have happened if the user invoked the checkbutton\nwith the mouse: toggle the selection state of the button and invoke\nthe Tcl command associated with the checkbutton, if there is one.\nThe return value is the return value from the Tcl command, or an\nempty string if there is no command associated with the checkbutton.\nThis command is ignored if the checkbutton's state is \\fBdisabled\\fR.\n.\\\" METHOD: select\n.TP\n\\fIpathName \\fBselect\\fR\n.\nSelects the checkbutton and sets the associated variable to its\n.QW on\nvalue.\n.\\\" METHOD: toggle\n.TP\n\\fIpathName \\fBtoggle\\fR\n.\nToggles the selection state of the button, redisplaying it and\nmodifying its associated variable to reflect the new state.\n.SH BINDINGS\n.PP\nTk automatically creates class bindings for checkbuttons that give them\nthe following default behavior:\n.IP [1]\nOn Unix systems, a checkbutton activates whenever the mouse passes\nover it and deactivates whenever the mouse leaves the checkbutton. On\nMac and Windows systems, when mouse button 1 is pressed over a\ncheckbutton, the button activates whenever the mouse pointer is inside\nthe button, and deactivates whenever the mouse pointer leaves the\nbutton.\n.IP [2]\nWhen mouse button 1 is pressed over a checkbutton, it is invoked (its\nselection state toggles and the command associated with the button is\ninvoked, if there is one).\n.IP [3]\nWhen a checkbutton has the input focus, the space key causes the checkbutton\nto be invoked. Under Windows, there are additional key bindings; plus\n(\\fB+\\fR) and equal (\\fB=\\fR) select the button, and minus (\\fB\\-\\fR)\ndeselects the button.\n.PP\nIf the checkbutton's state is \\fBdisabled\\fR then none of the above\nactions occur: the checkbutton is completely non-responsive.\n.PP\nThe behavior of checkbuttons can be changed by defining new bindings for\nindividual widgets or by redefining the class bindings.\n.SH EXAMPLE\n.PP\nThis example shows a group of uncoupled checkbuttons.\n.PP\n.CS\nlabelframe .lbl -text \"Steps:\"\n\\fBcheckbutton\\fR .c1 -text Lights -variable lights\n\\fBcheckbutton\\fR .c2 -text Cameras -variable cameras\n\\fBcheckbutton\\fR .c3 -text Action! -variable action\npack .c1 .c2 .c3 -in .lbl\npack .lbl\n.CE\n.SH \"SEE ALSO\"\nbutton(n), options(n), radiobutton(n), ttk::checkbutton(n)\n.SH KEYWORDS\ncheckbutton, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/chooseColor.n", "content": "'\\\"\n'\\\" Copyright (c) 1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk_chooseColor n 4.2 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk_chooseColor \\- pops up a dialog box for the user to select a color.\n.SH SYNOPSIS\n\\fBtk_chooseColor \\fR?\\fIoption value ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe procedure \\fBtk_chooseColor\\fR pops up a dialog box for the\nuser to select a color. The following \\fIoption\\-value\\fR pairs are\npossible as command line arguments:\n.\\\" OPTION: -initialcolor\n.TP\n\\fB\\-initialcolor\\fI color\\fR\n.\nSpecifies the color to display in the color dialog when it pops\nup. \\fIcolor\\fR must be in a form acceptable to the \\fBTk_GetColor\\fR\nfunction.\n.\\\" OPTION: -parent\n.TP\n\\fB\\-parent\\fI window\\fR\n.\nMakes \\fIwindow\\fR the logical parent of the color dialog. The color\ndialog is displayed on top of its parent window.\n.\\\" OPTION: -title\n.TP\n\\fB\\-title\\fI titleString\\fR\n.\nSpecifies a string to display as the title of the dialog box. If this\noption is not specified, then a default title will be displayed.\n.LP\nIf the user selects a color, \\fBtk_chooseColor\\fR will return the\nname of the color in a form acceptable to \\fBTk_GetColor\\fR. If the\nuser cancels the operation, both commands will return the empty\nstring.\n.SH EXAMPLE\n.PP\n.CS\nbutton .b -bg [tk_chooseColor -initialcolor gray -title \"Choose color\"]\n.CE\n.SH KEYWORDS\ncolor, color selection, dialog\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/chooseDirectory.n", "content": "'\\\"\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" All rights reserved.\n'\\\"\n.TH tk_chooseDirectory n 8.3 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk_chooseDirectory \\- pops up a dialog box for the user to select a directory.\n.SH SYNOPSIS\n\\fBtk_chooseDirectory \\fR?\\fIoption value ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe procedure \\fBtk_chooseDirectory\\fR pops up a dialog box for the\nuser to select a directory. The following \\fIoption\\-value\\fR pairs are\npossible as command line arguments:\n.\\\" OPTION: -command\n.TP\n\\fB\\-command\\fI string\\fR\n.\nSpecifies the prefix of a Tcl command to invoke when the user closes the\ndialog after having selected an item. This callback is not called if the\nuser cancelled the dialog. The actual command consists of \\fIstring\\fR\nfollowed by a space and the value selected by the user in the dialog. This\nis only available on macOS.\n.\\\" OPTION: -initialdir\n.TP\n\\fB\\-initialdir\\fI dirname\\fR\n.\nSpecifies that the directories in \\fIdirectory\\fR should be displayed\nwhen the dialog pops up. If this parameter is not specified,\nthe initial directory defaults to the current working directory\non non-Windows systems and on Windows systems prior to Vista.\nOn Vista and later systems, the initial directory defaults to the last\nuser-selected directory for the application. If the\nparameter specifies a relative path, the return value will convert the\nrelative path to an absolute path.\n.\\\" OPTION: -message\n.TP\n\\fB\\-message\\fI string\\fR\n.\nSpecifies a message to include in the client area of the dialog.\nThis is only available on macOS.\n.\\\" OPTION: -mustexist\n.TP\n\\fB\\-mustexist\\fI boolean\\fR\n.\nSpecifies whether the user may specify non-existent directories. If\nthis parameter is true, then the user may only select directories that\nalready exist. The default value is \\fIfalse\\fR.\n.\\\" OPTION: -parent\n.TP\n\\fB\\-parent\\fI window\\fR\n.\nMakes \\fIwindow\\fR the logical parent of the dialog. The dialog\nis displayed on top of its parent window. On macOS, this\nturns the file dialog into a sheet attached to the parent window.\n.\\\" OPTION: -title\n.TP\n\\fB\\-title\\fI titleString\\fR\n.\nSpecifies a string to display as the title of the dialog box. If this\noption is not specified, then a default title will be displayed.\n.SH EXAMPLE\n.PP\n.CS\nset dir [\\fBtk_chooseDirectory\\fR \\e\n -initialdir ~ -title \"Choose a directory\"]\nif {$dir eq \"\"} {\n label .l -text \"No directory selected\"\n} else {\n label .l -text \"Selected $dir\"\n}\n.CE\n.SH \"SEE ALSO\"\ntk_getOpenFile(n), tk_getSaveFile(n)\n.SH KEYWORDS\ndirectory, selection, dialog, platform-specific\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/clipboard.n", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH clipboard n 8.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nclipboard \\- Manipulate Tk clipboard\n.SH SYNOPSIS\n\\fBclipboard \\fIoption\\fR ?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThis command provides a Tcl interface to the Tk clipboard,\nwhich stores data for later retrieval using the selection mechanism\n(via the \\fB\\-selection CLIPBOARD\\fR option).\nIn order to copy data into the clipboard, \\fBclipboard clear\\fR must\nbe called, followed by a sequence of one or more calls to \\fBclipboard\nappend\\fR. To ensure that the clipboard is updated atomically, all\nappends should be completed before returning to the event loop.\n.PP\nThe first argument to \\fBclipboard\\fR determines the format of the\nrest of the arguments and the behavior of the command. The following\nforms are currently supported:\n.\\\" METHOD: append\n.TP\n\\fBclipboard append\\fR ?\\fB\\-displayof\\fI window\\fR? ?\\fB\\-format\\fI format\\fR? ?\\fB\\-type\\fI type\\fR? ?\\fB\\-\\|\\-\\fR? \\fIdata\\fR\n.\nAppends \\fIdata\\fR to the clipboard on \\fIwindow\\fR's\ndisplay in the form given by \\fItype\\fR with the representation given\nby \\fIformat\\fR and claims ownership of the clipboard on \\fIwindow\\fR's\ndisplay.\n.RS\n.PP\n\\fIType\\fR specifies the form in which the selection is to be returned\n(the desired\n.QW target\nfor conversion, in ICCCM terminology), and\nshould be an atom name such as \\fBSTRING\\fR or \\fBFILE_NAME\\fR; see the\nInter-Client Communication Conventions Manual for complete details.\n\\fIType\\fR defaults to \\fBSTRING\\fR.\n.PP\nThe \\fIformat\\fR argument specifies the representation that should be\nused to transmit the selection to the requester (the second column of\nTable 2 of the ICCCM), and defaults to \\fBSTRING\\fR. If \\fIformat\\fR is\n\\fBSTRING\\fR, the selection is transmitted as 8-bit ASCII characters. If\n\\fIformat\\fR is \\fBATOM\\fR, then the \\fIdata\\fR is\ndivided into fields separated by white space; each field is converted\nto its atom value, and the 32-bit atom value is transmitted instead of\nthe atom name. For any other \\fIformat\\fR, \\fIdata\\fR is divided\ninto fields separated by white space and each\nfield is converted to a 32-bit integer; an array of integers is\ntransmitted to the selection requester. Note that strings passed to\n\\fBclipboard append\\fR are concatenated before conversion, so the\ncaller must take care to ensure appropriate spacing across string\nboundaries. All items appended to the clipboard with the same\n\\fItype\\fR must have the same \\fIformat\\fR.\n.PP\nThe \\fIformat\\fR argument is needed only for compatibility with\nclipboard requesters that do not use Tk. If the Tk toolkit is being\nused to retrieve the \\fBCLIPBOARD\\fR selection then the value is\nconverted back to a string at the requesting end, so \\fIformat\\fR is\nirrelevant.\n.PP\nA \\fB\\-\\|\\-\\fR argument may be specified to mark the end of options: the\nnext argument will always be used as \\fIdata\\fR.\nThis feature may be convenient if, for example, \\fIdata\\fR starts\nwith a \\fB\\-\\fR.\n.RE\n.\\\" METHOD: clear\n.TP\n\\fBclipboard clear\\fR ?\\fB\\-displayof\\fI window\\fR?\n.\nClaims ownership of the clipboard on \\fIwindow\\fR's display and removes\nany previous contents. \\fIWindow\\fR defaults to\n.QW . .\nReturns an empty string.\n.\\\" METHOD: get\n.TP\n\\fBclipboard get\\fR ?\\fB\\-displayof\\fI window\\fR? ?\\fB\\-type\\fI type\\fR?\n.\nRetrieve data from the clipboard on \\fIwindow\\fR's display.\n\\fIWindow\\fR defaults to\n.QW . .\n\\fIType\\fR specifies the form in which\nthe data is to be returned and should be an atom name such as \\fBSTRING\\fR\nor \\fBFILE_NAME\\fR. \\fIType\\fR defaults to \\fBSTRING\\fR. This command is\nequivalent to\n.QW \"\\fBselection get\\fR \\fB\\-selection CLIPBOARD\\fR\" .\n.RS\n.PP\nNote that on modern X11 systems, the most useful type to retrieve for\ntransferred strings is not \\fBSTRING\\fR, but rather \\fBUTF8_STRING\\fR.\n.RE\n.SH EXAMPLES\n.PP\nGet the current contents of the clipboard.\n.CS\nif {[catch {\\fBclipboard get\\fR} contents]} {\n # There were no clipboard contents at all\n}\n.CE\n.PP\nSet the clipboard to contain a fixed string.\n.CS\n\\fBclipboard clear\\fR\n\\fBclipboard append\\fR \"some fixed string\"\n.CE\n.PP\nYou can put custom data into the clipboard by using a custom \\fB\\-type\\fR\noption. This is not necessarily portable, but can be very useful. The\nmethod of passing Tcl scripts this way is effective, but should be mixed\nwith safe interpreters in production code.\n.CS\n# This is a very simple canvas serializer;\n# it produces a script that recreates the item(s) when executed\nproc getItemConfig {canvas tag} {\n set script {}\n foreach item [$canvas find withtag $tag] {\n append script {$canvas create } [$canvas type $item]\n append script { } [$canvas coords $item] { }\n foreach config [$canvas itemconf $item] {\n lassign $config name - - - value\n append script [list $name $value] { }\n }\n append script \\en\n }\n return [string trim $script]\n}\n\n# Set up a binding on a canvas to cut and paste an item\nset c [canvas .c]\npack $c\n$c create text 150 30 -text \"cut and paste me\"\nbind $c <> {\n \\fBclipboard clear\\fR\n \\fBclipboard append -type\\fR TkCanvasItem \\e\n [getItemConfig %W current]\n # Delete because this is cut, not copy.\n %W delete current\n}\nbind $c <> {\n catch {\n set canvas %W\n eval [\\fBclipboard get -type\\fR TkCanvasItem]\n }\n}\n.CE\n.SH \"SEE ALSO\"\ninterp(n), selection(n)\n.SH KEYWORDS\nclear, format, clipboard, append, selection, type\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/colors.n", "content": "'\\\"\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" Copyright (c) 2003 ActiveState Corporation.\n'\\\" Copyright (c) 2006-2007 Daniel A. Steffen \n'\\\" Copyright (c) 2008 Donal K. Fellows\n'\\\"\n.TH colors n 8.3 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n.\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ncolors \\- symbolic color names recognized by Tk\n.BE\n.SH DESCRIPTION\n.PP\nTk recognizes many symbolic color names (e.g., \\fBred\\fR) when\nspecifying colors. The symbolic names recognized by Tk and their\n8-bit-per-channel RGB values are:\n.DS\n.ta 7.2cR 9.5cR 11cR\n\\fBName\\fR\t\\fBRed\\fR\t\\fBGreen\\fR\t\\fBBlue\\fR\nalice blue\t240\t248 \t255\nAliceBlue\t240\t248 \t255\nantique white\t250\t235 \t215\nAntiqueWhite\t250\t235 \t215\nAntiqueWhite1\t255\t239 \t219\nAntiqueWhite2\t238\t223 \t204\nAntiqueWhite3\t205\t192 \t176\nAntiqueWhite4\t139\t131 \t120\naqua\t0\t255\t255\naquamarine\t127\t255 \t212\naquamarine1\t127\t255 \t212\naquamarine2\t118\t238 \t198\naquamarine3\t102\t205 \t170\naquamarine4\t69\t139 \t116\nazure\t240\t255 \t255\nazure1\t240\t255 \t255\nazure2\t224\t238 \t238\nazure3\t193\t205 \t205\nazure4\t131\t139 \t139\nbeige\t245\t245 \t220\nbisque\t255\t228 \t196\nbisque1\t255\t228 \t196\nbisque2\t238\t213 \t183\nbisque3\t205\t183 \t158\nbisque4\t139\t125 \t107\nblack\t0\t0 \t0\nblanched almond\t255\t235 \t205\nBlanchedAlmond\t255\t235 \t205\nblue\t0\t0 \t255\nblue violet\t138\t43 \t226\nblue1\t0\t0 \t255\nblue2\t0\t0 \t238\nblue3\t0\t0 \t205\nblue4\t0\t0 \t139\nBlueViolet\t138\t43 \t226\nbrown\t165\t42 \t42\nbrown1\t255\t64 \t64\nbrown2\t238\t59 \t59\nbrown3\t205\t51 \t51\nbrown4\t139\t35 \t35\nburlywood\t222\t184 \t135\nburlywood1\t255\t211 \t155\nburlywood2\t238\t197 \t145\nburlywood3\t205\t170 \t125\nburlywood4\t139\t115 \t85\ncadet blue\t95\t158 \t160\nCadetBlue\t95\t158 \t160\nCadetBlue1\t152\t245 \t255\nCadetBlue2\t142\t229 \t238\nCadetBlue3\t122\t197 \t205\nCadetBlue4\t83\t134 \t139\nchartreuse\t127\t255 \t0\nchartreuse1\t127\t255 \t0\nchartreuse2\t118\t238 \t0\nchartreuse3\t102\t205 \t0\nchartreuse4\t69\t139 \t0\nchocolate\t210\t105 \t30\nchocolate1\t255\t127 \t36\nchocolate2\t238\t118 \t33\nchocolate3\t205\t102 \t29\nchocolate4\t139\t69 \t19\ncoral\t255\t127 \t80\ncoral1\t255\t114 \t86\ncoral2\t238\t106 \t80\ncoral3\t205\t91 \t69\ncoral4\t139\t62 \t47\ncornflower blue\t100\t149 \t237\nCornflowerBlue\t100\t149 \t237\ncornsilk\t255\t248 \t220\ncornsilk1\t255\t248 \t220\ncornsilk2\t238\t232 \t205\ncornsilk3\t205\t200 \t177\ncornsilk4\t139\t136 \t120\ncrimson\t220\t20\t60\ncyan\t0\t255 \t255\ncyan1\t0\t255 \t255\ncyan2\t0\t238 \t238\ncyan3\t0\t205 \t205\ncyan4\t0\t139 \t139\ndark blue\t0\t0 \t139\ndark cyan\t0\t139 \t139\ndark goldenrod\t184\t134 \t11\ndark gray\t169\t169 \t169\ndark green\t0\t100 \t0\ndark grey\t169\t169 \t169\ndark khaki\t189\t183 \t107\ndark magenta\t139\t0 \t139\ndark olive green\t85\t107 \t47\ndark orange\t255\t140 \t0\ndark orchid\t153\t50 \t204\ndark red\t139\t0 \t0\ndark salmon\t233\t150 \t122\ndark sea green\t143\t188 \t143\ndark slate blue\t72\t61 \t139\ndark slate gray\t47\t79 \t79\ndark slate grey\t47\t79 \t79\ndark turquoise\t0\t206 \t209\ndark violet\t148\t0 \t211\nDarkBlue\t0\t0 \t139\nDarkCyan\t0\t139 \t139\nDarkGoldenrod\t184\t134 \t11\nDarkGoldenrod1\t255\t185 \t15\nDarkGoldenrod2\t238\t173 \t14\nDarkGoldenrod3\t205\t149 \t12\nDarkGoldenrod4\t139\t101 \t8\nDarkGray\t169\t169 \t169\nDarkGreen\t0\t100 \t0\nDarkGrey\t169\t169 \t169\nDarkKhaki\t189\t183 \t107\nDarkMagenta\t139\t0 \t139\nDarkOliveGreen\t85\t107 \t47\nDarkOliveGreen1\t202\t255 \t112\nDarkOliveGreen2\t188\t238 \t104\nDarkOliveGreen3\t162\t205 \t90\nDarkOliveGreen4\t110\t139 \t61\nDarkOrange\t255\t140 \t0\nDarkOrange1\t255\t127 \t0\nDarkOrange2\t238\t118 \t0\nDarkOrange3\t205\t102 \t0\nDarkOrange4\t139\t69 \t0\nDarkOrchid\t153\t50 \t204\nDarkOrchid1\t191\t62 \t255\nDarkOrchid2\t178\t58 \t238\nDarkOrchid3\t154\t50 \t205\nDarkOrchid4\t104\t34 \t139\nDarkRed\t139\t0 \t0\nDarkSalmon\t233\t150 \t122\nDarkSeaGreen\t143\t188 \t143\nDarkSeaGreen1\t193\t255 \t193\nDarkSeaGreen2\t180\t238 \t180\nDarkSeaGreen3\t155\t205 \t155\nDarkSeaGreen4\t105\t139 \t105\nDarkSlateBlue\t72\t61 \t139\nDarkSlateGray\t47\t79 \t79\nDarkSlateGray1\t151\t255 \t255\nDarkSlateGray2\t141\t238 \t238\nDarkSlateGray3\t121\t205 \t205\nDarkSlateGray4\t82\t139 \t139\nDarkSlateGrey\t47\t79 \t79\nDarkTurquoise\t0\t206 \t209\nDarkViolet\t148\t0 \t211\ndeep pink\t255\t20 \t147\ndeep sky blue\t0\t191 \t255\nDeepPink\t255\t20 \t147\nDeepPink1\t255\t20 \t147\nDeepPink2\t238\t18 \t137\nDeepPink3\t205\t16 \t118\nDeepPink4\t139\t10 \t80\nDeepSkyBlue\t0\t191 \t255\nDeepSkyBlue1\t0\t191 \t255\nDeepSkyBlue2\t0\t178 \t238\nDeepSkyBlue3\t0\t154 \t205\nDeepSkyBlue4\t0\t104 \t139\ndim gray\t105\t105 \t105\ndim grey\t105\t105 \t105\nDimGray\t105\t105 \t105\nDimGrey\t105\t105 \t105\ndodger blue\t30\t144 \t255\nDodgerBlue\t30\t144 \t255\nDodgerBlue1\t30\t144 \t255\nDodgerBlue2\t28\t134 \t238\nDodgerBlue3\t24\t116 \t205\nDodgerBlue4\t16\t78 \t139\nfirebrick\t178\t34 \t34\nfirebrick1\t255\t48 \t48\nfirebrick2\t238\t44 \t44\nfirebrick3\t205\t38 \t38\nfirebrick4\t139\t26 \t26\nfloral white\t255\t250 \t240\nFloralWhite\t255\t250 \t240\nforest green\t34\t139 \t34\nForestGreen\t34\t139 \t34\nfuchsia\t255\t0\t255\ngainsboro\t220\t220 \t220\nghost white\t248\t248 \t255\nGhostWhite\t248\t248 \t255\ngold\t255\t215 \t0\ngold1\t255\t215 \t0\ngold2\t238\t201 \t0\ngold3\t205\t173 \t0\ngold4\t139\t117 \t0\ngoldenrod\t218\t165 \t32\ngoldenrod1\t255\t193 \t37\ngoldenrod2\t238\t180 \t34\ngoldenrod3\t205\t155 \t29\ngoldenrod4\t139\t105 \t20\ngray\t128\t128\t128\ngray0\t0\t0 \t0\ngray1\t3\t3 \t3\ngray2\t5\t5 \t5\ngray3\t8\t8 \t8\ngray4\t10\t10 \t10\ngray5\t13\t13 \t13\ngray6\t15\t15 \t15\ngray7\t18\t18 \t18\ngray8\t20\t20 \t20\ngray9\t23\t23 \t23\ngray10\t26\t26 \t26\ngray11\t28\t28 \t28\ngray12\t31\t31 \t31\ngray13\t33\t33 \t33\ngray14\t36\t36 \t36\ngray15\t38\t38 \t38\ngray16\t41\t41 \t41\ngray17\t43\t43 \t43\ngray18\t46\t46 \t46\ngray19\t48\t48 \t48\ngray20\t51\t51 \t51\ngray21\t54\t54 \t54\ngray22\t56\t56 \t56\ngray23\t59\t59 \t59\ngray24\t61\t61 \t61\ngray25\t64\t64 \t64\ngray26\t66\t66 \t66\ngray27\t69\t69 \t69\ngray28\t71\t71 \t71\ngray29\t74\t74 \t74\ngray30\t77\t77 \t77\ngray31\t79\t79 \t79\ngray32\t82\t82 \t82\ngray33\t84\t84 \t84\ngray34\t87\t87 \t87\ngray35\t89\t89 \t89\ngray36\t92\t92 \t92\ngray37\t94\t94 \t94\ngray38\t97\t97 \t97\ngray39\t99\t99 \t99\ngray40\t102\t102 \t102\ngray41\t105\t105 \t105\ngray42\t107\t107 \t107\ngray43\t110\t110 \t110\ngray44\t112\t112 \t112\ngray45\t115\t115 \t115\ngray46\t117\t117 \t117\ngray47\t120\t120 \t120\ngray48\t122\t122 \t122\ngray49\t125\t125 \t125\ngray50\t127\t127 \t127\ngray51\t130\t130 \t130\ngray52\t133\t133 \t133\ngray53\t135\t135 \t135\ngray54\t138\t138 \t138\ngray55\t140\t140 \t140\ngray56\t143\t143 \t143\ngray57\t145\t145 \t145\ngray58\t148\t148 \t148\ngray59\t150\t150 \t150\ngray60\t153\t153 \t153\ngray61\t156\t156 \t156\ngray62\t158\t158 \t158\ngray63\t161\t161 \t161\ngray64\t163\t163 \t163\ngray65\t166\t166 \t166\ngray66\t168\t168 \t168\ngray67\t171\t171 \t171\ngray68\t173\t173 \t173\ngray69\t176\t176 \t176\ngray70\t179\t179 \t179\ngray71\t181\t181 \t181\ngray72\t184\t184 \t184\ngray73\t186\t186 \t186\ngray74\t189\t189 \t189\ngray75\t191\t191 \t191\ngray76\t194\t194 \t194\ngray77\t196\t196 \t196\ngray78\t199\t199 \t199\ngray79\t201\t201 \t201\ngray80\t204\t204 \t204\ngray81\t207\t207 \t207\ngray82\t209\t209 \t209\ngray83\t212\t212 \t212\ngray84\t214\t214 \t214\ngray85\t217\t217 \t217\ngray86\t219\t219 \t219\ngray87\t222\t222 \t222\ngray88\t224\t224 \t224\ngray89\t227\t227 \t227\ngray90\t229\t229 \t229\ngray91\t232\t232 \t232\ngray92\t235\t235 \t235\ngray93\t237\t237 \t237\ngray94\t240\t240 \t240\ngray95\t242\t242 \t242\ngray96\t245\t245 \t245\ngray97\t247\t247 \t247\ngray98\t250\t250 \t250\ngray99\t252\t252 \t252\ngray100\t255\t255 \t255\ngreen\t0\t128 \t0\ngreen yellow\t173\t255 \t47\ngreen1\t0\t255 \t0\ngreen2\t0\t238 \t0\ngreen3\t0\t205 \t0\ngreen4\t0\t139 \t0\nGreenYellow\t173\t255 \t47\ngrey\t128\t128\t128\ngrey0\t0\t0 \t0\ngrey1\t3\t3 \t3\ngrey2\t5\t5 \t5\ngrey3\t8\t8 \t8\ngrey4\t10\t10 \t10\ngrey5\t13\t13 \t13\ngrey6\t15\t15 \t15\ngrey7\t18\t18 \t18\ngrey8\t20\t20 \t20\ngrey9\t23\t23 \t23\ngrey10\t26\t26 \t26\ngrey11\t28\t28 \t28\ngrey12\t31\t31 \t31\ngrey13\t33\t33 \t33\ngrey14\t36\t36 \t36\ngrey15\t38\t38 \t38\ngrey16\t41\t41 \t41\ngrey17\t43\t43 \t43\ngrey18\t46\t46 \t46\ngrey19\t48\t48 \t48\ngrey20\t51\t51 \t51\ngrey21\t54\t54 \t54\ngrey22\t56\t56 \t56\ngrey23\t59\t59 \t59\ngrey24\t61\t61 \t61\ngrey25\t64\t64 \t64\ngrey26\t66\t66 \t66\ngrey27\t69\t69 \t69\ngrey28\t71\t71 \t71\ngrey29\t74\t74 \t74\ngrey30\t77\t77 \t77\ngrey31\t79\t79 \t79\ngrey32\t82\t82 \t82\ngrey33\t84\t84 \t84\ngrey34\t87\t87 \t87\ngrey35\t89\t89 \t89\ngrey36\t92\t92 \t92\ngrey37\t94\t94 \t94\ngrey38\t97\t97 \t97\ngrey39\t99\t99 \t99\ngrey40\t102\t102 \t102\ngrey41\t105\t105 \t105\ngrey42\t107\t107 \t107\ngrey43\t110\t110 \t110\ngrey44\t112\t112 \t112\ngrey45\t115\t115 \t115\ngrey46\t117\t117 \t117\ngrey47\t120\t120 \t120\ngrey48\t122\t122 \t122\ngrey49\t125\t125 \t125\ngrey50\t127\t127 \t127\ngrey51\t130\t130 \t130\ngrey52\t133\t133 \t133\ngrey53\t135\t135 \t135\ngrey54\t138\t138 \t138\ngrey55\t140\t140 \t140\ngrey56\t143\t143 \t143\ngrey57\t145\t145 \t145\ngrey58\t148\t148 \t148\ngrey59\t150\t150 \t150\ngrey60\t153\t153 \t153\ngrey61\t156\t156 \t156\ngrey62\t158\t158 \t158\ngrey63\t161\t161 \t161\ngrey64\t163\t163 \t163\ngrey65\t166\t166 \t166\ngrey66\t168\t168 \t168\ngrey67\t171\t171 \t171\ngrey68\t173\t173 \t173\ngrey69\t176\t176 \t176\ngrey70\t179\t179 \t179\ngrey71\t181\t181 \t181\ngrey72\t184\t184 \t184\ngrey73\t186\t186 \t186\ngrey74\t189\t189 \t189\ngrey75\t191\t191 \t191\ngrey76\t194\t194 \t194\ngrey77\t196\t196 \t196\ngrey78\t199\t199 \t199\ngrey79\t201\t201 \t201\ngrey80\t204\t204 \t204\ngrey81\t207\t207 \t207\ngrey82\t209\t209 \t209\ngrey83\t212\t212 \t212\ngrey84\t214\t214 \t214\ngrey85\t217\t217 \t217\ngrey86\t219\t219 \t219\ngrey87\t222\t222 \t222\ngrey88\t224\t224 \t224\ngrey89\t227\t227 \t227\ngrey90\t229\t229 \t229\ngrey91\t232\t232 \t232\ngrey92\t235\t235 \t235\ngrey93\t237\t237 \t237\ngrey94\t240\t240 \t240\ngrey95\t242\t242 \t242\ngrey96\t245\t245 \t245\ngrey97\t247\t247 \t247\ngrey98\t250\t250 \t250\ngrey99\t252\t252 \t252\ngrey100\t255\t255 \t255\nhoneydew\t240\t255 \t240\nhoneydew1\t240\t255 \t240\nhoneydew2\t224\t238 \t224\nhoneydew3\t193\t205 \t193\nhoneydew4\t131\t139 \t131\nhot pink\t255\t105 \t180\nHotPink\t255\t105 \t180\nHotPink1\t255\t110 \t180\nHotPink2\t238\t106 \t167\nHotPink3\t205\t96 \t144\nHotPink4\t139\t58 \t98\nindian red\t205\t92 \t92\nIndianRed\t205\t92 \t92\nIndianRed1\t255\t106 \t106\nIndianRed2\t238\t99 \t99\nIndianRed3\t205\t85 \t85\nIndianRed4\t139\t58 \t58\nindigo\t75\t0\t130\nivory\t255\t255 \t240\nivory1\t255\t255 \t240\nivory2\t238\t238 \t224\nivory3\t205\t205 \t193\nivory4\t139\t139 \t131\nkhaki\t240\t230 \t140\nkhaki1\t255\t246 \t143\nkhaki2\t238\t230 \t133\nkhaki3\t205\t198 \t115\nkhaki4\t139\t134 \t78\nlavender\t230\t230 \t250\nlavender blush\t255\t240 \t245\nLavenderBlush\t255\t240 \t245\nLavenderBlush1\t255\t240 \t245\nLavenderBlush2\t238\t224 \t229\nLavenderBlush3\t205\t193 \t197\nLavenderBlush4\t139\t131 \t134\nlawn green\t124\t252 \t0\nLawnGreen\t124\t252 \t0\nlemon chiffon\t255\t250 \t205\nLemonChiffon\t255\t250 \t205\nLemonChiffon1\t255\t250 \t205\nLemonChiffon2\t238\t233 \t191\nLemonChiffon3\t205\t201 \t165\nLemonChiffon4\t139\t137 \t112\nlight blue\t173\t216 \t230\nlight coral\t240\t128 \t128\nlight cyan\t224\t255 \t255\nlight goldenrod\t238\t221 \t130\nlight goldenrod yellow\t250\t250 \t210\nlight gray\t211\t211 \t211\nlight green\t144\t238 \t144\nlight grey\t211\t211 \t211\nlight pink\t255\t182 \t193\nlight salmon\t255\t160 \t122\nlight sea green\t32\t178 \t170\nlight sky blue\t135\t206 \t250\nlight slate blue\t132\t112 \t255\nlight slate gray\t119\t136 \t153\nlight slate grey\t119\t136 \t153\nlight steel blue\t176\t196 \t222\nlight yellow\t255\t255 \t224\nLightBlue\t173\t216 \t230\nLightBlue1\t191\t239 \t255\nLightBlue2\t178\t223 \t238\nLightBlue3\t154\t192 \t205\nLightBlue4\t104\t131 \t139\nLightCoral\t240\t128 \t128\nLightCyan\t224\t255 \t255\nLightCyan1\t224\t255 \t255\nLightCyan2\t209\t238 \t238\nLightCyan3\t180\t205 \t205\nLightCyan4\t122\t139 \t139\nLightGoldenrod\t238\t221 \t130\nLightGoldenrod1\t255\t236 \t139\nLightGoldenrod2\t238\t220 \t130\nLightGoldenrod3\t205\t190 \t112\nLightGoldenrod4\t139\t129 \t76\nLightGoldenrodYellow\t250\t250 \t210\nLightGray\t211\t211 \t211\nLightGreen\t144\t238 \t144\nLightGrey\t211\t211 \t211\nLightPink\t255\t182 \t193\nLightPink1\t255\t174 \t185\nLightPink2\t238\t162 \t173\nLightPink3\t205\t140 \t149\nLightPink4\t139\t95 \t101\nLightSalmon\t255\t160 \t122\nLightSalmon1\t255\t160 \t122\nLightSalmon2\t238\t149 \t114\nLightSalmon3\t205\t129 \t98\nLightSalmon4\t139\t87 \t66\nLightSeaGreen\t32\t178 \t170\nLightSkyBlue\t135\t206 \t250\nLightSkyBlue1\t176\t226 \t255\nLightSkyBlue2\t164\t211 \t238\nLightSkyBlue3\t141\t182 \t205\nLightSkyBlue4\t96\t123 \t139\nLightSlateBlue\t132\t112 \t255\nLightSlateGray\t119\t136 \t153\nLightSlateGrey\t119\t136 \t153\nLightSteelBlue\t176\t196 \t222\nLightSteelBlue1\t202\t225 \t255\nLightSteelBlue2\t188\t210 \t238\nLightSteelBlue3\t162\t181 \t205\nLightSteelBlue4\t110\t123 \t139\nLightYellow\t255\t255 \t224\nLightYellow1\t255\t255 \t224\nLightYellow2\t238\t238 \t209\nLightYellow3\t205\t205 \t180\nLightYellow4\t139\t139 \t122\nlime\t0\t255\t0\nlime green\t50\t205 \t50\nLimeGreen\t50\t205 \t50\nlinen\t250\t240 \t230\nmagenta\t255\t0 \t255\nmagenta1\t255\t0 \t255\nmagenta2\t238\t0 \t238\nmagenta3\t205\t0 \t205\nmagenta4\t139\t0 \t139\nmaroon\t128\t0 \t0\nmaroon1\t255\t52 \t179\nmaroon2\t238\t48 \t167\nmaroon3\t205\t41 \t144\nmaroon4\t139\t28 \t98\nmedium aquamarine\t102\t205 \t170\nmedium blue\t0\t0 \t205\nmedium orchid\t186\t85 \t211\nmedium purple\t147\t112 \t219\nmedium sea green\t60\t179 \t113\nmedium slate blue\t123\t104 \t238\nmedium spring green\t0\t250 \t154\nmedium turquoise\t72\t209 \t204\nmedium violet red\t199\t21 \t133\nMediumAquamarine\t102\t205 \t170\nMediumBlue\t0\t0 \t205\nMediumOrchid\t186\t85 \t211\nMediumOrchid1\t224\t102 \t255\nMediumOrchid2\t209\t95 \t238\nMediumOrchid3\t180\t82 \t205\nMediumOrchid4\t122\t55 \t139\nMediumPurple\t147\t112 \t219\nMediumPurple1\t171\t130 \t255\nMediumPurple2\t159\t121 \t238\nMediumPurple3\t137\t104 \t205\nMediumPurple4\t93\t71 \t139\nMediumSeaGreen\t60\t179 \t113\nMediumSlateBlue\t123\t104 \t238\nMediumSpringGreen\t0\t250 \t154\nMediumTurquoise\t72\t209 \t204\nMediumVioletRed\t199\t21 \t133\nmidnight blue\t25\t25 \t112\nMidnightBlue\t25\t25 \t112\nmint cream\t245\t255 \t250\nMintCream\t245\t255 \t250\nmisty rose\t255\t228 \t225\nMistyRose\t255\t228 \t225\nMistyRose1\t255\t228 \t225\nMistyRose2\t238\t213 \t210\nMistyRose3\t205\t183 \t181\nMistyRose4\t139\t125 \t123\nmoccasin\t255\t228 \t181\nnavajo white\t255\t222 \t173\nNavajoWhite\t255\t222 \t173\nNavajoWhite1\t255\t222 \t173\nNavajoWhite2\t238\t207 \t161\nNavajoWhite3\t205\t179 \t139\nNavajoWhite4\t139\t121 \t94\nnavy\t0\t0 \t128\nnavy blue\t0\t0 \t128\nNavyBlue\t0\t0 \t128\nold lace\t253\t245 \t230\nOldLace\t253\t245 \t230\nolive\t128\t128\t0\nolive drab\t107\t142 \t35\nOliveDrab\t107\t142 \t35\nOliveDrab1\t192\t255 \t62\nOliveDrab2\t179\t238 \t58\nOliveDrab3\t154\t205 \t50\nOliveDrab4\t105\t139 \t34\norange\t255\t165 \t0\norange red\t255\t69 \t0\norange1\t255\t165 \t0\norange2\t238\t154 \t0\norange3\t205\t133 \t0\norange4\t139\t90 \t0\nOrangeRed\t255\t69 \t0\nOrangeRed1\t255\t69 \t0\nOrangeRed2\t238\t64 \t0\nOrangeRed3\t205\t55 \t0\nOrangeRed4\t139\t37 \t0\norchid\t218\t112 \t214\norchid1\t255\t131 \t250\norchid2\t238\t122 \t233\norchid3\t205\t105 \t201\norchid4\t139\t71 \t137\npale goldenrod\t238\t232 \t170\npale green\t152\t251 \t152\npale turquoise\t175\t238 \t238\npale violet red\t219\t112 \t147\nPaleGoldenrod\t238\t232 \t170\nPaleGreen\t152\t251 \t152\nPaleGreen1\t154\t255 \t154\nPaleGreen2\t144\t238 \t144\nPaleGreen3\t124\t205 \t124\nPaleGreen4\t84\t139 \t84\nPaleTurquoise\t175\t238 \t238\nPaleTurquoise1\t187\t255 \t255\nPaleTurquoise2\t174\t238 \t238\nPaleTurquoise3\t150\t205 \t205\nPaleTurquoise4\t102\t139 \t139\nPaleVioletRed\t219\t112 \t147\nPaleVioletRed1\t255\t130 \t171\nPaleVioletRed2\t238\t121 \t159\nPaleVioletRed3\t205\t104 \t127\nPaleVioletRed4\t139\t71 \t93\npapaya whip\t255\t239 \t213\nPapayaWhip\t255\t239 \t213\npeach puff\t255\t218 \t185\nPeachPuff\t255\t218 \t185\nPeachPuff1\t255\t218 \t185\nPeachPuff2\t238\t203 \t173\nPeachPuff3\t205\t175 \t149\nPeachPuff4\t139\t119 \t101\nperu\t205\t133 \t63\npink\t255\t192 \t203\npink1\t255\t181 \t197\npink2\t238\t169 \t184\npink3\t205\t145 \t158\npink4\t139\t99 \t108\nplum\t221\t160 \t221\nplum1\t255\t187 \t255\nplum2\t238\t174 \t238\nplum3\t205\t150 \t205\nplum4\t139\t102 \t139\npowder blue\t176\t224 \t230\nPowderBlue\t176\t224 \t230\npurple\t128\t0 \t128\npurple1\t155\t48 \t255\npurple2\t145\t44 \t238\npurple3\t125\t38 \t205\npurple4\t85\t26 \t139\nred\t255\t0 \t0\nred1\t255\t0 \t0\nred2\t238\t0 \t0\nred3\t205\t0 \t0\nred4\t139\t0 \t0\nrosy brown\t188\t143 \t143\nRosyBrown\t188\t143 \t143\nRosyBrown1\t255\t193 \t193\nRosyBrown2\t238\t180 \t180\nRosyBrown3\t205\t155 \t155\nRosyBrown4\t139\t105 \t105\nroyal blue\t65\t105 \t225\nRoyalBlue\t65\t105 \t225\nRoyalBlue1\t72\t118 \t255\nRoyalBlue2\t67\t110 \t238\nRoyalBlue3\t58\t95 \t205\nRoyalBlue4\t39\t64 \t139\nsaddle brown\t139\t69 \t19\nSaddleBrown\t139\t69 \t19\nsalmon\t250\t128 \t114\nsalmon1\t255\t140 \t105\nsalmon2\t238\t130 \t98\nsalmon3\t205\t112 \t84\nsalmon4\t139\t76 \t57\nsandy brown\t244\t164 \t96\nSandyBrown\t244\t164 \t96\nsea green\t46\t139 \t87\nSeaGreen\t46\t139 \t87\nSeaGreen1\t84\t255 \t159\nSeaGreen2\t78\t238 \t148\nSeaGreen3\t67\t205 \t128\nSeaGreen4\t46\t139 \t87\nseashell\t255\t245 \t238\nseashell1\t255\t245 \t238\nseashell2\t238\t229 \t222\nseashell3\t205\t197 \t191\nseashell4\t139\t134 \t130\nsienna\t160\t82 \t45\nsienna1\t255\t130 \t71\nsienna2\t238\t121 \t66\nsienna3\t205\t104 \t57\nsienna4\t139\t71 \t38\nsilver\t192\t192\t192\nsky blue\t135\t206 \t235\nSkyBlue\t135\t206 \t235\nSkyBlue1\t135\t206 \t255\nSkyBlue2\t126\t192 \t238\nSkyBlue3\t108\t166 \t205\nSkyBlue4\t74\t112 \t139\nslate blue\t106\t90 \t205\nslate gray\t112\t128 \t144\nslate grey\t112\t128 \t144\nSlateBlue\t106\t90 \t205\nSlateBlue1\t131\t111 \t255\nSlateBlue2\t122\t103 \t238\nSlateBlue3\t105\t89 \t205\nSlateBlue4\t71\t60 \t139\nSlateGray\t112\t128 \t144\nSlateGray1\t198\t226 \t255\nSlateGray2\t185\t211 \t238\nSlateGray3\t159\t182 \t205\nSlateGray4\t108\t123 \t139\nSlateGrey\t112\t128 \t144\nsnow\t255\t250 \t250\nsnow1\t255\t250 \t250\nsnow2\t238\t233 \t233\nsnow3\t205\t201 \t201\nsnow4\t139\t137 \t137\nspring green\t0\t255 \t127\nSpringGreen\t0\t255 \t127\nSpringGreen1\t0\t255 \t127\nSpringGreen2\t0\t238 \t118\nSpringGreen3\t0\t205 \t102\nSpringGreen4\t0\t139 \t69\nsteel blue\t70\t130 \t180\nSteelBlue\t70\t130 \t180\nSteelBlue1\t99\t184 \t255\nSteelBlue2\t92\t172 \t238\nSteelBlue3\t79\t148 \t205\nSteelBlue4\t54\t100 \t139\ntan\t210\t180 \t140\ntan1\t255\t165 \t79\ntan2\t238\t154 \t73\ntan3\t205\t133 \t63\ntan4\t139\t90 \t43\nteal\t0\t128\t128\nthistle\t216\t191 \t216\nthistle1\t255\t225 \t255\nthistle2\t238\t210 \t238\nthistle3\t205\t181 \t205\nthistle4\t139\t123 \t139\ntomato\t255\t99 \t71\ntomato1\t255\t99 \t71\ntomato2\t238\t92 \t66\ntomato3\t205\t79 \t57\ntomato4\t139\t54 \t38\nturquoise\t64\t224 \t208\nturquoise1\t0\t245 \t255\nturquoise2\t0\t229 \t238\nturquoise3\t0\t197 \t205\nturquoise4\t0\t134 \t139\nviolet\t238\t130 \t238\nviolet red\t208\t32 \t144\nVioletRed\t208\t32 \t144\nVioletRed1\t255\t62 \t150\nVioletRed2\t238\t58 \t140\nVioletRed3\t205\t50 \t120\nVioletRed4\t139\t34 \t82\nwheat\t245\t222 \t179\nwheat1\t255\t231 \t186\nwheat2\t238\t216 \t174\nwheat3\t205\t186 \t150\nwheat4\t139\t126 \t102\nwhite\t255\t255 \t255\nwhite smoke\t245\t245 \t245\nWhiteSmoke\t245\t245 \t245\nyellow\t255\t255 \t0\nyellow green\t154\t205 \t50\nyellow1\t255\t255 \t0\nyellow2\t238\t238 \t0\nyellow3\t205\t205 \t0\nyellow4\t139\t139 \t0\nYellowGreen\t154\t205 \t50\n.DE\n.SH \"PORTABILITY ISSUES\"\n.TP\n\\fBmacOS\\fR\n.\nOn macOS, the following additional system colors are available. This\nfirst group contains all of the HIBrush colors available in the\nHIToolbox library. Note that on macOS 10.14 (Mojave) and later these\ncolors are unlikely to match the color actually used for the purpose\nsuggested by the color name.\n.RS\n.DS\nsystemActiveAreaFill\nsystemAlertBackgroundActive\nsystemAlertBackgroundInactive\nsystemAlternatePrimaryHighlightColor\nsystemAppleGuideCoachmark\nsystemBevelActiveDark\nsystemBevelActiveLight\nsystemBevelInactiveDark\nsystemBevelInactiveLight\nsystemBlack\nsystemButtonActiveDarkHighlight\nsystemButtonActiveDarkShadow\nsystemButtonActiveLightHighlight\nsystemButtonActiveLightShadow\nsystemButtonFace\nsystemButtonFaceActive\nsystemButtonFaceInactive\nsystemButtonFacePressed\nsystemButtonFrame\nsystemButtonFrameActive\nsystemButtonFrameInactive\nsystemButtonInactiveDarkHighlight\nsystemButtonInactiveDarkShadow\nsystemButtonInactiveLightHighlight\nsystemButtonInactiveLightShadow\nsystemButtonPressedDarkHighlight\nsystemButtonPressedDarkShadow\nsystemButtonPressedLightHighlight\nsystemButtonPressedLightShadow\nsystemChasingArrows\nsystemDialogBackgroundActive\nsystemDialogBackgroundInactive\nsystemDocumentWindowBackground\nsystemDragHilite\nsystemDrawerBackground\nsystemFinderWindowBackground\nsystemFocusHighlight\nsystemHighlight\nsystemHighlightAlternate\nsystemHighlightSecondary\nsystemIconLabelBackground\nsystemIconLabelBackgroundSelected\nsystemListViewBackground\nsystemListViewColumnDivider\nsystemListViewEvenRowBackground\nsystemListViewOddRowBackground\nsystemListViewSeparator\nsystemListViewSortColumnBackground\nsystemMenu\nsystemMenuActive\nsystemMenuBackground\nsystemMenuBackgroundSelected\nsystemModelessDialogBackgroundActive\nsystemModelessDialogBackgroundInactive\nsystemMovableModalBackground\nsystemNotificationWindowBackground\nsystemPopupArrowActive\nsystemPopupArrowInactive\nsystemPopupArrowPressed\nsystemPrimaryHighlightColor\nsystemScrollBarDelimiterActive\nsystemScrollBarDelimiterInactive\nsystemSecondaryHighlightColor\nsystemSelectedTabTextColor\nsystemSheetBackground\nsystemSheetBackgroundOpaque\nsystemSheetBackgroundTransparent\nsystemStaticAreaFill\nsystemToolbarBackground\nsystemTransparent\nsystemUtilityWindowBackgroundActive\nsystemUtilityWindowBackgroundInactive\nsystemWhite\nsystemWindowBody\n.DE\n.RE\n.\nTk supports all of the NSColors in the macOS System ColorList. The\nconvention for naming these colors is that the Tk name is generated by\ncapitalizing the macOS name and adding the prefix \"system\". On macOS\n10.14 (Mojave) and later many of these \"semantic\" colors will appear\ndifferently depending on whether the NSWindow in which they are used has\nthe Aqua or DarkAqua appearance. The System ColorList differs between\nreleases of macOS and some colors, such as systemLinkColor and\nsystemControlAccentColor, are simulated on older systems which did not\nprovide them. All of the colors below are available on all supported\nmacOS releases, but newer systems will support additional colors.\n.RS\n.DS\nsystemControlAccentColor\nsystemControlTextColor\nsystemDisabledControlTextColor\nsystemLabelColor\nsystemLinkColor\nsystemPlaceholderTextColor\nsystemSelectedTextBackgroundColor\nsystemSelectedTextColor\nsystemSeparatorColor\nsystemTextBackgroundColor\nsystemTextColor\n.DE\n.RE\n.\nThe numbered systemWindowBackgroundColors below\nare used in the \\fBttk::notebook\\fR and \\fBttk::labelframe\\fR widgets\nto provide a contrasting background. Each numbered color contrasts\nwith its predecessor.\n.RS\n.DS\nsystemWindowBackgroundColor\nsystemWindowBackgroundColor1\nsystemWindowBackgroundColor2\nsystemWindowBackgroundColor3\nsystemWindowBackgroundColor4\nsystemWindowBackgroundColor5\nsystemWindowBackgroundColor6\nsystemWindowBackgroundColor7\n.DE\n.RE\n.TP\n\\fBWindows\\fR\n.\nOn Windows, the following additional system colors are available\n(note that the actual color values depend on the currently active OS theme):\n.RS\n.DS\n.ta 6c\nsystem3dDarkShadow\tsystemHighlightText\nsystem3dLight\tsystemInactiveBorder\nsystemActiveBorder\tsystemInactiveCaption\nsystemActiveCaption\tsystemInactiveCaptionText\nsystemAppWorkspace\tsystemInfoBackground\nsystemBackground\tsystemInfoText\nsystemButtonFace\tsystemMenu\nsystemButtonHighlight\tsystemMenuText\nsystemButtonShadow\tsystemPlaceholderText\nsystemButtonText\tsystemScrollbar\nsystemCaptionText\tsystemWindow\nsystemDisabledText\tsystemWindowFrame\nsystemGrayText\tsystemWindowText\nsystemHighlight\n.DE\n.RE\n.SH \"SEE ALSO\"\noptions(n), Tk_GetColor(3)\n.SH KEYWORDS\ncolor, option\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/console.n", "content": "'\\\"\n'\\\" Copyright (c) 2001 Donal K. Fellows\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH console n 8.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nconsole \\- Control the console on systems without a real console\n.SH SYNOPSIS\n\\fBconsole\\fI subcommand\\fR ?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe console window is a replacement for a real console to allow input\nand output on the standard I/O channels on platforms that do not have\na real console. It is implemented as a separate interpreter with the\nTk toolkit loaded, and control over this interpreter is given through\nthe \\fBconsole\\fR command. The behaviour of the console window is\ndefined mainly through the contents of the \\fIconsole.tcl\\fR file in\nthe Tk library. Except for TkAqua, this command is not available when\nTk is loaded into a tclsh interpreter with\n.QW \"\\fBpackage require tk\\fR\" ,\nas a conventional terminal is expected to be present in that case.\nIn TkAqua, this command is disabled when there is a startup script\nand stdin is \\fB/dev/null\\fR (as is the case e.g. when a bundled application\nembedding Tk is started by the macOS Launcher). To enable the command\nin that case, define the environment variable \\fBTK_CONSOLE\\fR. This can be\ndone by modifying the Info.plist file by adding the LSEnvironment key\nto the main dict and setting its value to be a dict with the key\n\\fBTK_CONSOLE\\fR.\n.PP\n.\\\" METHOD: eval\n.TP\n\\fBconsole eval \\fIscript\\fR\n.\nEvaluate the \\fIscript\\fR argument as a Tcl script in the console\ninterpreter. The normal interpreter is accessed through the\n\\fBconsoleinterp\\fR command in the console interpreter.\n.\\\" METHOD: hide\n.TP\n\\fBconsole hide\\fR\n.\nHide the console window from view. Precisely equivalent to\nwithdrawing the \\fB.\\fR window in the console interpreter.\n.\\\" METHOD: show\n.TP\n\\fBconsole show\\fR\n.\nDisplay the console window. Precisely equivalent to deiconifying the\n\\fB.\\fR window in the console interpreter.\n.\\\" METHOD: title\n.TP\n\\fBconsole title \\fR?\\fIstring\\fR?\n.\nQuery or modify the title of the console window. If \\fIstring\\fR is\nnot specified, queries the title of the console window, and sets the\ntitle of the console window to \\fIstring\\fR otherwise. Precisely\nequivalent to using the \\fBwm title\\fR command in the console\ninterpreter.\n.SH \"ACCESS TO THE MAIN INTERPRETER\"\n.PP\nThe \\fBconsoleinterp\\fR command in the console interpreter allows\nscripts to be evaluated in the main interpreter. It supports two\nsubcommands: \\fBeval\\fR and \\fBrecord\\fR.\n.PP\n.\\\" METHOD: eval\n.TP\n\\fBconsoleinterp eval \\fIscript\\fR\n.\nEvaluates \\fIscript\\fR as a Tcl script at the global level in the main\ninterpreter.\n.\\\" METHOD: record\n.TP\n\\fBconsoleinterp record \\fIscript\\fR\n.\nRecords and evaluates \\fIscript\\fR as a Tcl script at the global level\nin the main interpreter as if \\fIscript\\fR had been typed in at the\nconsole.\n.SH \"ADDITIONAL TRAP CALLS\"\n.PP\nThere are several additional commands in the console interpreter that\nare called in response to activity in the main interpreter.\n\\fIThese are documented here for completeness only; they form part of\nthe internal implementation of the console and are likely to change or\nbe modified without warning.\\fR\n.PP\nOutput to the console from the main interpreter via the stdout and\nstderr channels is handled by invoking the \\fBtk::ConsoleOutput\\fR\ncommand in the console interpreter with two arguments. The first\nargument is the name of the channel being written to, and the second\nargument is the string being written to the channel (after encoding\nand end-of-line translation processing has been performed.)\n.PP\nWhen the \\fB.\\fR window of the main interpreter is destroyed, the\n\\fBtk::ConsoleExit\\fR command in the console interpreter is called\n(assuming the console interpreter has not already been deleted itself,\nthat is.)\n.SH \"DEFAULT BINDINGS\"\n.PP\nThe default script creates a console window (implemented using a text\nwidget) that has the following behaviour:\n.IP [1]\nPressing the tab key inserts a TAB character (as defined by the Tcl\n\\et escape.)\n.IP [2]\nPressing the return key causes the current line (if complete by the\nrules of \\fBinfo complete\\fR) to be passed to the main interpreter for\nevaluation.\n.IP [3]\nPressing the delete key deletes the selected text (if any text is\nselected) or the character to the right of the cursor (if not at the\nend of the line.)\n.IP [4]\nPressing the backspace key deletes the selected text (if any text is\nselected) or the character to the left of the cursor (of not at the\nstart of the line.)\n.IP [5]\nPressing either Control+A or the home key causes the cursor to go to\nthe start of the line (but after the prompt, if a prompt is present on\nthe line.)\n.IP [6]\nPressing either Control+E or the end key causes the cursor to go to\nthe end of the line.\n.IP [7]\nPressing either Control+P or the up key causes the previous entry in\nthe command history to be selected.\n.IP [8]\nPressing either Control+N or the down key causes the next entry in the\ncommand history to be selected.\n.IP [9]\nPressing either Control+B or the left key causes the cursor to move\none character backward as long as the cursor is not at the prompt.\n.IP [10]\nPressing either Control+F or the right key causes the cursor to move\none character forward.\n.IP [11]\nPressing F9 rebuilds the console window by destroying all its children\nand reloading the Tcl script that defined the console's behaviour.\n.IP [12]\nScrolling the mouse wheel while holding Cmd (macOS) or Ctrl (other platforms)\nincreases (scroll up) or decreases (scroll down) the console font size.\n.PP\nMost other behaviour is the same as a conventional text widget except\nfor the way that the \\fI<>\\fR event is handled identically to the\n\\fI<>\\fR event.\n.SH EXAMPLE\n.PP\nNot all platforms have the \\fBconsole\\fR command, so debugging code\noften has the following code fragment in it so output produced by\n\\fBputs\\fR can be seen while during development:\n.CS\ncatch {\\fBconsole show\\fR}\n.CE\n.SH \"SEE ALSO\"\ndestroy(n), fconfigure(n), history(n), interp(n), puts(n), text(n), wm(n)\n.SH KEYWORDS\nconsole, interpreter, window, interactive, output channels\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/cursors.n", "content": "'\\\"\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" All rights reserved.\n'\\\"\n'\\\" Copyright (c) 2006-2007 Daniel A. Steffen \n'\\\"\n.TH cursors n 8.3 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ncursors \\- mouse cursors available in Tk\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fB\\-cursor\\fR widget option allows a Tk programmer to change the\nmouse cursor for a particular widget. The cursor names recognized by\nTk on all platforms are:\n.CS\nX_cursor\narrow\nbased_arrow_down\nbased_arrow_up\nboat\nbogosity\nbottom_left_corner\nbottom_right_corner\nbottom_side\nbottom_tee\nbox_spiral\ncenter_ptr\ncircle\nclock\ncoffee_mug\ncross\ncross_reverse\ncrosshair\ndiamond_cross\ndot\ndotbox\ndouble_arrow\ndraft_large\ndraft_small\ndraped_box\nexchange\nfleur\ngobbler\ngumby\nhand1\nhand2\nheart\nicon\niron_cross\nleft_ptr\nleft_side\nleft_tee\nleftbutton\nll_angle\nlr_angle\nman\nmiddlebutton\nmouse\nnone\npencil\npirate\nplus\nquestion_arrow\nright_ptr\nright_side\nright_tee\nrightbutton\nrtl_logo\nsailboat\nsb_down_arrow\nsb_h_double_arrow\nsb_left_arrow\nsb_right_arrow\nsb_up_arrow\nsb_v_double_arrow\nshuttle\nsizing\nspider\nspraycan\nstar\ntarget\ntcross\ntop_left_arrow\ntop_left_corner\ntop_right_corner\ntop_side\ntop_tee\ntrek\nul_angle\numbrella\nur_angle\nwatch\nxterm\n.CE\n.PP\nThe \\fBnone\\fR cursor can be specified to eliminate the cursor.\n.SH \"PORTABILITY ISSUES\"\n.TP\n\\fBWindows\\fR\n.\nOn Windows systems, the following cursors are mapped to native cursors:\n.RS\n.CS\narrow\ncenter_ptr\ncrosshair\nfleur\nibeam\nicon\nnone\nsb_h_double_arrow\nsb_v_double_arrow\nwatch\nxterm\n.CE\nAnd the following additional cursors are available:\n.CS\nno\nstarting\nsize\nsize_ne_sw\nsize_ns\nsize_nw_se\nsize_we\nuparrow\nwait\n.CE\n.RE\n.TP\n\\fBmacOS\\fR\n.\nOn macOS, the following cursors are mapped to native cursors:\n.RS\n.CS\narrow\ntop_left_arrow\nleft_ptr\ncross\ncrosshair\ntcross\nibeam\nnone\nxterm\n.CE\nAnd the following additional native cursors are available:\n.CS\ncopyarrow\naliasarrow\ncontextualmenuarrow\nmovearrow\ntext\ncross-hair\nhand\nopenhand\nclosedhand\nfist\npointinghand\nresize\nresizeleft\nresizeright\nresizeleftright\nresizeup\nresizedown\nresizeupdown\nresizebottomleft\nresizetopleft\nresizebottomright\nresizetopright\nnotallowed\npoof\nwait\ncountinguphand\ncountingdownhand\ncountingupanddownhand\nspinning\nhelp\nbucket\ncancel\neyedrop\neyedrop-full\nzoom-in\nzoom-out\n.CE\n.RE\n.SH KEYWORDS\ncursor, option\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/destroy.n", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH destroy n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ndestroy \\- Destroy one or more windows\n.SH SYNOPSIS\n\\fBdestroy \\fR?\\fIwindow window ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThis command deletes the windows given by the\n\\fIwindow\\fR arguments, plus all of their descendants.\nIf a \\fIwindow\\fR\n.QW .\nis deleted then all windows will be destroyed and the application will\n(normally) exit.\nThe \\fIwindow\\fRs are destroyed in order, and if an error occurs\nin destroying a window the command aborts without destroying the\nremaining windows.\nNo error is returned if \\fIwindow\\fR does not exist.\n.SH EXAMPLE\n.PP\nDestroy all checkbuttons that are direct children of the given widget:\n.CS\nproc killCheckbuttonChildren {parent} {\n foreach w [winfo children $parent] {\n if {[winfo class $w] eq \"Checkbutton\"} {\n \\fBdestroy\\fR $w\n }\n }\n}\n.CE\n.SH KEYWORDS\napplication, destroy, window\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/dialog.n", "content": "'\\\"\n'\\\" Copyright (c) 1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk_dialog n 4.1 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk_dialog \\- Create modal dialog and wait for response\n.SH SYNOPSIS\n\\fBtk_dialog \\fIwindow title text bitmap default string string ...\\fR\n.BE\n.SH DESCRIPTION\n.PP\nThis procedure is part of the Tk script library.\nIt is largely \\fIdeprecated\\fR by the \\fBtk_messageBox\\fR.\nIts arguments describe a dialog box:\n.IP \\fIwindow\\fR\nName of top-level window to use for dialog. Any existing window\nby this name is destroyed.\n.IP \\fItitle\\fR\nText to appear in the window manager's title bar for the dialog.\n.IP \\fItext\\fR\nMessage to appear in the top portion of the dialog box.\n.IP \\fIbitmap\\fR\nIf non-empty, specifies a bitmap (in a form suitable for Tk_GetBitmap)\nto display in the top portion of\nthe dialog, to the left of the text.\nIf this is an empty string then no bitmap is displayed in the dialog.\n.IP \\fIdefault\\fR\nIf this is an integer greater than or equal to zero, then it gives\nthe index of the button that is to be the default button for the dialog\n(0 for the leftmost button, and so on).\nIf negative or an empty string then there will not be any default\nbutton.\n.IP \\fIstring\\fR\nThere will be one button for each of these arguments.\nEach \\fIstring\\fR specifies text to display in a button,\nin order from left to right.\n.PP\nAfter creating a dialog box, \\fBtk_dialog\\fR waits for the user to\nselect one of the buttons either by clicking on the button with the\nmouse or by typing return to invoke the default button (if any).\nThen it returns the index of the selected button: 0 for the leftmost\nbutton, 1 for the button next to it, and so on.\nIf the dialog's window is destroyed before the user selects one\nof the buttons, then \\-1 is returned.\n.PP\nWhile waiting for the user to respond, \\fBtk_dialog\\fR sets a local\ngrab. This prevents the user from interacting with the application\nin any way except to invoke the dialog box.\n.SH EXAMPLE\n.PP\n.CS\nset reply [\\fBtk_dialog\\fR .foo \"The Title\" \"Do you want to say yes?\" \\e\n questhead 0 Yes No \"I'm not sure\"]\n.CE\n.SH \"SEE ALSO\"\ntk_messageBox(n)\n.SH KEYWORDS\nbitmap, dialog, modal\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/entry.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH entry n 8.3 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nentry \\- Create and manipulate 'entry' one-line text entry widgets\n.SH SYNOPSIS\n\\fBentry\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-background\t\\-highlightthickness\t\\-selectbackground\n\\-borderwidth\t\\-insertbackground\t\\-selectborderwidth\n\\-cursor\t\\-insertborderwidth\t\\-selectforeground\n\\-exportselection\t\\-insertofftime\t\\-takefocus\n\\-font\t\\-insertontime\t\\-textvariable\n\\-foreground\t\\-insertwidth\t\\-xscrollcommand\n\\-highlightbackground\t\\-justify\n\\-highlightcolor\t\\-relief\n\\-placeholder\t\\-placeholderforeground\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-disabledbackground disabledBackground DisabledBackground\nSpecifies the background color to use when the entry is disabled. If\nthis option is the empty string, the normal background color is used.\n.OP \\-disabledforeground disabledForeground DisabledForeground\nSpecifies the foreground color to use when the entry is disabled. If\nthis option is the empty string, the normal foreground color is used.\n.OP \"\\-invalidcommand or \\-invcmd\" invalidCommand InvalidCommand\nSpecifies a script to eval when \\fB\\-validatecommand\\fR returns 0.\nSetting it to {} disables this feature (the default). The best use\nof this option is to set it to \\fIbell\\fR. See \\fBVALIDATION\\fR\nbelow for more information.\n.OP \\-readonlybackground readonlyBackground ReadonlyBackground\nSpecifies the background color to use when the entry is readonly. If\nthis option is the empty string, the normal background color is used.\n.OP \\-show show Show\nIf this option is specified, then the true contents of the entry\nare not displayed in the window.\nInstead, each character in the entry's value will be displayed as\nthe first character in the value of this option, such as\n.QW * .\nThis is useful, for example, if the entry is to be used to enter\na password.\nIf characters in the entry are selected and copied elsewhere, the\ninformation copied will be what is displayed, not the true contents\nof the entry.\n.OP \\-state state State\nSpecifies one of three states for the entry: \\fBnormal\\fR,\n\\fBdisabled\\fR, or \\fBreadonly\\fR. If the entry is readonly, then the\nvalue may not be changed using widget commands and no insertion cursor\nwill be displayed, even if the input focus is in the widget; the\ncontents of the widget may still be selected. If the entry is\ndisabled, the value may not be changed, no insertion cursor will be\ndisplayed, the contents will not be selectable, and the entry may\nbe displayed in a different color, depending on the values of the\n\\fB\\-disabledforeground\\fR and \\fB\\-disabledbackground\\fR options.\n.OP \\-validate validate Validate\nSpecifies the mode in which validation should operate: \\fBnone\\fR,\n\\fBfocus\\fR, \\fBfocusin\\fR, \\fBfocusout\\fR, \\fBkey\\fR, or \\fBall\\fR.\nIt defaults to \\fBnone\\fR. When you want validation, you must explicitly\nstate which mode you wish to use. See \\fBVALIDATION\\fR below for more.\n.OP \"\\-validatecommand or \\-vcmd\" validateCommand ValidateCommand\nSpecifies a script to eval when you want to validate the input into\nthe entry widget. Setting it to {} disables this feature (the default).\nThis command must return a valid Tcl boolean value. If it returns 0 (or\nthe valid Tcl boolean equivalent) then it means you reject the new edition\nand it will not occur and the \\fB\\-invalidcommand\\fR will be evaluated if it\nis set. If it returns 1, then the new edition occurs.\nSee \\fBVALIDATION\\fR below for more information.\n.OP \\-width width Width\nSpecifies an integer value indicating the desired width of the entry window,\nin average-size characters of the widget's font.\nIf the value is negative or zero, the widget picks a\nsize just large enough to hold its current text.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBentry\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into an entry widget.\nAdditional options, described above, may be specified on the\ncommand line or in the option database\nto configure aspects of the entry such as its colors, font,\nand relief. The \\fBentry\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nAn entry is a widget that displays a one-line text string and\nallows that string to be edited using widget commands described below, which\nare typically bound to keystrokes and mouse actions.\nWhen first created, an entry's string is empty.\nA portion of the entry may be selected as described below.\nIf an entry is exporting its selection (see the \\fB\\-exportselection\\fR\noption), then it will observe the standard X11 protocols for handling the\nselection; entry selections are available as type \\fBSTRING\\fR.\nEntries also observe the standard Tk rules for dealing with the\ninput focus. When an entry has the input focus it displays an\n\\fIinsertion cursor\\fR to indicate where new characters will be\ninserted.\n.PP\nEntries are capable of displaying strings that are too long to\nfit entirely within the widget's window. In this case, only a\nportion of the string will be displayed; commands described below\nmay be used to change the view in the window. Entries use\nthe standard \\fB\\-xscrollcommand\\fR mechanism for interacting with\nscrollbars (see the description of the \\fB\\-xscrollcommand\\fR option\nfor details). They also support scanning, as described below.\n.SH VALIDATION\n.PP\nValidation works by setting the \\fB\\-validatecommand\\fR option to a\nscript (\\fIvalidateCommand\\fR) which will be evaluated according to\nthe \\fB\\-validate\\fR option as follows:\n.PP\n.IP \\fBnone\\fR 10\nDefault. This means no validation will occur.\n.IP \\fBfocus\\fR 10\n\\fIvalidateCommand\\fR will be called when the entry receives or\nloses focus.\n.IP \\fBfocusin\\fR 10\n\\fIvalidateCommand\\fR will be called when the entry receives focus.\n.IP \\fBfocusout\\fR 10\n\\fIvalidateCommand\\fR will be called when the entry loses focus.\n.IP \\fBkey\\fR 10\n\\fIvalidateCommand\\fR will be called when the entry is edited.\n.IP \\fBall\\fR 10\n\\fIvalidateCommand\\fR will be called for all above conditions.\n.PP\nIt is possible to perform percent substitutions on the value of the\n\\fB\\-validatecommand\\fR and \\fB\\-invalidcommand\\fR options,\njust as you would in a \\fBbind\\fR script. The following substitutions\nare recognized:\n.PP\n.IP \\fB%d\\fR 5\nType of action: 1 for \\fBinsert\\fR, 0 for \\fBdelete\\fR,\nor \\-1 for focus, forced or textvariable validation.\n.IP \\fB%i\\fR 5\nIndex of char string to be inserted/deleted, if any, otherwise \\-1.\n.IP \\fB%P\\fR 5\nThe value of the entry if the edit is allowed. If you are configuring the\nentry widget to have a new textvariable, this will be the value of that\ntextvariable.\n.IP \\fB%s\\fR 5\nThe current value of entry prior to editing.\n.IP \\fB%S\\fR 5\nThe text string being inserted/deleted, if any, {} otherwise.\n.IP \\fB%v\\fR 5\nThe type of validation currently set.\n.IP \\fB%V\\fR 5\nThe type of validation that triggered the callback\n(key, focusin, focusout, forced).\n.IP \\fB%W\\fR 5\nThe name of the entry widget.\n.PP\nIn general, the \\fB\\-textvariable\\fR and \\fB\\-validatecommand\\fR options can be\ndangerous to mix. Any problems have been overcome so that using the\n\\fB\\-validatecommand\\fR will not interfere with the traditional behavior of\nthe entry widget. Using the \\fB\\-textvariable\\fR for read-only purposes will\nnever cause problems. The danger comes when you try set the\n\\fB\\-textvariable\\fR to something that the \\fB\\-validatecommand\\fR would not\naccept, which causes \\fB\\-validate\\fR to become \\fInone\\fR (the\n\\fB\\-invalidcommand\\fR will not be triggered). The same happens\nwhen an error occurs evaluating the \\fB\\-validatecommand\\fR.\n.PP\nPrimarily, an error will occur when the \\fB\\-validatecommand\\fR or\n\\fB\\-invalidcommand\\fR encounters an error in its script while evaluating or\n\\fB\\-validatecommand\\fR does not return a valid Tcl boolean value. The\n\\fB\\-validate\\fR option will also set itself to \\fBnone\\fR when you edit the\nentry widget from within either the \\fB\\-validatecommand\\fR or the\n\\fB\\-invalidcommand\\fR. Such editions will override the one that was being\nvalidated. If you wish to edit the entry widget (for example set it to {})\nduring validation and still have the \\fB\\-validate\\fR option set, you should\ninclude the command:\n.CS\nafter idle {%W config -validate %v}\n.CE\nin the \\fB\\-validatecommand\\fR or \\fB\\-invalidcommand\\fR (whichever one you\nwere editing the entry widget from). It is also recommended to not set an\nassociated \\fB\\-textvariable\\fR during validation, as that can cause the\nentry widget to become out of sync with the \\fB\\-textvariable\\fR.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBentry\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This command may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName subcommand \\fR?\\fIarg ...\\fR?\n.CE\n\\fISubcommand\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command.\n.SS INDICES\n.PP\nMany of the widget commands for entries take one or more indices as\narguments. An index specifies a particular character in the entry's\nstring, in any of the following ways:\n.TP 12\n\\fInumber\\fR\n.\nSpecifies the character as a numerical index, where 0 corresponds\nto the first character in the string.\n.TP 12\n\\fBanchor\\fR\n.\nIndicates the anchor point for the selection, which is set with the\n\\fBselect from\\fR and \\fBselect adjust\\fR widget commands.\n.TP 12\n\\fBend\\fR\n.\nIndicates the character just after the last one in the entry's string.\nThis is equivalent to specifying a numerical index equal to the length\nof the entry's string.\n.TP 12\n\\fBinsert\\fR\n.\nIndicates the character adjacent to and immediately following the\ninsertion cursor.\n.TP 12\n\\fBsel.first\\fR\n.\nIndicates the first character in the selection. It is an error to\nuse this form if the selection is not in the entry window.\n.TP 12\n\\fBsel.last\\fR\n.\nIndicates the character just after the last one in the selection.\nIt is an error to use this form if the selection is not in the\nentry window.\n.TP 12\n\\fB@\\fInumber\\fR\n.\nIn this form, \\fInumber\\fR is treated as an x-coordinate in the\nentry's window; the character spanning that x-coordinate is used.\nFor example,\n.QW \\fB@0\\fR\nindicates the left-most character in the window.\n.LP\nAbbreviations may be used for any of the forms above, e.g.\n.QW \\fBe\\fR\nor\n.QW \\fBsel.f\\fR .\nIn general, out-of-range indices are automatically rounded to the\nnearest legal value.\nIndexes support the same simple interpretation as\nfor the command \\fBstring index\\fR, with simple integer index\narithmetic and indexing relative to \\fBend\\fR.\n.SS SUBCOMMANDS\n.PP\nThe following commands are possible for entry widgets:\n.\\\" METHOD: bbox\n.TP\n\\fIpathName \\fBbbox \\fIindex\\fR\n.\nReturns a list of four numbers describing the bounding box of the\ncharacter given by \\fIindex\\fR.\nThe first two elements of the list give the x and y coordinates of\nthe upper-left corner of the screen area covered by the character\n(in pixels relative to the widget) and the last two elements give\nthe width and height of the character, in pixels.\nThe bounding box may refer to a region outside the visible area\nof the window.\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBentry\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBentry\\fR\ncommand.\n.\\\" METHOD: delete\n.TP\n\\fIpathName \\fBdelete \\fIfirst \\fR?\\fIlast\\fR?\n.\nDelete one or more elements of the entry.\n\\fIFirst\\fR is the index of the first character to delete, and\n\\fIlast\\fR is the index of the character just after the last\none to delete.\nIf \\fIlast\\fR is not specified it defaults to \\fIfirst\\fR+1,\ni.e. a single character is deleted.\nThis command returns an empty string.\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget\\fR\n.\nReturns the entry's string.\n.\\\" METHOD: icursor\n.TP\n\\fIpathName \\fBicursor \\fIindex\\fR\n.\nArrange for the insertion cursor to be displayed just before the character\ngiven by \\fIindex\\fR. Returns an empty string.\n.\\\" METHOD: index\n.TP\n\\fIpathName \\fBindex\\fI index\\fR\n.\nReturns the numerical index corresponding to \\fIindex\\fR.\n.\\\" METHOD: insert\n.TP\n\\fIpathName \\fBinsert \\fIindex string\\fR\n.\nInsert the characters of \\fIstring\\fR just before the character\nindicated by \\fIindex\\fR. Returns an empty string.\n.\\\" METHOD: scan\n.TP\n\\fIpathName \\fBscan\\fI option args\\fR\n.\nThis command is used to implement scanning on entries. It has\ntwo forms, depending on \\fIoption\\fR:\n.RS\n.TP\n\\fIpathName \\fBscan mark \\fIx\\fR\n.\nRecords \\fIx\\fR and the current view in the entry window; used in\nconjunction with later \\fBscan dragto\\fR commands. Typically this\ncommand is associated with a mouse button press in the widget. It\nreturns an empty string.\n.TP\n\\fIpathName \\fBscan dragto \\fIx\\fR\n.\nThis command computes the difference between its \\fIx\\fR argument\nand the \\fIx\\fR argument to the last \\fBscan mark\\fR command for\nthe widget. It then adjusts the view left or right by 10 times the\ndifference in x-coordinates. This command is typically associated\nwith mouse motion events in the widget, to produce the effect of\ndragging the entry at high speed through the window. The return\nvalue is an empty string.\n.RE\n.\\\" METHOD: selection\n.TP\n\\fIpathName \\fBselection \\fIoption arg\\fR\n.\nThis command is used to adjust the selection within an entry. It\nhas several forms, depending on \\fIoption\\fR:\n.RS\n.TP\n\\fIpathName \\fBselection adjust \\fIindex\\fR\n.\nLocate the end of the selection nearest to the character given by\n\\fIindex\\fR, and adjust that end of the selection to be at \\fIindex\\fR\n(i.e. including but not going beyond \\fIindex\\fR). The other\nend of the selection is made the anchor point for future\n\\fBselect to\\fR commands. If the selection\nis not currently in the entry, then a new selection is created to\ninclude the characters between \\fIindex\\fR and the most recent\nselection anchor point, inclusive.\nReturns an empty string.\n.TP\n\\fIpathName \\fBselection clear\\fR\n.\nClear the selection if it is currently in this widget. If the\nselection is not in this widget then the command has no effect.\nReturns an empty string.\n.TP\n\\fIpathName \\fBselection from \\fIindex\\fR\n.\nSet the selection anchor point to just before the character\ngiven by \\fIindex\\fR. Does not change the selection.\nReturns an empty string.\n.TP\n\\fIpathName \\fBselection present\\fR\n.\nReturns 1 if there is are characters selected in the entry,\n0 if nothing is selected.\n.TP\n\\fIpathName \\fBselection range \\fIstart end\\fR\n.\nSets the selection to include the characters starting with\nthe one indexed by \\fIstart\\fR and ending with the one just\nbefore \\fIend\\fR.\nIf \\fIend\\fR refers to the same character as \\fIstart\\fR or an\nearlier one, then the entry's selection is cleared.\n.TP\n\\fIpathName \\fBselection to \\fIindex\\fR\n.\nIf \\fIindex\\fR is before the anchor point, set the selection\nto the characters from \\fIindex\\fR up to but not including\nthe anchor point.\nIf \\fIindex\\fR is the same as the anchor point, do nothing.\nIf \\fIindex\\fR is after the anchor point, set the selection\nto the characters from the anchor point up to but not including\n\\fIindex\\fR.\nThe anchor point is determined by the most recent \\fBselect from\\fR\nor \\fBselect adjust\\fR command in this widget.\nIf the selection is not in this widget then a new selection is\ncreated using the most recent anchor point specified for the widget.\nReturns an empty string.\n.RE\n.\\\" METHOD: validate\n.TP\n\\fIpathName \\fBvalidate\\fR\n.\nThis command is used to force an evaluation of the \\fB\\-validatecommand\\fR\nindependent of the conditions specified by the \\fB\\-validate\\fR option.\nThis is done by temporarily setting the \\fB\\-validate\\fR option to \\fBall\\fR.\nIt returns 0 or 1.\n.\\\" METHOD: xview\n.TP\n\\fIpathName \\fBxview \\fIargs\\fR\n.\nThis command is used to query and change the horizontal position of the\ntext in the widget's window. It can take any of the following\nforms:\n.RS\n.TP\n\\fIpathName \\fBxview\\fR\n.\nReturns a list containing two elements.\nEach element is a real fraction between 0 and 1; together they describe\nthe horizontal span that is visible in the window.\nFor example, if the first element is .2 and the second element is .6,\n20% of the entry's text is off-screen to the left, the middle 40% is visible\nin the window, and 40% of the text is off-screen to the right.\nThese are the same values passed to scrollbars via the \\fB\\-xscrollcommand\\fR\noption.\n.TP\n\\fIpathName \\fBxview\\fI index\\fR\n.\nAdjusts the view in the window so that the character given by \\fIindex\\fR\nis displayed at the left edge of the window.\n.TP\n\\fIpathName \\fBxview moveto\\fI fraction\\fR\n.\nAdjusts the view in the window so that the character \\fIfraction\\fR of the\nway through the text appears at the left edge of the window.\n\\fIFraction\\fR must be a fraction between 0 and 1.\n.TP\n\\fIpathName \\fBxview scroll \\fInumber what\\fR\n.\nThis command shifts the view in the window left or right according to\n\\fInumber\\fR and \\fIwhat\\fR.\n\\fINumber\\fR must be an integer or a float, but if it is a float then\nit is converted to an integer, rounded away from 0.\n\\fIWhat\\fR must be either \\fBpages\\fR or \\fBunits\\fR or an abbreviation\nof one of these.\nIf \\fIwhat\\fR is \\fBpages\\fR then the view adjusts by \\fInumber\\fR screenfuls.\nIf \\fInumber\\fR is negative then characters farther to the left become\nvisible; if it is positive then characters farther to the right\nbecome visible.\nIf \\fIwhat\\fR is \\fBunits\\fR, the view adjusts left or right by\n\\fInumber\\fR average-width characters on the display.\n.RE\n.SH \"DEFAULT BINDINGS\"\n.PP\nTk automatically creates class bindings for entries that give them\nthe following default behavior. In the descriptions below,\n.QW word\nrefers to a contiguous group of letters, digits, or\n.QW _\ncharacters, or any single character other than these.\n.IP [1]\nClicking mouse button 1 positions the insertion cursor\njust before the character underneath the mouse cursor, sets the\ninput focus to this widget, and clears any selection in the widget.\nDragging with mouse button 1 strokes out a selection between\nthe insertion cursor and the character under the mouse.\n.IP [2]\nDouble-clicking with mouse button 1 selects the word under the mouse\nand positions the insertion cursor at the end of the word.\nDragging after a double click will stroke out a selection consisting\nof whole words.\n.IP [3]\nTriple-clicking with mouse button 1 selects all of the text in the\nentry and positions the insertion cursor at the end of the line.\n.IP [4]\nThe ends of the selection can be adjusted by dragging with mouse\nbutton 1 while the Shift key is down; this will adjust the end\nof the selection that was nearest to the mouse cursor when button\n1 was pressed.\nIf the button is double-clicked before dragging then the selection\nwill be adjusted in units of whole words.\n.IP [5]\nClicking mouse button 1 with the Control key down will position the\ninsertion cursor in the entry without affecting the selection.\n.IP [6]\nIf any normal printing characters are typed in an entry, they are\ninserted at the point of the insertion cursor.\n.IP [7]\nThe view in the entry can be adjusted by dragging with the middle\nmouse button (button 2, or button 3 in TkAqua). If the middle mouse\nbutton is clicked without moving the mouse, the selection is copied\ninto the entry at the position of the mouse cursor.\n.IP [8]\nIf the mouse is dragged out of the entry on the left or right sides\nwhile button 1 is pressed, the entry will automatically scroll to\nmake more text visible (if there is more text off-screen on the side\nwhere the mouse left the window).\n.IP [9]\nThe Left and Right keys move the insertion cursor one character to the\nleft or right; they also clear any selection in the entry and set\nthe selection anchor.\nIf Left or Right is typed with the Shift key down, then the insertion\ncursor moves and the selection is extended to include the new character.\nControl-Left and Control-Right move the insertion cursor by words, and\nControl-Shift-Left and Control-Shift-Right move the insertion cursor\nby words and also extend the selection.\nControl-b and Control-f behave the same as Left and Right, respectively.\nMeta-b and Meta-f behave the same as Control-Left and Control-Right,\nrespectively.\n.IP [10]\nThe Home key, or Control-a, will move the insertion cursor to the\nbeginning of the entry and clear any selection in the entry.\nShift-Home moves the insertion cursor to the beginning of the entry\nand also extends the selection to that point.\n.IP [11]\nThe End key, or Control-e, will move the insertion cursor to the\nend of the entry and clear any selection in the entry.\nShift-End moves the cursor to the end and extends the selection\nto that point.\n.IP [12]\nThe Select key and Control-Space set the selection anchor to the position\nof the insertion cursor. They do not affect the current selection.\nShift-Select and Control-Shift-Space adjust the selection to the\ncurrent position of the insertion cursor, selecting from the anchor\nto the insertion cursor if there was not any selection previously.\n.IP [13]\nControl-/ selects all the text in the entry.\n.IP [14]\nControl-\\e clears any selection in the entry.\n.IP [15]\nThe F16 key (labelled Copy on many Sun workstations) or Meta-w\ncopies the selection in the widget to the clipboard, if there is a selection.\n.IP [16]\nThe F20 key (labelled Cut on many Sun workstations) or Control-w\ncopies the selection in the widget to the clipboard and deletes\nthe selection.\nIf there is no selection in the widget then these keys have no effect.\n.IP [17]\nThe F18 key (labelled Paste on many Sun workstations) or Control-y\ninserts the contents of the clipboard at the position of the\ninsertion cursor.\n.IP [18]\nThe Delete key deletes the selection, if there is one in the entry.\nIf there is no selection, it deletes the character to the right of\nthe insertion cursor.\n.IP [19]\nThe BackSpace key and Control-h delete the selection, if there is one\nin the entry.\nIf there is no selection, it deletes the character to the left of\nthe insertion cursor.\n.IP [20]\nControl-d deletes the character to the right of the insertion cursor.\n.IP [21]\nMeta-d deletes the word to the right of the insertion cursor.\n.IP [22]\nControl-k deletes all the characters to the right of the insertion\ncursor.\n.IP [23]\nControl-t reverses the order of the two characters to the right of\nthe insertion cursor.\n.PP\nIf the entry is disabled using the \\fB\\-state\\fR option, then the entry's\nview can still be adjusted and text in the entry can still be selected,\nbut no insertion cursor will be displayed and no text modifications will\ntake place\nexcept if the entry is linked to a variable using the \\fB\\-textvariable\\fR\noption, in which case any changes to the variable are reflected by the\nentry whatever the value of its \\fB\\-state\\fR option.\n.PP\nThe behavior of entries can be changed by defining new bindings for\nindividual widgets or by redefining the class bindings.\n.SH \"SEE ALSO\"\nttk::entry(n)\n.SH KEYWORDS\nentry, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/event.n", "content": "'\\\"\n'\\\" Copyright (c) 1996 Sun Microsystems, Inc.\n'\\\" Copyright (c) 1998-2000 Ajuba Solutions.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH event n 8.3 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nevent \\- Miscellaneous event facilities: define virtual events and generate events\n.SH SYNOPSIS\n\\fBevent\\fI option \\fR?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBevent\\fR command provides several facilities for dealing with\nwindow system events, such as defining virtual events and synthesizing\nevents. The command has several different forms, determined by the\nfirst argument. The following forms are currently supported:\n.\\\" METHOD: add\n.TP\n\\fBevent add <<\\fIvirtual\\fB>>\\fI sequence \\fR?\\fIsequence ...\\fR?\n.\nAssociates the virtual event \\fIvirtual\\fR with the physical\nevent sequence(s) given by the \\fIsequence\\fR arguments, so that\nthe virtual event will trigger whenever any one of the \\fIsequence\\fRs\noccurs.\n\\fIVirtual\\fR may be any string value and \\fIsequence\\fR may have\nany of the values allowed for the \\fIsequence\\fR argument to the\n\\fBbind\\fR command.\nIf \\fIvirtual\\fR is already defined, the new physical event sequences\nadd to the existing sequences for the event.\n.\\\" METHOD: delete\n.TP\n\\fBevent delete <<\\fIvirtual\\fB>> \\fR?\\fIsequence sequence ...\\fR?\n.\nDeletes each of the \\fIsequence\\fRs from those associated with\nthe virtual event given by \\fIvirtual\\fR.\n\\fIVirtual\\fR may be any string value and \\fIsequence\\fR may have\nany of the values allowed for the \\fIsequence\\fR argument to the\n\\fBbind\\fR command.\nAny \\fIsequence\\fRs not currently associated with \\fIvirtual\\fR\nare ignored.\nIf no \\fIsequence\\fR argument is provided, all physical event sequences\nare removed for \\fIvirtual\\fR, so that the virtual event will not\ntrigger anymore.\n.\\\" METHOD: generate\n.TP\n\\fBevent generate \\fIwindow event \\fR?\\fIoption value option value ...\\fR?\n.\nGenerates a window event and arranges for it to be processed just as if\nit had come from the window system.\n\\fIWindow\\fR gives the path name of the window for which the event\nwill be generated; it may also be an identifier (such as returned by\n\\fBwinfo id\\fR) as long as it is for a window in the current application.\n\\fIEvent\\fR provides a basic description of\nthe event, such as \\fB\\fR or \\fB<>\\fR.\nIf \\fIWindow\\fR is empty the whole screen is meant, and coordinates\nare relative to the screen.\n\\fIEvent\\fR may have any of the forms allowed for the \\fIsequence\\fR\nargument of the \\fBbind\\fR command except that it must consist\nof a single event pattern, not a sequence.\n\\fIOption-value\\fR pairs may be used to specify additional\nattributes of the event, such as the x and y mouse position; see\n\\fBEVENT FIELDS\\fR below. If the \\fB\\-when\\fR option is not specified, the\nevent is processed immediately: all of the handlers for the event\nwill complete before the \\fBevent generate\\fR command returns.\nIf the \\fB\\-when\\fR option is specified then it determines when the\nevent is processed. Certain events, such as key events, require\nthat the window has focus to receive the event properly.\n.\\\" METHOD: info\n.TP\n\\fBevent info \\fR?\\fB<<\\fIvirtual\\fB>>\\fR?\n.\nReturns information about virtual events.\nIf the \\fB<<\\fIvirtual\\fB>>\\fR argument is omitted, the return value\nis a list of all the virtual events that are currently defined.\nIf \\fB<<\\fIvirtual\\fB>>\\fR is specified then the return value is\na list whose elements are the physical event sequences currently\ndefined for the given virtual event; if the virtual event is\nnot defined then an empty string is returned.\n.RS\n.PP\nNote that virtual events that are not bound to physical event\nsequences are \\fInot\\fR returned by \\fBevent info\\fR.\n.RE\n.SH \"EVENT FIELDS\"\n.PP\nThe following options are supported for the \\fBevent generate\\fR\ncommand. These correspond to the\n.QW %\nexpansions allowed in binding scripts for the \\fBbind\\fR command.\n.\\\" OPTION: -above\n.TP\n\\fB\\-above\\fI window\\fR\n.\n\\fIWindow\\fR specifies the \\fIabove\\fR field for the event,\neither as a window path name or as an integer window id.\nValid for \\fBConfigure\\fR events.\nCorresponds to the \\fB%a\\fR substitution for binding scripts.\n.\\\" OPTION: -borderwidth\n.TP\n\\fB\\-borderwidth\\fI size\\fR\n.\n\\fISize\\fR must be a screen distance; it specifies the\n\\fIborder_width\\fR field for the event.\nValid for \\fBConfigure\\fR events.\nCorresponds to the \\fB%B\\fR substitution for binding scripts.\n.\\\" OPTION: -button\n.TP\n\\fB\\-button\\fI number\\fR\n.\n\\fINumber\\fR must be an integer; it specifies the \\fIdetail\\fR field\nfor a \\fBButton\\fR or \\fBButtonRelease\\fR event, overriding\nany button number provided in the base \\fIevent\\fR argument.\nCorresponds to the \\fB%b\\fR substitution for binding scripts.\n.\\\" OPTION: -count\n.TP\n\\fB\\-count\\fI number\\fR\n.\n\\fINumber\\fR must be an integer; it specifies the \\fIcount\\fR field\nfor the event. Valid for \\fBExpose\\fR events.\nCorresponds to the \\fB%c\\fR substitution for binding scripts.\n.\\\" OPTION: -data\n.TP\n\\fB\\-data\\fI string\\fR\n.\n\\fIString\\fR may be any value; it specifies the \\fIuser_data\\fR field\nfor the event. Only valid for virtual events. Corresponds to the\n\\fB%d\\fR substitution for virtual events in binding scripts.\n.\\\" OPTION: -delta\n.TP\n\\fB\\-delta\\fI number\\fR\n.\n\\fINumber\\fR must be an integer; it specifies the \\fIdelta\\fR field\nfor the \\fBMouseWheel\\fR event. The \\fIdelta\\fR refers to the\ndirection and magnitude the mouse wheel was rotated. Note the value\nis not a screen distance but are units of motion in the mouse wheel.\nTypically these values are multiples of 120. For example, 120 should\nscroll the text widget up 4 lines and \\-240 would scroll the text\nwidget down 8 lines. Of course, other widgets may define different\nbehaviors for mouse wheel motion. This field corresponds to the\n\\fB%D\\fR substitution for binding scripts.\n.\\\" OPTION: -detail\n.TP\n\\fB\\-detail\\fI detail\\fR\n.\n\\fIDetail\\fR specifies the \\fIdetail\\fR field for the event\nand must be one of the following:\n.RS\n.DS\n.ta 6c\n\\fBNotifyAncestor\\fR\t\\fBNotifyNonlinearVirtual\\fR\n\\fBNotifyDetailNone\\fR\t\\fBNotifyPointer\\fR\n\\fBNotifyInferior\\fR\t\\fBNotifyPointerRoot\\fR\n\\fBNotifyNonlinear\\fR\t\\fBNotifyVirtual\\fR\n.DE\nValid for \\fBEnter\\fR, \\fBLeave\\fR, \\fBFocusIn\\fR and\n\\fBFocusOut\\fR events.\nCorresponds to the \\fB%d\\fR substitution for binding scripts.\n.RE\n.\\\" OPTION: -focus\n.TP\n\\fB\\-focus\\fI boolean\\fR\n.\n\\fIBoolean\\fR must be a boolean value; it specifies the \\fIfocus\\fR\nfield for the event.\nValid for \\fBEnter\\fR and \\fBLeave\\fR events.\nCorresponds to the \\fB%f\\fR substitution for binding scripts.\n.\\\" OPTION: -height\n.TP\n\\fB\\-height\\fI size\\fR\n.\n\\fISize\\fR must be a screen distance; it specifies the \\fIheight\\fR\nfield for the event. Valid for \\fBConfigure\\fR events.\nCorresponds to the \\fB%h\\fR substitution for binding scripts.\n.\\\" OPTION: -keycode\n.TP\n\\fB\\-keycode\\fI number\\fR\n.\n\\fINumber\\fR must be an integer; it specifies the \\fIkeycode\\fR\nfield for the event.\nValid for \\fBKey\\fR and \\fBKeyRelease\\fR events.\nCorresponds to the \\fB%k\\fR substitution for binding scripts.\n.\\\" OPTION: -keysym\n.TP\n\\fB\\-keysym\\fI name\\fR\n.\n\\fIName\\fR must be the name of a valid keysym, such as \\fBg\\fR,\n\\fBspace\\fR, or \\fBReturn\\fR; its corresponding\nkeycode value is used as the \\fIkeycode\\fR field for event, overriding\nany detail specified in the base \\fIevent\\fR argument.\nValid for \\fBKey\\fR and \\fBKeyRelease\\fR events.\nCorresponds to the \\fB%K\\fR substitution for binding scripts.\n.\\\" OPTION: -mode\n.TP\n\\fB\\-mode\\fI notify\\fR\n.\n\\fINotify\\fR specifies the \\fImode\\fR field for the event and must be\none of \\fBNotifyNormal\\fR, \\fBNotifyGrab\\fR, \\fBNotifyUngrab\\fR, or\n\\fBNotifyWhileGrabbed\\fR.\nValid for \\fBEnter\\fR, \\fBLeave\\fR, \\fBFocusIn\\fR, and\n\\fBFocusOut\\fR events.\nCorresponds to the \\fB%m\\fR substitution for binding scripts.\n.\\\" OPTION: -override\n.TP\n\\fB\\-override\\fI boolean\\fR\n.\n\\fIBoolean\\fR must be a boolean value; it specifies the\n\\fIoverride_redirect\\fR field for the event.\nValid for \\fBMap\\fR, \\fBReparent\\fR, and \\fBConfigure\\fR events.\nCorresponds to the \\fB%o\\fR substitution for binding scripts.\n.\\\" OPTION: -place\n.TP\n\\fB\\-place\\fI where\\fR\n.\n\\fIWhere\\fR specifies the \\fIplace\\fR field for the event; it must be\neither \\fBPlaceOnTop\\fR or \\fBPlaceOnBottom\\fR.\nValid for \\fBCirculate\\fR events.\nCorresponds to the \\fB%p\\fR substitution for binding scripts.\n.\\\" OPTION: -root\n.TP\n\\fB\\-root\\fI window\\fR\n.\n\\fIWindow\\fR must be either a window path name or an integer window\nidentifier; it specifies the \\fIroot\\fR field for the event.\nValid for \\fBKey\\fR, \\fBKeyRelease\\fR, \\fBButton\\fR,\n\\fBButtonRelease\\fR, \\fBEnter\\fR, \\fBLeave\\fR, and \\fBMotion\\fR\nevents.\nCorresponds to the \\fB%R\\fR substitution for binding scripts.\n.\\\" OPTION: -rootx\n.TP\n\\fB\\-rootx\\fI coord\\fR\n.\n\\fICoord\\fR must be a screen distance; it specifies the \\fIx_root\\fR\nfield for the event.\nValid for \\fBKey\\fR, \\fBKeyRelease\\fR, \\fBButton\\fR,\n\\fBButtonRelease\\fR, \\fBEnter\\fR, \\fBLeave\\fR, and \\fBMotion\\fR\nevents. Corresponds to the \\fB%X\\fR substitution for binding scripts.\n.\\\" OPTION: -rooty\n.TP\n\\fB\\-rooty\\fI coord\\fR\n.\n\\fICoord\\fR must be a screen distance; it specifies the \\fIy_root\\fR\nfield for the event.\nValid for \\fBKey\\fR, \\fBKeyRelease\\fR, \\fBButton\\fR,\n\\fBButtonRelease\\fR, \\fBEnter\\fR, \\fBLeave\\fR, and \\fBMotion\\fR\nevents.\nCorresponds to the \\fB%Y\\fR substitution for binding scripts.\n.\\\" OPTION: -sendevent\n.TP\n\\fB\\-sendevent\\fI boolean\\fR\n.\n\\fIBoolean\\fR must be a boolean value; it specifies the \\fIsend_event\\fR\nfield for the event. Valid for all events. Corresponds to the\n\\fB%E\\fR substitution for binding scripts.\n.\\\" OPTION: -serial\n.TP\n\\fB\\-serial\\fI number\\fR\n.\n\\fINumber\\fR must be an integer; it specifies the \\fIserial\\fR field\nfor the event. Valid for all events.\nCorresponds to the \\fB%#\\fR substitution for binding scripts.\n.\\\" OPTION: -state\n.TP\n\\fB\\-state\\fI state\\fR\n.\n\\fIState\\fR specifies the \\fIstate\\fR field for the event.\nFor \\fBKey\\fR, \\fBKeyRelease\\fR, \\fBButtons\\fR,\n\\fBButtonRelease\\fR, \\fBEnter\\fR, \\fBLeave\\fR, and \\fBMotion\\fR events\nit must be an integer value.\nFor \\fBVisibility\\fR events it must be one of \\fBVisibilityUnobscured\\fR,\n\\fBVisibilityPartiallyObscured\\fR, or \\fBVisibilityFullyObscured\\fR.\nThis option overrides any modifiers such as \\fBMeta\\fR or \\fBControl\\fR\nspecified in the base \\fIevent\\fR.\nCorresponds to the \\fB%s\\fR substitution for binding scripts.\n.\\\" OPTION: -subwindow\n.TP\n\\fB\\-subwindow\\fI window\\fR\n.\n\\fIWindow\\fR specifies the \\fIsubwindow\\fR field for the event, either\nas a path name for a Tk widget or as an integer window identifier.\nValid for \\fBKey\\fR, \\fBKeyRelease\\fR, \\fBButton\\fR,\n\\fBButtonRelease\\fR, \\fBEnter\\fR, \\fBLeave\\fR, and \\fBMotion\\fR events.\nSimilar to \\fB%S\\fR substitution for binding scripts.\n.\\\" OPTION: -time\n.TP\n\\fB\\-time\\fI integer\\fR\n.\n\\fIInteger\\fR must be an integer value; it specifies the \\fItime\\fR field\nfor the event. Additionally, the special value \\fBcurrent\\fR is allowed;\nthis value will be substituted by the current event time.\nValid for \\fBKey\\fR, \\fBKeyRelease\\fR, \\fBButton\\fR,\n\\fBButtonRelease\\fR, \\fBEnter\\fR, \\fBLeave\\fR, \\fBMotion\\fR,\nand \\fBProperty\\fR events.\nCorresponds to the \\fB%t\\fR substitution for binding scripts.\n.\\\" OPTION: -warp\n.TP\n\\fB\\-warp\\fI boolean\\fR\n.\n\\fIboolean\\fR must be a boolean value; it specifies whether\nthe screen pointer should be warped as well.\nValid for \\fBKey\\fR, \\fBKeyRelease\\fR, \\fBButton\\fR,\n\\fBButtonRelease\\fR, and \\fBMotion\\fR events. Tk supports pointer warping\nrelative to the screen's root window, and relative to a Tk window. In the\nlatter case, the pointer will only warp if the window is mapped.\n.\\\" OPTION: -width\n.TP\n\\fB\\-width\\fI size\\fR\n.\n\\fISize\\fR must be a screen distance; it specifies the \\fIwidth\\fR field\nfor the event.\nValid for \\fBConfigure\\fR events.\nCorresponds to the \\fB%w\\fR substitution for binding scripts.\n.\\\" OPTION: -when\n.TP\n\\fB\\-when\\fI when\\fR\n.\n\\fIWhen\\fR determines when the event will be processed; it must have one\nof the following values:\n.RS\n.IP \\fBnow\\fR 10\nProcess the event immediately, before the command returns.\nThis also happens if the \\fB\\-when\\fR option is omitted.\n.IP \\fBtail\\fR 10\nPlace the event on Tcl's event queue behind any events already\nqueued for this application.\n.IP \\fBhead\\fR 10\nPlace the event at the front of Tcl's event queue, so that it\nwill be handled before any other events already queued.\n.IP \\fBmark\\fR 10\nPlace the event at the front of Tcl's event queue but behind any\nother events already queued with \\fB\\-when mark\\fR.\nThis option is useful when generating a series of events that should\nbe processed in order but at the front of the queue.\n.RE\n.\\\" OPTION: -x\n.TP\n\\fB\\-x\\fI coord\\fR\n.\n\\fICoord\\fR must be a screen distance; it specifies the \\fIx\\fR field\nfor the event.\nValid for \\fBKey\\fR, \\fBKeyRelease\\fR, \\fBButton\\fR,\n\\fBButtonRelease\\fR, \\fBMotion\\fR, \\fBEnter\\fR, \\fBLeave\\fR,\n\\fBExpose\\fR, \\fBConfigure\\fR, \\fBGravity\\fR, and \\fBReparent\\fR\nevents.\nCorresponds to the \\fB%x\\fR substitution for binding scripts.\nIf \\fIWindow\\fR is empty the coordinate is relative to the\nscreen, and this option corresponds to the \\fB%X\\fR substitution\nfor binding scripts.\n.\\\" OPTION: -y\n.TP\n\\fB\\-y\\fI coord\\fR\n.\n\\fICoord\\fR must be a screen distance; it specifies the \\fIy\\fR\nfield for the event.\nValid for \\fBKey\\fR, \\fBKeyRelease\\fR, \\fBButton\\fR,\n\\fBButtonRelease\\fR, \\fBMotion\\fR, \\fBEnter\\fR, \\fBLeave\\fR,\n\\fBExpose\\fR, \\fBConfigure\\fR, \\fBGravity\\fR, and \\fBReparent\\fR\nevents.\nCorresponds to the \\fB%y\\fR substitution for binding scripts.\nIf \\fIWindow\\fR is empty the coordinate is relative to the\nscreen, and this option corresponds to the \\fB%Y\\fR substitution\nfor binding scripts.\n.PP\nAny options that are not specified when generating an event are filled\nwith the value 0, except for \\fIserial\\fR, which is filled with the\nnext X event serial number.\n.SH \"PREDEFINED VIRTUAL EVENTS\"\n.PP\nTk defines the following virtual events for the purposes of\nnotification:\n.TP\n\\fB<>\\fR\n.\nThis is sent to widget to notify it that the letter it has underlined\n(as an accelerator indicator) with the \\fB\\-underline\\fR option has\nbeen pressed in combination with the Alt key. The usual response to\nthis is to either focus into the widget (or some related widget) or to\ninvoke the widget.\n.TP\n\\fB<>\\fR\n.\nThis can be sent to some widgets (e.g. button, listbox, menu) as an\nalternative to .\n.TP\n\\fB<>\\fR\n.\nThis is sent to a listbox when the set of selected item(s) in the\nlistbox is updated.\n.TP\n\\fB<>\\fR\n.\nThis is sent to a menu when the currently selected item in the menu\nchanges. It is intended for use with context-sensitive help systems.\n.TP\n\\fB<>\\fR\n.\nThis is sent to a text widget when the contents of the widget are\nchanged.\n.TP\n\\fB<>\\fR\n.\nThis is sent to a text widget when the selection in the widget is\nchanged.\n.TP\n\\fB<>\\fR\n.\nThis is sent to all widgets when the ttk theme changed. The ttk\nwidgets listen to this event and redisplay themselves when it fires.\nThe legacy widgets ignore this event.\n.TP\n\\fB<>\\fR\n.\nThis event is sent to all widgets when a font is changed, for example,\nby the use of [font configure]. The user_data field (%d) will have the\nvalue \"FontChanged\". For other system wide changes, this event will\nbe sent to all widgets, and the user_data field will indicate the\ncause of the change. NOTE: all tk and ttk widgets already handle this\nevent internally.\n.TP\n\\fB<>\\fR\n.\nThis is sent to a widget when the focus enters the widget because of a\nuser-driven\n.QW \"tab to widget\"\naction.\n.TP\n\\fB<>\\fR\n.\nThis is sent to a widget when the focus leaves the widget because of a\nuser-driven\n.QW \"tab to widget\"\naction.\n.TP\n\\fB<>\\fR\n.\nThis is sent to a text widget when its undo stack or redo stack becomes\nempty or unempty.\n.TP\n\\fB<>\\fR\n.\nThis is sent to a text widget when its internal data become obsolete,\nand again when these internal data are back in sync with the widget\nview. The detail field (%d substitution) is either true (when the\nwidget is in sync) or false (when it is not).\n.PP\nTk defines the following virtual events for the purposes of unifying\nbindings across multiple platforms. Users expect them to behave in the\nfollowing way:\n.TP\n\\fB<>\\fR\n.\nDelete the currently selected widget contents.\n.TP\n\\fB<>\\fR\n.\nCopy the currently selected widget contents to the clipboard.\n.TP\n\\fB<>\\fR\n.\nMove the currently selected widget contents to the clipboard.\n.TP\n\\fB<>\\fR\n.\nMove to the end of the line in the current widget while deselecting any\nselected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the start of the line in the current widget while deselecting any\nselected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the next item (i.e., visible character) in the current widget while\ndeselecting any selected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the next line in the current widget while deselecting any selected\ncontents.\n.TP\n\\fB<>\\fR\n.\nMove to the next paragraph in the current widget while deselecting any\nselected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the next group of items (i.e., visible word) in the current widget\nwhile deselecting any selected contents.\n.TP\n\\fB<>\\fR\n.\nReplace the currently selected widget contents with the contents of\nthe clipboard.\n.TP\n\\fB<>\\fR\n.\nInsert the contents of the selection at the mouse location. (This\nevent has meaningful \\fB%x\\fR and \\fB%y\\fR substitutions).\n.TP\n\\fB<>\\fR\n.\nMove to the previous item (i.e., visible character) in the current widget\nwhile deselecting any selected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the previous line in the current widget while deselecting any selected\ncontents.\n.TP\n\\fB<>\\fR\n.\nMove to the previous paragraph in the current widget while deselecting any\nselected contents.\n.TP\n\\fB<>\\fR\n.\nTraverse to the previous window.\n.TP\n\\fB<>\\fR\n.\nMove to the previous group of items (i.e., visible word) in the current widget\nwhile deselecting any selected contents.\n.TP\n\\fB<>\\fR\n.\nRedo one undone action.\n.TP\n\\fB<>\\fR\n.\nSet the range of selected contents to the complete widget.\n.TP\n\\fB<>\\fR\n.\nMove to the end of the line in the current widget while extending the range\nof selected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the start of the line in the current widget while extending the range\nof selected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the next item (i.e., visible character) in the current widget while\nextending the range of selected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the next line in the current widget while extending the range of\nselected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the next paragraph in the current widget while extending the range\nof selected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the next group of items (i.e., visible word) in the current widget\nwhile extending the range of selected contents.\n.TP\n\\fB<>\\fR\n.\nReset the range of selected contents to be empty.\n.TP\n\\fB<>\\fR\n.\nMove to the previous item (i.e., visible character) in the current widget\nwhile extending the range of selected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the previous line in the current widget while extending the range of\nselected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the previous paragraph in the current widget while extending the\nrange of selected contents.\n.TP\n\\fB<>\\fR\n.\nMove to the previous group of items (i.e., visible word) in the current widget\nwhile extending the range of selected contents.\n.TP\n\\fB<>\\fR\n.\nToggle the selection.\n.TP\n\\fB<>\\fR\n.\nUndo the last action.\n.SH EXAMPLES\n.SS \"MAPPING KEYS TO VIRTUAL EVENTS\"\n.PP\nIn order for a virtual event binding to trigger, two things must\nhappen. First, the virtual event must be defined with the\n\\fBevent add\\fR command. Second, a binding must be created for\nthe virtual event with the \\fBbind\\fR command.\nConsider the following virtual event definitions:\n.PP\n.CS\n\\fBevent add\\fR <> \n\\fBevent add\\fR <> \n\\fBevent add\\fR <> \n\\fBevent add\\fR <> \nif {[tk windowingsystem] eq \"aqua\"} {\n \\fBevent add\\fR <> \n}\n.CE\n.PP\nIn the \\fBbind\\fR command, a virtual event can be bound like any other\nbuiltin event type as follows:\n.PP\n.CS\nbind Entry <> {%W insert [selection get]}\n.CE\n.PP\nThe double angle brackets are used to specify that a virtual event is being\nbound. If the user types Control-y or presses button 2, or if\na \\fB<>\\fR virtual event is synthesized with \\fBevent generate\\fR,\nthen the \\fB<>\\fR binding will be invoked.\n.PP\nIf a virtual binding has the exact same sequence as a separate\nphysical binding, then the physical binding will take precedence.\nConsider the following example:\n.PP\n.CS\n\\fBevent add\\fR <> \nbind Entry {puts Control-y}\nbind Entry <> {puts Paste}\n.CE\n.PP\nWhen the user types Control-y the \\fB\\fR binding\nwill be invoked, because a physical event is considered\nmore specific than a virtual event, all other things being equal.\nHowever, when the user types Meta-Control-y the\n\\fB<>\\fR binding will be invoked, because the\n\\fBMeta\\fR modifier in the physical pattern associated with the\nvirtual binding is more specific than the \\fB sequence for\nthe physical event.\n.PP\nBindings on a virtual event may be created before the virtual event exists.\nIndeed, the virtual event never actually needs to be defined, for instance,\non platforms where the specific virtual event would be meaningless or\nungeneratable.\n.PP\nWhen a definition of a virtual event changes at run time, all windows\nwill respond immediately to the new definition.\nStarting from the preceding example, if the following code is executed:\n.PP\n.CS\nbind Entry {}\n\\fBevent add\\fR <> \n.CE\n.PP\nthe behavior will change such in two ways. First, the shadowed\n\\fB<>\\fR binding will emerge.\nTyping Control-y will no longer invoke the \\fB\\fR binding,\nbut instead invoke the virtual event \\fB<>\\fR. Second,\npressing the F6 key will now also invoke the \\fB<>\\fR binding.\n.SS \"MOVING THE MOUSE POINTER\"\n.PP\nSometimes it is useful to be able to really move the mouse pointer. For\nexample, if you have some software that is capable of demonstrating directly\nto the user how to use the program. To do this, you need to\n.QW warp\nthe mouse around by using \\fBevent generate\\fR, like this:\n.PP\n.CS\nfor {set xy 0} {$xy < 200} {incr xy} {\n \\fBevent generate\\fR . -x $xy -y $xy -warp 1\n update\n after 50\n}\n.CE\n.PP\nNote that it is usually considered bad style to move the mouse pointer for the\nuser because it removes control from them. Therefore this technique should be\nused with caution. Also note that it is not guaranteed to function on all\nplatforms.\n.SH \"SEE ALSO\"\nbind(n)\n.SH KEYWORDS\nevent, binding, define, handle, virtual event\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/fileicon.n", "content": ".\\\" Text automatically generated by txt2man\n'\\\"\n'\\\" Copyright (c) 2025 Kevin Walzer.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk fileicon n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n.SH NAME\nfileicon \\- Platform-native icon image for file type/extension.\n.SH SYNOPSIS\n\\fBtk fileicon\\fI file size\\fR\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBtk fileicon\\fR command creates a platform-specific file icon. Its intent is to provide a visual representation of a file type that is expected by users on that platform. The command takes two arguments - an aboslute file path and an icon size, which be any size (on Windows these map to the closest of 16, 32, 48 or 256 pixels because of API constraints).\n.SH EXAMPLE\n.PP\nHere is an example of the \\fBtk fileicon\\fR code:\n.PP\n.CS\nset img [tk fileicon [file normalize text.txt] 32]\npack [label .l -text \"text.txt\" -image $img -compound top]\n.CE\n.SH PLATFORM NOTES\n.PP\nOn Windows and macOS, system API's are used; on X11, icons from the Tango project - the default icon theme for the Gnome desktop - are used.\n.\n.SH KEYWORDS\nimage, icon\n" }, { "path": "doc/focus.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH focus n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nfocus \\- Manage the input focus\n.SH SYNOPSIS\n.nf\n\\fBfocus\\fR\n\\fBfocus \\fIwindow\\fR\n\\fBfocus \\fIoption\\fR ?\\fIarg ...\\fR?\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBfocus\\fR command is used to manage the Tk input focus.\nAt any given time, one window on each display is designated as\nthe \\fIfocus window\\fR; any key press or key release events for the\ndisplay are sent to that window.\nIt is normally up to the window manager to redirect the focus among the\ntop-level windows of a display. For example, some window managers\nautomatically set the input focus to a top-level window whenever\nthe mouse enters it; others redirect the input focus only when\nthe user clicks on a window.\nUsually the window manager will set the focus\nonly to top-level windows, leaving it up to the application to\nredirect the focus among the children of the top-level.\n.PP\nTk remembers one focus window for each top-level (the most recent\ndescendant of that top-level to receive the focus); when the window\nmanager gives the focus\nto a top-level, Tk automatically redirects it to the remembered\nwindow. Within a top-level Tk uses an \\fIexplicit\\fR focus model\nby default. Moving the mouse within a top-level does not normally\nchange the focus; the focus changes only when a widget\ndecides explicitly to claim the focus (e.g., because of a button\nclick), or when the user types a key such as Tab that moves the\nfocus.\n.PP\nThe Tcl procedure \\fBtk_focusFollowsMouse\\fR may be invoked to\ncreate an \\fIimplicit\\fR focus model: it reconfigures Tk so that\nthe focus is set to a window whenever the mouse enters it.\nThe Tcl procedures \\fBtk_focusNext\\fR and \\fBtk_focusPrev\\fR\nimplement a focus order among the windows of a top-level; they\nare used in the default bindings for Tab and Shift-Tab, among other\nthings.\n.PP\nThe \\fBfocus\\fR command can take any of the following forms:\n.TP\n\\fBfocus\\fR\n.\nReturns the path name of the focus window on the display containing\nthe application's main window, or an empty string if no window in\nthis application has the focus on that display. Note: it is\nbetter to specify the display explicitly using \\fB\\-displayof\\fR\n(see below) so that the code will work in applications using multiple\ndisplays.\n.TP\n\\fBfocus \\fIwindow\\fR\n.\nIf the application currently has the input focus on \\fIwindow\\fR's\ndisplay, this command resets the input focus for \\fIwindow\\fR's display\nto \\fIwindow\\fR and returns an empty string.\nIf the application does not currently have the input focus on\n\\fIwindow\\fR's display, \\fIwindow\\fR will be remembered as the focus\nfor its top-level; the next time the focus arrives at the top-level,\nTk will redirect it to \\fIwindow\\fR.\nIf \\fIwindow\\fR is an empty string then the command does nothing.\n.TP\n\\fBfocus \\-displayof \\fIwindow\\fR\n.\nReturns the name of the focus window on the display containing \\fIwindow\\fR.\nIf the focus window for \\fIwindow\\fR's display is not in this\napplication, the return value is an empty string.\n.TP\n\\fBfocus \\-force \\fIwindow\\fR\n.\nSets the focus of \\fIwindow\\fR's display to \\fIwindow\\fR, even if\nthe application does not currently have the input focus for the display.\nThis command should be used sparingly, if at all.\nIn normal usage, an application should not claim the focus for\nitself; instead, it should wait for the window manager to give it\nthe focus.\nIf \\fIwindow\\fR is an empty string then the command does nothing.\n.TP\n\\fBfocus \\-lastfor \\fIwindow\\fR\n.\nReturns the name of the most recent window to have the input focus\namong all the windows in the same top-level as \\fIwindow\\fR.\nIf no window in that top-level has ever had the input focus, or\nif the most recent focus window has been deleted, then the name\nof the top-level is returned. The return value is the window that\nwill receive the input focus the next time the window manager gives\nthe focus to the top-level.\n.SH \"QUIRKS\"\n.PP\nWhen an internal window receives the input focus, Tk does not actually\nset the X focus to that window; as far as X is concerned, the focus\nwill stay on the top-level window containing the window with the focus.\nHowever, Tk generates FocusIn and FocusOut events just as if the X\nfocus were on the internal window. This approach gets around a\nnumber of problems that would occur if the X focus were actually moved;\nthe fact that the X focus is on the top-level is invisible unless\nyou use C code to query the X server directly.\n.SH \"EXAMPLE\"\n.PP\nTo make a window that only participates in the focus traversal ring\nwhen a variable is set, add the following bindings to the widgets\n\\fIbefore\\fR and \\fIafter\\fR it in that focus ring:\n.PP\n.CS\nbutton .before -text \"Before\"\nbutton .middle -text \"Middle\"\nbutton .after -text \"After\"\ncheckbutton .flag -variable traverseToMiddle -takefocus 0\npack .flag -side left\npack .before .middle .after\nbind .before {\n if {!$traverseToMiddle} {\n \\fBfocus\\fR .after\n break\n }\n}\nbind .after {\n if {!$traverseToMiddle} {\n \\fBfocus\\fR .before\n break\n }\n}\n\\fBfocus\\fR .before\n.CE\n.SH KEYWORDS\nevents, focus, keyboard, top-level, window manager\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/focusNext.n", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk_focusNext n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk_focusNext, tk_focusPrev, tk_focusFollowsMouse \\- Utility procedures for managing the input focus.\n.SH SYNOPSIS\n.nf\n\\fBtk_focusNext \\fIwindow\\fR\n\\fBtk_focusPrev \\fIwindow\\fR\n\\fBtk_focusFollowsMouse\\fR\n.fi\n.BE\n.SH DESCRIPTION\n.PP\n\\fBtk_focusNext\\fR is a utility procedure used for keyboard traversal.\nIt returns the\n.QW next\nwindow after \\fIwindow\\fR in focus order. The focus order is determined by\nthe stacking order of windows and the structure of the window hierarchy.\nAmong siblings, the focus order is the same as the stacking order, with the\nlowest window being first.\nIf a window has children, the window is visited first, followed by\nits children (recursively), followed by its next sibling.\nTop-level windows other than \\fIwindow\\fR are skipped, so that\n\\fBtk_focusNext\\fR never returns a window in a different top-level\nfrom \\fIwindow\\fR.\n.PP\nAfter computing the next window, \\fBtk_focusNext\\fR examines the\nwindow's \\fB\\-takefocus\\fR option to see whether it should be skipped.\nIf so, \\fBtk_focusNext\\fR continues on to the next window in the focus\norder, until it eventually finds a window that will accept the focus\nor returns back to \\fIwindow\\fR.\n.PP\n\\fBtk_focusPrev\\fR is similar to \\fBtk_focusNext\\fR except that it\nreturns the window just before \\fIwindow\\fR in the focus order.\n.PP\n\\fBtk_focusFollowsMouse\\fR changes the focus model for the application\nto an implicit one where the window under the mouse gets the focus.\nAfter this procedure is called, whenever the mouse enters a window\nTk will automatically give it the input focus.\nThe \\fBfocus\\fR command may be used to move the focus to a window\nother than the one under the mouse, but as soon as the mouse moves\ninto a new window the focus will jump to that window.\n.PP\nNote that at present there is no built-in support for returning the\napplication to an explicit focus model; to do this you will have\nto write a script that deletes the bindings created by\n\\fBtk_focusFollowsMouse\\fR.\n.SH KEYWORDS\nfocus, keyboard traversal, top-level\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/font.n", "content": "'\\\"\n'\\\" Copyright (c) 1996 Sun Microsystems, Inc.\n'\\\" Copyright (c) 2006-2007 Daniel A. Steffen \n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH font n 8.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nfont \\- Create and inspect fonts.\n.SH SYNOPSIS\n\\fBfont\\fI option \\fR?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBfont\\fR command provides several facilities for dealing with\nfonts, such as defining named fonts and inspecting the actual attributes of\na font. The command has several different forms, determined by the\nfirst argument. The following forms are currently supported:\n.\\\" METHOD: actual\n.TP\n\\fBfont actual \\fIfont\\fR ?\\fB\\-displayof \\fIwindow\\fR? ?\\fIoption\\fR? ?\\fB\\-\\|\\-\\fR? ?\\fIchar\\fR?\n.\nReturns information about the actual attributes that are obtained when\n\\fIfont\\fR is used on \\fIwindow\\fR's display; the actual attributes obtained\nmay differ from the attributes requested due to platform-dependent\nlimitations, such as the availability of font families and point sizes.\n\\fIfont\\fR is a font description; see \\fBFONT DESCRIPTIONS\\fR below. If the\n\\fIwindow\\fR argument is omitted, it defaults to the main window. If\n\\fIoption\\fR is specified, returns the value of that attribute; if it is\nomitted, the return value is a list of all the attributes and their values.\nSee \\fBFONT OPTIONS\\fR below for a list of the possible attributes. If the\n\\fIchar\\fR argument is supplied, it must be a single character. The font\nattributes returned will be those of the specific font used to render\nthat character, which will be different from the base font if the base\nfont does not contain the given character. If \\fIchar\\fR may be a hyphen, it\nshould be preceded by \\fB\\-\\|\\-\\fR to distinguish it from a misspelled\n\\fIoption\\fR.\n.\\\" METHOD: configure\n.TP\n\\fBfont configure \\fIfontname\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the desired attributes for the named font called\n\\fIfontname\\fR. If no \\fIoption\\fR is specified, returns a list describing\nall the options and their values for \\fIfontname\\fR. If a single \\fIoption\\fR\nis specified with no \\fIvalue\\fR, then returns the current value of that\nattribute. If one or more \\fIoption\\fR\\-\\fIvalue\\fR pairs are specified,\nthen the command modifies the given named font to have the given values; in\nthis case, all widgets using that font will redisplay themselves using the\nnew attributes for the font. See \\fBFONT OPTIONS\\fR below for a list of the\npossible attributes.\n.RS\n.PP\nNote that on Aqua/macOS, the system fonts (see\n\\fBPLATFORM SPECIFIC FONTS\\fR below) may not be actually altered because they\nare implemented by the system theme. To achieve the effect of modification,\nuse \\fBfont actual\\fR to get their configuration and \\fBfont create\\fR to\nsynthesize a copy of the font which can be modified.\n.RE\n.\\\" METHOD: create\n.TP\n\\fBfont create\\fR ?\\fIfontname\\fR? ?\\fIoption value ...\\fR?\n.\nCreates a new named font and returns its name. \\fIfontname\\fR specifies the\nname for the font; if it is omitted, then Tk generates a new name of the\nform \\fBfont\\fIx\\fR, where \\fIx\\fR is an integer. There may be any number\nof \\fIoption\\fR\\-\\fIvalue\\fR pairs, which provide the desired attributes for\nthe new named font. See \\fBFONT OPTIONS\\fR below for a list of the possible\nattributes.\n.\\\" METHOD: delete\n.TP\n\\fBfont delete\\fI fontname\\fR ?\\fIfontname ...\\fR?\n.\nDelete the specified named fonts. If there are widgets using the named font,\nthe named font will not actually be deleted until all the instances are\nreleased. Those widgets will continue to display using the last known values\nfor the named font. If a deleted named font is subsequently recreated with\nanother call to \\fBfont create\\fR, the widgets will use the new named font\nand redisplay themselves using the new attributes of that font.\n.\\\" METHOD: families\n.TP\n\\fBfont families\\fR ?\\fB\\-displayof \\fIwindow\\fR?\n.\nThe return value is a list of the case-insensitive names of all font families\nthat exist on \\fIwindow\\fR's display. If the \\fIwindow\\fR argument is\nomitted, it defaults to the main window.\n.\\\" METHOD: measure\n.TP\n\\fBfont measure \\fIfont\\fR ?\\fB\\-displayof \\fIwindow\\fR? \\fItext\\fR\n.\nMeasures the amount of space the string \\fItext\\fR would use in the given\n\\fIfont\\fR when displayed in \\fIwindow\\fR. \\fIfont\\fR is a font description;\nsee \\fBFONT DESCRIPTIONS\\fR below. If the \\fIwindow\\fR argument is\nomitted, it\ndefaults to the main window. The return value is the total width in pixels\nof \\fItext\\fR, not including the extra pixels used by highly exaggerated\ncharacters such as cursive\n.QW f .\nIf the string contains newlines or tabs,\nthose characters are not expanded or treated specially when measuring the\nstring.\n.\\\" METHOD: metrics\n.TP\n\\fBfont metrics \\fIfont\\fR ?\\fB\\-displayof \\fIwindow\\fR? ?\\fIoption\\fR?\n.\nReturns information about the metrics (the font-specific data), for\n\\fIfont\\fR when it is used on \\fIwindow\\fR's display. \\fIfont\\fR is a font\ndescription; see \\fBFONT DESCRIPTIONS\\fR below. If the \\fIwindow\\fR\nargument is\nomitted, it defaults to the main window. If \\fIoption\\fR is specified,\nreturns the value of that metric; if it is omitted, the return value is a\nlist of all the metrics and their values. See \\fBFONT METRICS\\fR\nbelow for a list of the possible metrics.\n.\\\" METHOD: names\n.TP\n\\fBfont names\\fR\n.\nThe return value is a list of all the named fonts that are currently defined.\n.SH \"FONT DESCRIPTIONS\"\n.PP\nThe following formats are accepted as a font description anywhere\n\\fIfont\\fR is specified as an argument above; these same forms are also\npermitted when specifying the \\fB\\-font\\fR option for widgets.\n.TP\n[1] \\fIfontname\\fR\n.\nThe name of a named font, created using the \\fBfont create\\fR command. When\na widget uses a named font, it is guaranteed that this will never cause an\nerror, as long as the named font exists, no matter what potentially invalid\nor meaningless set of attributes the named font has. If the named font\ncannot be displayed with exactly the specified attributes, some other close\nfont will be substituted automatically.\n.TP\n[2] \\fIsystemfont\\fR\n.\nThe platform-specific name of a font, interpreted by the graphics server.\nThis also includes, under X, an XLFD (see [4]) for which a single\n.QW \\fB*\\fR\ncharacter was used to elide more than one field in the middle of the\nname. See \\fBPLATFORM SPECIFIC FONTS\\fR for a list of the system fonts.\n.TP\n[3] \\fIfamily \\fR?\\fIsize\\fR? ?\\fIstyle\\fR? ?\\fIstyle ...\\fR?\n.\nA properly formed list whose first element is the desired font\n\\fIfamily\\fR and whose optional second element is the desired \\fIsize\\fR.\nThe interpretation of the \\fIsize\\fR attribute follows the same rules\ndescribed for \\fB\\-size\\fR in \\fBFONT OPTIONS\\fR below. Any\nadditional optional\narguments following the \\fIsize\\fR are font \\fIstyle\\fRs. Possible values\nfor the \\fIstyle\\fR arguments are as follows:\n.RS\n.DS\n.ta 3c 6c 9c\n\\fBnormal\\fR\t\\fBbold\\fR\t\\fBroman\\fR\t\\fBitalic\\fR\n\\fBunderline\\fR\t\\fBoverstrike\\fR\n.DE\n.RE\n.TP\n[4] X-font names (XLFD)\n.\nA Unix-centric font name of the form\n\\fI\\-foundry\\-family\\-weight\\-slant\\-setwidth\\-addstyle\\-pixel\\-point\\-resx\\-resy\\-spacing\\-width\\-charset\\-encoding\\fR.\nThe\n.QW \\fB*\\fR\ncharacter may be used to skip individual fields that the\nuser does not care about. There must be exactly one\n.QW \\fB*\\fR\nfor each field skipped, except that a\n.QW \\fB*\\fR\nat the end of the XLFD skips any\nremaining fields; the shortest valid XLFD is simply\n.QW \\fB*\\fR ,\nsignifying all fields as defaults. Any fields that were skipped are\ngiven default\nvalues. For compatibility, an XLFD always chooses a font of the specified\npixel size (not point size); although this interpretation is not strictly\ncorrect, all existing applications using XLFDs assumed that one\n.QW point\nwas in fact one pixel and would display incorrectly (generally larger) if\nthe correct size font were actually used.\n.TP\n[5] \\fIoption value \\fR?\\fIoption value ...\\fR?\n.\nA properly formed list of \\fIoption\\fR\\-\\fIvalue\\fR pairs that specify\nthe desired attributes of the font, in the same format used when defining\na named font; see \\fBFONT OPTIONS\\fR below.\n.LP\nWhen font description \\fIfont\\fR is used, the system attempts to parse the\ndescription according to each of the above five rules, in the order specified.\nCases [1] and [2] must match the name of an existing named font or of a\nsystem font. Cases [3], [4], and [5] are accepted on all\nplatforms and the closest available font will be used. In some situations\nit may not be possible to find any close font (e.g., the font family was\na garbage value); in that case, some system-dependent default font is\nchosen. If the font description does not match any of the above patterns,\nan error is generated.\n.SH \"FONT METRICS\"\n.PP\nThe following options are used by the \\fBfont metrics\\fR command to query\nfont-specific data determined when the font was created. These properties are\nfor the whole font itself and not for individual characters drawn in that\nfont. In the following definitions, the\n.QW baseline\nof a font is the\nhorizontal line where the bottom of most letters line up; certain letters,\nsuch as lower-case\n.QW g\nstick below the baseline.\n.\\\" OPTION: -ascent\n.TP\n\\fB\\-ascent\\fR\n.\nThe amount in pixels that the tallest letter sticks up above the baseline of\nthe font, plus any extra blank space added by the designer of the font.\n.\\\" OPTION: -descent\n.TP\n\\fB\\-descent\\fR\n.\nThe largest amount in pixels that any letter sticks down below the baseline\nof the font, plus any extra blank space added by the designer of the font.\n.\\\" OPTION: -linespace\n.TP\n\\fB\\-linespace\\fR\n.\nReturns how far apart vertically in pixels two lines of text using the same\nfont should be placed so that none of the characters in one line overlap any\nof the characters in the other line. This is generally the sum of the ascent\nabove the baseline line plus the descent below the baseline.\n.\\\" OPTION: -fixed\n.TP\n\\fB\\-fixed\\fR\n.\nReturns a boolean flag that is\n.QW \\fB1\\fR\nif this is a fixed-width font,\nwhere each normal character is the same width as all the other\ncharacters, or is\n.QW \\fB0\\fR\nif this is a proportionally-spaced font, where\nindividual characters have different widths. The widths of control\ncharacters, tab characters, and other non-printing characters are not\nincluded when calculating this value.\n.SH \"FONT OPTIONS\"\n.PP\nThe following options are supported on all platforms, and are used when\nconstructing a named font or when specifying a font using style [5] as\nabove:\n.\\\" OPTION: -family\n.TP\n\\fB\\-family \\fIname\\fR\n.\nThe case-insensitive font family name. Tk guarantees to support the font\nfamilies named \\fBCourier\\fR (a monospaced\n.QW typewriter\nfont), \\fBTimes\\fR (a serifed\n.QW newspaper\nfont), and \\fBHelvetica\\fR (a sans-serif\n.QW European\nfont). The most closely matching native font family will\nautomatically be substituted when one of the above font families is used.\nThe \\fIname\\fR may also be the name of a native, platform-specific font\nfamily; in that case it will work as desired on one platform but may not\ndisplay correctly on other platforms. If the family is unspecified or\nunrecognized, a platform-specific default font will be chosen.\n.\\\" OPTION: -size\n.TP\n\\fB\\-size \\fIsize\\fR\n.\nThe desired size of the font. If the \\fIsize\\fR argument is a positive\nnumber, it is interpreted as a size in points. If \\fIsize\\fR is a negative\nnumber, its absolute value is interpreted as a size in pixels. If a\nfont cannot be displayed at the specified size, a nearby size will be\nchosen. If \\fIsize\\fR is unspecified or zero, a platform-dependent default\nsize will be chosen.\n.RS\n.PP\nSizes should normally be specified in points so the application will remain\nthe same ruler size on the screen, even when changing screen resolutions or\nmoving scripts across platforms. However, specifying pixels is useful in\ncertain circumstances such as when a piece of text must line up with respect\nto a fixed-size bitmap. The mapping between points and pixels is set when\nthe application starts, based on properties of the installed monitor, but it\ncan be overridden by calling the \\fBtk scaling\\fR command.\n.RE\n.\\\" OPTION: -weight\n.TP\n\\fB\\-weight \\fIweight\\fR\n.\nThe nominal thickness of the characters in the font. The value\n\\fBnormal\\fR specifies a normal weight font, while \\fBbold\\fR specifies a\nbold font. The closest available weight to the one specified will\nbe chosen. The default weight is \\fBnormal\\fR.\n.\\\" OPTION: -slant\n.TP\n\\fB\\-slant \\fIslant\\fR\n.\nThe amount the characters in the font are slanted away from the\nvertical. Valid values for slant are \\fBroman\\fR and \\fBitalic\\fR.\nA roman font is the normal, upright appearance of a font, while\nan italic font is one that is tilted some number of degrees from upright.\nThe closest available slant to the one specified will be chosen.\nThe default slant is \\fBroman\\fR.\n.\\\" OPTION: -underline\n.TP\n\\fB\\-underline \\fIboolean\\fR\n.\nThe value is a boolean flag that specifies whether characters in this\nfont should be underlined. The default value for underline is \\fBfalse\\fR.\n.\\\" OPTION: -overstrike\n.TP\n\\fB\\-overstrike \\fIboolean\\fR\n.\nThe value is a boolean flag that specifies whether a horizontal line should\nbe drawn through the middle of characters in this font. The default value\nfor overstrike is \\fBfalse\\fR.\n.SH \"STANDARD FONTS\"\n.PP\nThe following named fonts are supported on all systems, and default to values\nthat match appropriate system defaults.\n.IP \\fBTkDefaultFont\\fR\nThis font is the default for all GUI items not otherwise specified.\n.IP \\fBTkTextFont\\fR\nThis font should be used for user text in entry widgets, listboxes etc.\n.IP \\fBTkFixedFont\\fR\nThis font is the standard fixed-width font.\n.IP \\fBTkMenuFont\\fR\nThis font is used for menu items.\n.IP \\fBTkHeadingFont\\fR\nThis font should be used for column headings in lists and tables.\n.IP \\fBTkCaptionFont\\fR\nThis font should be used for window and dialog caption bars.\n.IP \\fBTkSmallCaptionFont\\fR\nThis font should be used for captions on contained windows or tool dialogs.\n.IP \\fBTkIconFont\\fR\nThis font should be used for icon captions.\n.IP \\fBTkTooltipFont\\fR\nThis font should be used for tooltip windows (transient information windows).\n.LP\nIt is \\fInot\\fR advised to change these fonts, as they may be modified by Tk\nitself in response to system changes. Instead, make a copy of the font and\nmodify that.\n.SH \"PLATFORM SPECIFIC FONTS\"\n.PP\nThe following system fonts are supported:\n.TP\n\\fBX Windows\\fR\n.\nAll valid X font names, including those listed by xlsfonts(1), are available.\n.TP\n\\fBMS Windows\\fR\n.\nThe following fonts are supported, and are mapped to the user's\nstyle defaults.\n.RS\n.DS\n.ta 3c 6c\n\\fBsystem\\fR\t\\fBansi\\fR\t\\fBdevice\\fR\n\\fBsystemfixed\\fR\t\\fBansifixed\\fR\t\\fBoemfixed\\fR\n.DE\n.RE\n.TP\n\\fBmacOS\\fR\n.\nThe following fonts are supported, and are mapped to the user's\nstyle defaults.\n.RS\n.DS\n.ta 3c 6c\n\\fBsystem\\fR\t\\fBapplication\\fR\t\\fBmenu\\fR\n.DE\n.PP\nAdditionally, the following named fonts provide access to the Aqua\ntheme fonts:\n.DS\n.ta 5c\n\\fBsystemSystemFont\\fR\t\\fBsystemEmphasizedSystemFont\\fR\n\\fBsystemSmallSystemFont\\fR\t\\fBsystemSmallEmphasizedSystemFont\\fR\n\\fBsystemApplicationFont\\fR\t\\fBsystemLabelFont\\fR\n\\fBsystemViewsFont\\fR\t\\fBsystemMenuTitleFont\\fR\n\\fBsystemMenuItemFont\\fR\t\\fBsystemMenuItemMarkFont\\fR\n\\fBsystemMenuItemCmdKeyFont\\fR\t\\fBsystemWindowTitleFont\\fR\n\\fBsystemPushButtonFont\\fR\t\\fBsystemUtilityWindowTitleFont\\fR\n\\fBsystemAlertHeaderFont\\fR\t\\fBsystemToolbarFont\\fR\n\\fBsystemMiniSystemFont\\fR\t\\fBsystemDetailSystemFont\\fR\n\\fBsystemDetailEmphasizedSystemFont\\fR\n.DE\n.RE\n.SH EXAMPLE\n.PP\nFill a text widget with lots of font demonstrators, one for every font\nfamily installed on your system:\n.CS\npack [text .t -wrap none] -fill both -expand 1\nset count 0\nset tabwidth 0\nforeach family [lsort -dictionary [\\fBfont families\\fR]] {\n .t tag configure f[incr count] -font [list $family 10]\n .t insert end ${family}:\\et {} \\e\n \"This is a simple sampler\\en\" f$count\n set w [\\fBfont measure\\fR [.t cget -font] ${family}:]\n if {$w + 5 > $tabwidth} {\n set tabwidth [expr {$w + 5}]\n .t configure -tabs $tabwidth\n }\n}\n.CE\n.SH \"SEE ALSO\"\noptions(n)\n.SH KEYWORDS\nfont\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/fontchooser.n", "content": "'\\\"\n'\\\" Copyright (c) 2008 Daniel A. Steffen \n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH fontchooser n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nfontchooser \\- control font selection dialog\n.SH SYNOPSIS\n.nf\n\\fBtk fontchooser\\fR \\fBconfigure\\fR ?\\fI\\-option value ...\\fR?\n\\fBtk fontchooser\\fR \\fBshow\\fR\n\\fBtk fontchooser\\fR \\fBhide\\fR\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBtk fontchooser\\fR command controls the Tk font selection dialog. It uses\nthe native platform font selection dialog where available, or a dialog\nimplemented in Tcl otherwise.\n.PP\nUnlike most of the other Tk dialog commands, \\fBtk fontchooser\\fR does not\nreturn an immediate result, as on some platforms (macOS) the standard font\ndialog is modeless while on others (Windows) it is modal. To accommodate this\ndifference, all user interaction with the dialog will be communicated to the\ncaller via callbacks or virtual events.\n.PP\nThe \\fBtk fontchooser\\fR command can have one of the following forms:\n.\\\" METHOD: configure\n.TP\n\\fBtk fontchooser\\fR \\fBconfigure \\fR?\\fI\\-option value ...\\fR?\n.\nSet or query one or more of the configurations options below (analogous to Tk\nwidget configuration).\n.\\\" METHOD: show\n.TP\n\\fBtk fontchooser\\fR \\fBshow\\fR\n.\nShow the font selection dialog. Depending on the platform, may return\nimmediately or only once the dialog has been withdrawn.\n.\\\" METHOD: hide\n.TP\n\\fBtk fontchooser\\fR \\fBhide\\fR\n.\nHide the font selection dialog if it is visible and cause any pending\n\\fBtk fontchooser\\fR \\fBshow\\fR command to return.\n.PP\n.SH \"CONFIGURATION OPTIONS\"\n.\\\" OPTION: -parent\n.TP\n\\fB\\-parent\\fR\n.\nSpecifies/returns the logical parent window of the font selection dialog\n(similar to the \\fB\\-parent\\fR option to other dialogs). The font selection\ndialog is hidden if it is visible when the parent window is destroyed.\n.\\\" OPTION: -title\n.TP\n\\fB\\-title\\fR\n.\nSpecifies/returns the title of the dialog. Has no effect on platforms where the\nfont selection dialog does not support titles.\n.\\\" OPTION: -font\n.TP\n\\fB\\-font\\fR\n.\nSpecifies/returns the font that is currently selected in the dialog if it is\nvisible, or that will be initially selected when the dialog is shown (if\nsupported by the platform). Can be set to the empty string to indicate that no\nfont should be selected. Fonts can be specified in any form given by the \"FONT\nDESCRIPTION\" section in the \\fBfont\\fR manual page.\n.\\\" OPTION: -command\n.TP\n\\fB\\-command\\fR\n.\nSpecifies/returns the command prefix to be called when a font selection has\nbeen made by the user. The command prefix is evaluated at the global level\nafter having the specification of the selected font appended. On platforms\nwhere the font selection dialog offers the user control of further font\nattributes (such as color), additional key/value pairs may be appended before\nevaluation. Can be set to the empty string to indicate that no callback should\nbe invoked. Fonts are specified by a list of form [3] of the \"FONT DESCRIPTION\"\nsection in the \\fBfont\\fR manual page (i.e. a list of the form\n\\fI{family size style ?style ...?}\\fR).\n.\\\" OPTION: -visible\n.TP\n\\fB\\-visible\\fR\n.\nRead-only option that returns a boolean indicating whether the font selection\ndialog is currently visible. Attempting to set this option results in an error.\n\n.PP\n.SH \"VIRTUAL EVENTS\"\n.TP\n\\fB<>\\fR\n.\nSent to the dialog parent whenever the visibility of the font selection dialog\nchanges, both as a result of user action (e.g. disposing of the dialog via\nOK/Cancel button or close box) and of the \\fBtk fontchooser\\fR\n\\fBshow\\fR/\\fBhide\\fR commands being called. Binding scripts can determine the\ncurrent visibility of the dialog by querying the \\fB\\-visible\\fR configuration\noption.\n.TP\n\\fB<>\\fR\n.\nSent to the dialog parent whenever the font selection dialog is visible and the\nselected font changes, both as a result of user action and of the \\fB\\-font\\fR\nconfiguration option being set. Binding scripts can determine the currently\nselected font by querying the \\fB\\-font\\fR configuration option.\n.PP\n.SH NOTES\n.PP\nCallers should not expect a result from \\fBtk fontchooser\\fR \\fBshow\\fR and may\nnot assume that the dialog has been withdrawn or closed when the command\nreturns. All user interaction with the dialog is communicated to the caller via\nthe \\fB\\-command\\fR callback and the \\fB<>\\fR virtual events.\nIt is implementation dependent which exact user actions result in the callback\nbeing called resp. the virtual events being sent. Where an Apply or OK button\nis present in the dialog, that button will trigger the \\fB\\-command\\fR callback\nand \\fB<>\\fR virtual event. On some implementations\nother user actions may also have that effect; on macOS for instance, the\nstandard font selection dialog immediately reflects all user choices to the\ncaller.\n.PP\nIn the presence of multiple widgets intended to be influenced by the font\nselection dialog, care needs to be taken to correctly handle focus changes: the\nfont selected in the dialog should always match the current font of the widget\nwith the focus, and the \\fB\\-command\\fR callback should only act on the widget\nwith the focus. The recommended practice is to set font dialog \\fB\\-font\\fR and\n\\fB\\-command\\fR configuration options in per\\-widget \\fB\\fR handlers\n(and if necessary to unset them \\- i.e. set to the empty string \\- in\ncorresponding \\fB\\fR handlers). This is particularly important for\nimplementers of library code using the font selection dialog, to avoid\nconflicting with application code that may also want to use the dialog.\n.PP\nBecause the font selection dialog is application-global, in the presence of\nmultiple interpreters calling \\fBtk fontchooser\\fR, only the \\fB\\-command\\fR\ncallback set by the interpreter that most recently called \\fBtk fontchooser\\fR\n\\fBconfigure\\fR or \\fBtk fontchooser\\fR \\fBshow\\fR will be invoked in response\nto user action and only the \\fB\\-parent\\fR set by that interpreter will receive\n\\fB<>\\fR virtual events.\n.PP\nThe font dialog implementation may only store (and return) \\fBfont\\fR\n\\fBactual\\fR data as the value of the \\fB\\-font\\fR configuration option. This\ncan be an issue when \\fB\\-font\\fR is set to a named font, if that font is\nsubsequently changed, the font dialog \\fB\\-font\\fR option needs to be set again\nto ensure its selected font matches the new value of the named font.\n.PP\n.SH EXAMPLE\n.PP\n.CS\nproc fontchooserDemo {} {\n wm title . \"Font Chooser Demo\"\n \\fBtk fontchooser\\fR \\fBconfigure\\fR -parent .\n button .b -command fontchooserToggle -takefocus 0\n fontchooserVisibility .b\n bind . \\fB<>\\fR \\e\n [list fontchooserVisibility .b]\n foreach w {.t1 .t2} {\n text $w -width 20 -height 4 -borderwidth 1 -relief solid\n bind $w [list fontchooserFocus $w]\n $w insert end \"Text Widget $w\"\n }\n .t1 configure -font {Courier 14}\n .t2 configure -font {Times 16}\n pack .b .t1 .t2; focus .t1\n}\nproc fontchooserToggle {} {\n \\fBtk fontchooser\\fR [expr {\n [\\fBtk fontchooser\\fR \\fBconfigure\\fR -visible] ?\n \"\\fBhide\\fR\" : \"\\fBshow\\fR\"}]\n}\nproc fontchooserVisibility {w} {\n $w configure -text [expr {\n [\\fBtk fontchooser\\fR \\fBconfigure\\fR -visible] ?\n \"Hide Font Dialog\" : \"Show Font Dialog\"}]\n}\nproc fontchooserFocus {w} {\n \\fBtk fontchooser\\fR \\fBconfigure\\fR -font [$w cget -font] \\e\n -command [list fontchooserFontSelection $w]\n}\nproc fontchooserFontSelection {w font args} {\n $w configure -font [font actual $font]\n}\nfontchooserDemo\n.CE\n.SH \"SEE ALSO\"\nfont(n), tk(n)\n.SH KEYWORDS\ndialog, font, font selection, font chooser, font panel\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/frame.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH frame n 8.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nframe \\- Create and manipulate 'frame' simple container widgets\n.SH SYNOPSIS\n\\fBframe\\fI pathName\\fR ?\\fIoptions\\fR?\n.SO\n\\-borderwidth\t\\-highlightcolor\t\\-pady\n\\-cursor\t\\-highlightthickness\t\\-relief\n\\-highlightbackground\t\\-padx\t\\-takefocus\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-background background Background\nThis option is the same as the standard \\fB\\-background\\fR option\nexcept that its value may also be specified as an empty string.\nIn this case, the widget will display no background or border, and\nno colors will be consumed from its colormap for its background\nand border.\n.VS \"9.0, TIP262\"\nAn empty background will disable drawing the background image.\n.OP \\-backgroundimage backgroundImage BackgroundImage\nThis specifies an image to display on the frame's background within\nthe border of the frame (i.e., the image will be clipped by the\nframe's highlight ring and border, if either are present); subwidgets\nof the frame will be drawn on top. The image must have been created\nwith the \\fBimage create\\fR command. If specified as the empty string,\nno image will be displayed.\n.VE \"9.0, TIP262\"\n.OP \\-class class Class\nSpecifies a class for the window.\nThis class will be used when querying the option database for\nthe window's other options, and it will also be used later for\nother purposes such as bindings.\nThe \\fB\\-class\\fR option may not be changed with the \\fBconfigure\\fR\nwidget command.\n.OP \\-colormap colormap Colormap\nSpecifies a colormap to use for the window.\nThe value may be either \\fBnew\\fR, in which case a new colormap is\ncreated for the window and its children, or the name of another\nwindow (which must be on the same screen and have the same visual\nas \\fIpathName\\fR), in which case the new window will use the colormap\nfrom the specified window.\nIf the \\fB\\-colormap\\fR option is not specified, the new window\nuses the same colormap as its parent.\nThis option may not be changed with the \\fBconfigure\\fR\nwidget command.\n.OP \\-container container Container\nThe value must be a boolean. If true, it means that this window will\nbe used as a container in which some other application will be embedded\n(for example, a Tk toplevel can be embedded using the \\fB\\-use\\fR option).\nThe window will support the appropriate window manager protocols for\nthings like geometry requests. The window should not have any\nchildren of its own in this application.\nThis option may not be changed with the \\fBconfigure\\fR\nwidget command.\nNote that \\fB\\-borderwidth\\fR, \\fB\\-padx\\fR and \\fB\\-pady\\fR are ignored when\nconfigured as a container since a container has no border.\n.OP \\-height height Height\nSpecifies the desired height for the window in any of the forms\nacceptable to \\fBTk_GetPixels\\fR. If this option is negative or\nzero then the window will not request any size at all. Note that this\nsets the total height of the frame, any \\fB\\-borderwidth\\fR or similar is\nnot added. Normally \\fB\\-height\\fR should not be used if a propagating\ngeometry manager, such as \\fBgrid\\fR or \\fBpack\\fR, is used within the\nframe since the geometry manager will override the height of the frame.\n.OP \\-tile tile Tile\n.VS \"9.0, TIP262\"\nThis specifies how to draw the background image (see\n\\fB\\-backgroundimage\\fR) on the frame.\nIf true (according to \\fBTcl_GetBoolean\\fR), the image will be tiled\nto fill the whole frame, with the origin of the first copy of the\nimage being the top left of the interior of the frame.\nIf false (the default), the image will be centered within the frame.\n.VE \"9.0, TIP262\"\n.OP \\-visual visual Visual\nSpecifies visual information for the new window in any of the\nforms accepted by \\fBTk_GetVisual\\fR.\nIf this option is not specified, the new window will use the same\nvisual as its parent.\nThe \\fB\\-visual\\fR option may not be modified with the \\fBconfigure\\fR\nwidget command.\n.OP \\-width width Width\nSpecifies the desired width for the window in any of the forms\nacceptable to \\fBTk_GetPixels\\fR. If this option is negative or\nzero then the window will not request any size at all. Note that this\nsets the total width of the frame, any \\fB\\-borderwidth\\fR or similar is\nnot added. Normally \\fB\\-width\\fR should not be used if a propagating\ngeometry manager, such as \\fBgrid\\fR or \\fBpack\\fR, is used within the\nframe since the geometry manager will override the width of the frame.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBframe\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a frame widget.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the frame such as its background color\nand relief. The \\fBframe\\fR command returns the\npath name of the new window.\n.PP\nA frame is a simple widget. Its primary purpose is to act as a\nspacer or container for complex window layouts. The only features\nof a frame are its background and an optional 3-D border to make the\nframe appear raised or sunken.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBframe\\fR command creates a new Tcl command whose\nname is the same as the path name of the frame's window. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.PP\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n.PP\n\\fIPathName\\fR is the name of the command, which is the same as\nthe frame widget's path name. \\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for frame widgets:\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBframe\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBframe\\fR\ncommand.\n.SH BINDINGS\n.PP\nWhen a new frame is created, it has no default event bindings:\nframes are not intended to be interactive.\n.SH \"SEE ALSO\"\nlabelframe(n), toplevel(n), ttk::frame(n)\n.SH KEYWORDS\nframe, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/getOpenFile.n", "content": "'\\\"\n'\\\" Copyright (c) 1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk_getOpenFile n 4.2 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk_getOpenFile, tk_getSaveFile \\- pop up a dialog box for the user to select a file to open or save.\n.SH SYNOPSIS\n.nf\n\\fBtk_getOpenFile \\fR?\\fIoption value ...\\fR?\n\\fBtk_getSaveFile \\fR?\\fIoption value ...\\fR?\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nThe procedures \\fBtk_getOpenFile\\fR and \\fBtk_getSaveFile\\fR pop up a\ndialog box for the user to select a file to open or save. The\n\\fBtk_getOpenFile\\fR command is usually associated with the \\fBOpen\\fR\ncommand in the \\fBFile\\fR menu. Its purpose is for the user to select an\nexisting file \\fIonly\\fR. If the user enters a non-existent file, the\ndialog box gives the user an error prompt and requires the user to give\nan alternative selection. If an application allows the user to create\nnew files, it should do so by providing a separate \\fBNew\\fR menu command.\n.PP\nThe \\fBtk_getSaveFile\\fR command is usually associated with the \\fBSave\nas\\fR command in the \\fBFile\\fR menu. If the user enters a file that\nalready exists, the dialog box prompts the user for confirmation\nwhether the existing file should be overwritten or not.\n.PP\nThe following \\fIoption\\-value\\fR pairs are possible as command line\narguments to these two commands:\n.\\\" OPTION: -command\n.TP\n\\fB\\-command\\fI string\\fR\n.\nSpecifies the prefix of a Tcl command to invoke when the user closes the\ndialog after having selected an item. This callback is not called if the\nuser cancelled the dialog. The actual command consists of \\fIstring\\fR\nfollowed by a space and the value selected by the user in the dialog. This\nis only available on macOS.\n.\\\" OPTION: -confirmoverwrite\n.TP\n\\fB\\-confirmoverwrite\\fI boolean\\fR\n.\nConfigures how the Save dialog reacts when the selected file already\nexists, and saving would overwrite it. A true value requests a\nconfirmation dialog be presented to the user. A false value requests\nthat the overwrite take place without confirmation. Default value is true.\n.\\\" OPTION: -defaultextension\n.TP\n\\fB\\-defaultextension\\fI extension\\fR\n.\nSpecifies a string that will be appended to the filename if the user\nenters a filename without an extension. The default value is the empty\nstring, which means no extension will be appended to the filename in\nany case. This option is ignored on macOS, which\ndoes not require extensions to filenames,\nand the UNIX implementation guesses reasonable values for this from\nthe \\fB\\-filetypes\\fR option when this is not supplied.\n.\\\" OPTION: -filetypes\n.TP\n\\fB\\-filetypes\\fI filePatternList\\fR\n.\nIf a \\fBFile types\\fR listbox exists in the file dialog on the particular\nplatform, this option gives the \\fIfiletype\\fRs in this listbox. When\nthe user choose a filetype in the listbox, only the files of that type\nare listed. If this option is unspecified, or if it is set to the\nempty list, or if the \\fBFile types\\fR listbox is not supported by the\nparticular platform then all files are listed regardless of their\ntypes. See the section \\fBSPECIFYING FILE PATTERNS\\fR below for a\ndiscussion on the contents of \\fIfilePatternList\\fR.\n.\\\" OPTION: -initialdir\n.TP\n\\fB\\-initialdir\\fI directory\\fR\n.\nSpecifies that the files in \\fIdirectory\\fR should be displayed\nwhen the dialog pops up. If this parameter is not specified,\nthe initial directory defaults to the current working directory\non non-Windows systems and on Windows systems prior to Vista.\nOn Vista and later systems, the initial directory defaults to the last\nuser-selected directory for the application. If the\nparameter specifies a relative path, the return value will convert the\nrelative path to an absolute path.\n.\\\" OPTION: -initialfile\n.TP\n\\fB\\-initialfile\\fI filename\\fR\n.\nSpecifies a filename to be displayed in the dialog when it pops up.\n.\\\" OPTION: -message\n.TP\n\\fB\\-message\\fI string\\fR\n.\nSpecifies a message to include in the client area of the dialog.\nThis is only available on macOS.\n.\\\" OPTION: -multiple\n.TP\n\\fB\\-multiple\\fI boolean\\fR\n.\nAllows the user to choose multiple files from the Open dialog.\n.\\\" OPTION: -parent\n.TP\n\\fB\\-parent\\fI window\\fR\n.\nMakes \\fIwindow\\fR the logical parent of the file dialog. The file\ndialog is displayed on top of its parent window. On macOS, this\nturns the file dialog into a sheet attached to the parent window.\n.\\\" OPTION: -title\n.TP\n\\fB\\-title\\fI titleString\\fR\n.\nSpecifies a string to display as the title of the dialog box. If this\noption is not specified, then a default title is displayed.\n.\\\" OPTION: -typevariable\n.TP\n\\fB\\-typevariable\\fI variableName\\fR\n.\nThe global variable \\fIvariableName\\fR is used to preselect which filter is\nused from \\fIfilterList\\fR when the dialog box is opened and is\nupdated when the dialog box is closed, to the last selected\nfilter. The variable is read once at the beginning to select the\nappropriate filter. If the variable does not exist, or its value does\nnot match any filter typename, or is empty (\\fB{}\\fR), the dialog box\nwill revert to the default behavior of selecting the first filter in\nthe list. If the dialog is canceled, the variable is not modified.\n.PP\nIf the user selects a file, both \\fBtk_getOpenFile\\fR and\n\\fBtk_getSaveFile\\fR return the full pathname of this file. If the\nuser cancels the operation, both commands return the empty string.\n.SH \"SPECIFYING FILE PATTERNS\"\n.PP\nThe \\fIfilePatternList\\fR value given by the \\fB\\-filetypes\\fR option\nis a list of file patterns. Each file pattern is a list of the\nform\n.CS\n\\fItypeName\\fR {\\fIextension\\fR ?\\fIextension ...\\fR?} ?{\\fImacType\\fR ?\\fImacType ...\\fR?}?\n.CE\n\\fItypeName\\fR is the name of the file type described by this\nfile pattern and is the text string that appears in the \\fBFile types\\fR\nlistbox. \\fIextension\\fR is a file extension for this file pattern.\n\\fImacType\\fR is a four-character Macintosh file type. The list of\n\\fImacType\\fRs is optional and may be omitted for applications that do\nnot need to execute on the Macintosh platform.\n.PP\nSeveral file patterns may have the same \\fItypeName,\\fR in which case\nthey refer to the same file type and share the same entry in the\nlistbox. When the user selects an entry in the listbox, all the files\nthat match at least one of the file patterns corresponding\nto that entry are listed. Usually, each file pattern corresponds to a\ndistinct type of file. The use of more than one file pattern for one\ntype of file is only necessary on the Macintosh platform.\n.PP\nOn the Macintosh platform, a file matches a file pattern if its\nname matches at least one of the \\fIextension\\fR(s) AND it\nbelongs to at least one of the \\fImacType\\fR(s) of the\nfile pattern. For example, the \\fBC Source Files\\fR file pattern in the\nsample code matches with files that have a \\fB\\.c\\fR extension AND\nbelong to the \\fImacType\\fR \\fBTEXT\\fR. To use the OR rule instead,\nyou can use two file patterns, one with the \\fIextensions\\fR only and\nthe other with the \\fImacType\\fR only. The \\fBGIF Files\\fR file type\nin the sample code matches files that \\fIeither\\fR have a \\fB\\.gif\\fR\nextension OR belong to the \\fImacType\\fR \\fBGIFF\\fR.\n.PP\nOn the Unix and Windows platforms, a file matches a file pattern\nif its name matches at least one of the \\fIextension\\fR(s) of\nthe file pattern. The \\fImacType\\fRs are ignored.\n.SH \"SPECIFYING EXTENSIONS\"\n.PP\nOn the Unix and Macintosh platforms, extensions are matched using\nglob-style pattern matching. On the Windows platform, extensions are\nmatched by the underlying operating system. The types of possible\nextensions are:\n.IP (1)\nthe special extension\n.QW *\nmatches any file;\n.IP (2)\nthe special extension\n.MT\nmatches any files that do not have an extension (i.e., the filename\ncontains no full stop character);\n.IP (3)\nany character string that does not contain any wild card characters (*\nand ?).\n.PP\nDue to the different pattern matching rules on the various platforms,\nto ensure portability, wild card characters are not allowed in the\nextensions, except as in the special extension\n.QW * .\nExtensions without a full stop character (e.g.\n.QW ~ )\nare allowed but may not work on all platforms.\n.SH EXAMPLE\n.PP\n.CS\nset types {\n {{Text Files} {.txt} }\n {{TCL Scripts} {.tcl} }\n {{C Source Files} {.c} TEXT}\n {{GIF Files} {.gif} }\n {{GIF Files} {} GIFF}\n {{All Files} * }\n}\nset filename [\\fBtk_getOpenFile\\fR -filetypes $types]\n\nif {$filename ne \"\"} {\n # Open the file ...\n}\n.CE\n.SH \"SEE ALSO\"\ntk_chooseDirectory\n.SH KEYWORDS\nfile selection dialog\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/grab.n", "content": "'\\\"\n'\\\" Copyright (c) 1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH grab n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ngrab \\- Confine pointer and keyboard events to a window sub-tree\n.SH SYNOPSIS\n.nf\n\\fBgrab \\fR?\\fB\\-global\\fR? \\fIwindow\\fR\n\\fBgrab \\fIoption \\fR?\\fIarg \\fR...?\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nThis command implements simple pointer and keyboard grabs for Tk.\nTk's grabs are different than the grabs\ndescribed in the Xlib documentation.\nWhen a grab is set for a particular window, Tk restricts all pointer\nevents to the grab window and its descendants in Tk's window hierarchy.\nWhenever the pointer is within the grab window's subtree, the pointer\nwill behave exactly the same as if there had been no grab at all\nand all events will be reported in the normal fashion.\nWhen the pointer is outside \\fIwindow\\fR's tree, button presses and\nreleases and\nmouse motion events are reported to \\fIwindow\\fR, and window entry\nand window exit events are ignored. The grab subtree\n.QW owns\nthe pointer:\nwindows outside the grab subtree will be visible on the screen\nbut they will be insensitive until the grab is released.\nThe tree of windows underneath the grab window can include top-level\nwindows, in which case all of those top-level windows\nand their descendants will continue to receive mouse events\nduring the grab.\n.PP\nTwo forms of grabs are possible: local and global.\nA local grab affects only the grabbing application: events will\nbe reported to other applications as if the grab had never occurred.\nGrabs are local by default.\nA global grab locks out all applications on the screen,\nso that only the given subtree of the grabbing application will be\nsensitive to pointer events (mouse button presses, mouse button releases,\npointer motions, window entries, and window exits).\nDuring global grabs the window manager will not receive pointer\nevents either.\n.PP\nDuring local grabs, keyboard events (key presses and key releases)\nare delivered as usual: the window\nmanager controls which application receives keyboard events, and\nif they are sent to any window in the grabbing application then they are\nredirected to the focus window.\nDuring a global grab Tk grabs the keyboard so that all keyboard events\nare always sent to the grabbing application.\nThe \\fBfocus\\fR command is still used to determine which window in the\napplication receives the keyboard events.\nThe keyboard grab is released when the grab is released.\n.PP\nOn macOS a global grab affects all windows created by one Tk process.\nNo window in that process other than the grab window can even be\nfocused, hence no other window receives key or mouse events. A local\ngrab on macOS affects all windows created by one Tcl interpreter. It\nis possible to focus any window belonging to the Tk process during a\nlocal grab but the grab window is the only window created by its\ninterpreter which receives key or mouse events. Windows belonging to the\nsame process but created by different interpreters continue to receive\nkey and mouse events normally.\n.PP\nGrabs apply to particular displays. If an application has windows\non multiple displays then it can establish a separate grab on each\ndisplay.\nThe grab on a particular display affects only the windows on\nthat display.\nIt is possible for different applications on a single display to have\nsimultaneous local grabs, but only one application can have a global\ngrab on a given display at once.\n.PP\nThe \\fBgrab\\fR command can take any of the following forms:\n.TP\n\\fBgrab \\fR?\\fB\\-global\\fR? \\fIwindow\\fR\n.\nSame as \\fBgrab set\\fR, described below.\n.\\\" METHOD: current\n.TP\n\\fBgrab current \\fR?\\fIwindow\\fR?\n.\nIf \\fIwindow\\fR is specified, returns the name of the current grab\nwindow in this application for \\fIwindow\\fR's display, or an empty\nstring if there is no such window.\nIf \\fIwindow\\fR is omitted, the command returns a list whose elements\nare all of the windows grabbed by this application for all displays,\nor an empty string if the application has no grabs.\n.\\\" METHOD: release\n.TP\n\\fBgrab release \\fIwindow\\fR\n.\nReleases the grab on \\fIwindow\\fR if there is one, otherwise does\nnothing. Returns an empty string.\n.\\\" METHOD: set\n.TP\n\\fBgrab set \\fR?\\fB\\-global\\fR? \\fIwindow\\fR\n.\nSets a grab on \\fIwindow\\fR. If \\fB\\-global\\fR is specified then the\ngrab is global, otherwise it is local.\nIf a grab was already in effect for this application on\n\\fIwindow\\fR's display then it is automatically released.\nIf there is already a grab on \\fIwindow\\fR and it has the same\nglobal/local form as the requested grab, then the command\ndoes nothing. Returns an empty string.\n.\\\" METHOD: status\n.TP\n\\fBgrab status \\fIwindow\\fR\n.\nReturns \\fBnone\\fR if no grab is currently set on \\fIwindow\\fR,\n\\fBlocal\\fR if a local grab is set on \\fIwindow\\fR, and\n\\fBglobal\\fR if a global grab is set.\n.SH WARNING\n.PP\nIt is very easy to use global grabs to render a display completely\nunusable (e.g. by setting a grab on a widget which does not respond to\nevents and not providing any mechanism for releasing the grab). Take\n\\fIextreme\\fR care when using them!\n.SH BUGS\n.PP\nIt took an incredibly complex and gross implementation to produce\nthe simple grab effect described above.\nGiven the current implementation, it is not safe for applications\nto use the Xlib grab facilities at all except through the Tk grab\nprocedures.\nIf applications try to manipulate X's grab mechanisms directly,\nthings will probably break.\n.PP\nIf a single process is managing several different Tk applications,\nonly one of those applications can have a local grab for a given\ndisplay at any given time. If the applications are in different\nprocesses, this restriction does not exist.\n.SH EXAMPLE\n.PP\nSet a grab so that only one button may be clicked out of a group. The\nother buttons are unresponsive to the mouse until the middle button is\nclicked.\n.CS\npack [button .b1 -text \"Click me! #1\" -command {destroy .b1}]\npack [button .b2 -text \"Click me! #2\" -command {destroy .b2}]\npack [button .b3 -text \"Click me! #3\" -command {destroy .b3}]\n\\fBgrab\\fR .b2\n.CE\n.SH \"SEE ALSO\"\nbusy(n)\n.SH KEYWORDS\ngrab, keyboard events, pointer events, window\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/grid.n", "content": "'\\\"\n'\\\" Copyright (c) 1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH grid n 8.5 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ngrid \\- Geometry manager that arranges widgets in a grid\n.SH SYNOPSIS\n\\fBgrid \\fIoption arg \\fR?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBgrid\\fR command is used to communicate with the grid\ngeometry manager that arranges widgets in rows and columns inside\nof another window, called the geometry container (or container window).\nThe \\fBgrid\\fR command can have any of several forms, depending\non the \\fIoption\\fR argument:\n.TP\n\\fBgrid \\fIwindow \\fR?\\fIwindow ...\\fR? ?\\fIoptions\\fR?\n.\nIf the first argument to \\fBgrid\\fR is suitable as the first window\nargument to \\fBgrid configure\\fR, either a window name (any value\nstarting with \\fB.\\fR) or one of the characters \\fBx\\fR or \\fB^\\fR\n(see the \\fBRELATIVE PLACEMENT\\fR section below), then the command is\nprocessed in the same way as \\fBgrid configure\\fR.\n.\\\" METHOD: anchor\n.TP\n\\fBgrid anchor \\fIwindow\\fR ?\\fIanchor\\fR?\n.\nThe anchor value controls how to place the grid within the container window\nwhen no row/column has any weight. See \\fBTHE GRID ALGORITHM\\fR below\nfor further details. The default \\fIanchor\\fR is \\fInw\\fR.\n.\\\" METHOD: bbox\n.TP\n\\fBgrid bbox \\fIwindow\\fR ?\\fIcolumn row\\fR? ?\\fIcolumn2 row2\\fR?\n.\nWith no arguments,\nthe bounding box (in pixels) of the grid is returned.\nThe return value consists of 4 integers. The first two are the pixel\noffset from the container window (x then y) of the top-left corner of the\ngrid, and the second two integers are the width and height of the grid,\nalso in pixels. If a single \\fIcolumn\\fR and \\fIrow\\fR is specified on\nthe command line, then the bounding box for that cell is returned, where the\ntop left cell is numbered from zero. If both \\fIcolumn\\fR and \\fIrow\\fR\narguments are specified, then the bounding box spanning the rows and columns\nindicated is returned.\n.\\\" METHOD: columnconfigure\n.TP\n\\fBgrid columnconfigure \\fIwindow index \\fR?\\fI\\-option value...\\fR?\n.\nQuery or set the column properties of the \\fIindex\\fR column of the\ngeometry container, \\fIwindow\\fR.\nThe valid options are \\fB\\-minsize\\fR, \\fB\\-weight\\fR, \\fB\\-uniform\\fR\nand \\fB\\-pad\\fR.\nIf one or more options are provided, then \\fIindex\\fR may be given as\na list of column indices to which the configuration options will operate on.\nIndices may be integers, window names or the keyword \\fIall\\fR. For \\fIall\\fR\nthe options apply to all columns currently occupied be content windows. For\na window name, that window must be a content of this container and the options\napply to all columns currently occupied be the content.\nThe \\fB\\-minsize\\fR option sets the minimum size, in screen units,\nthat will be permitted for this column.\nThe \\fB\\-weight\\fR option (an integer value)\nsets the relative weight for apportioning\nany extra spaces among\ncolumns.\nA weight of zero (0) indicates the column will not deviate from its requested\nsize. A column whose weight is two will grow at twice the rate as a column\nof weight one when extra space is allocated to the layout.\nThe \\fB\\-uniform\\fR option, when a non-empty value is supplied, places\nthe column in a \\fIuniform group\\fR with other columns that have the\nsame value for \\fB\\-uniform\\fR. The space for columns belonging to a\nuniform group is allocated so that their sizes are always in strict\nproportion to their \\fB\\-weight\\fR values. See\n\\fBTHE GRID ALGORITHM\\fR below for further details.\nThe \\fB\\-pad\\fR option specifies the number of screen units that will be\nadded to the largest window contained completely in that column when the\ngrid geometry manager requests a size from the containing window.\nIf only an option is specified, with no value,\nthe current value of that option is returned.\nIf only the container window and index is specified, all the current settings\nare returned in a list of\n.QW \"\\fI\\-option value\\fR\"\npairs.\n.\\\" METHOD: configure\n.TP\n\\fBgrid configure \\fIwindow \\fR?\\fIwindow ...\\fR? ?\\fIoptions\\fR?\n.\nThe arguments consist of the names of one or more content windows\nfollowed by pairs of arguments that specify how\nto manage the content.\nThe characters \\fB\\-\\fR, \\fBx\\fR and \\fB^\\fR,\ncan be specified instead of a window name to alter the default\nlocation of a \\fIwindow\\fR, as described in the \\fBRELATIVE PLACEMENT\\fR\nsection, below.\nThe following options are supported:\n.RS\n.\\\" OPTION: -column\n.TP\n\\fB\\-column \\fIn\\fR\n.\nInsert the window so that it occupies the \\fIn\\fRth column in the grid.\nColumn numbers start with 0. If this option is not supplied, then the\nwindow is arranged just to the right of previous window specified on this\ncall to \\fBgrid\\fR, or column\n.QW 0\nif it is the first window. For each\n\\fBx\\fR that immediately precedes the \\fIwindow\\fR, the column position\nis incremented by one. Thus the \\fBx\\fR represents a blank column\nfor this row in the grid.\n.\\\" OPTION: -columnspan\n.TP\n\\fB\\-columnspan \\fIn\\fR\n.\nInsert the window so that it occupies \\fIn\\fR columns in the grid.\nThe default is one column, unless the window name is followed by a\n\\fB\\-\\fR, in which case the columnspan is incremented once for each immediately\nfollowing \\fB\\-\\fR.\n.\\\" OPTION: -in\n.TP\n\\fB\\-in \\fIcontainer\\fR\n.\nInsert the window(s) in the container\nwindow given by \\fIcontainer\\fR. The default is the first window's\nparent window.\n.\\\" OPTION: -ipadx\n.TP\n\\fB\\-ipadx \\fIamount\\fR\n.\nThe \\fIamount\\fR specifies how much horizontal internal padding to\nleave on each side of the content. This is space is added\ninside the content border.\nThe \\fIamount\\fR must be a valid screen distance, such as \\fB2\\fR or \\fB.5c\\fR.\nIt defaults to 0.\n.\\\" OPTION: -ipady\n.TP\n\\fB\\-ipady \\fIamount\\fR\n.\nThe \\fIamount\\fR specifies how much vertical internal padding to\nleave on the top and bottom of the content.\nThis space is added inside the content border.\nThe \\fIamount\\fR defaults to 0.\n.\\\" OPTION: -padx\n.TP\n\\fB\\-padx \\fIamount\\fR\n.\nThe \\fIamount\\fR specifies how much horizontal external padding to\nleave on each side of the content, in screen units.\n\\fIAmount\\fR may be a list\nof two values to specify padding for left and right separately.\nThe \\fIamount\\fR defaults to 0.\nThis space is added outside the content border.\n.\\\" OPTION: -pady\n.TP\n\\fB\\-pady \\fIamount\\fR\n.\nThe \\fIamount\\fR specifies how much vertical external padding to\nleave on the top and bottom of the content, in screen units.\n\\fIAmount\\fR may be a list\nof two values to specify padding for top and bottom separately.\nThe \\fIamount\\fR defaults to 0.\nThis space is added outside the content border.\n.\\\" OPTION: -row\n.TP\n\\fB\\-row \\fIn\\fR\n.\nInsert the content so that it occupies the \\fIn\\fRth row in the grid.\nRow numbers start with 0. If this option is not supplied, then the\ncontent is arranged on the same row as the previous content specified on this\ncall to \\fBgrid\\fR, or the next row after the highest occupied row\nif this is the first content.\n.\\\" OPTION: -rowspan\n.TP\n\\fB\\-rowspan \\fIn\\fR\n.\nInsert the content so that it occupies \\fIn\\fR rows in the grid.\nThe default is one row. If the next \\fBgrid\\fR command contains\n\\fB^\\fR characters instead of \\fIcontent\\fR that line up with the columns\nof this \\fIcontent\\fR, then the \\fBrowspan\\fR of this \\fIcontent\\fR is\nextended by one.\n.\\\" OPTION: -sticky\n.TP\n\\fB\\-sticky \\fIstyle\\fR\n.\nIf a content's cell is larger than its requested dimensions, this\noption may be used to position (or stretch) the content within its cell.\n\\fIStyle\\fR is a string that contains zero or more of the characters\n\\fBn\\fR, \\fBs\\fR, \\fBe\\fR or \\fBw\\fR.\nThe string can optionally contain spaces or\ncommas, but they are ignored. Each letter refers to a side (north, south,\neast, or west) that the content will\n.QW stick\nto. If both \\fBn\\fR and \\fBs\\fR (or \\fBe\\fR and \\fBw\\fR) are\nspecified, the content will be stretched to fill the entire\nheight (or width) of its cavity. The \\fB\\-sticky\\fR option subsumes the\ncombination of \\fB\\-anchor\\fR and \\fB\\-fill\\fR that is used by \\fBpack\\fR.\nThe default is\n.QW \"\" ,\nwhich causes the content to be centered in its cavity, at its requested size.\n.LP\nIf any of the content is already managed by the geometry manager\nthen any unspecified options for them retain their previous values rather\nthan receiving default values.\n.RE\n.\\\" METHOD: content\n.TP\n\\fBgrid content \\fIwindow\\fR ?\\fI\\-option value\\fR?\n.\nIf no options are supplied, a list of all of the content in \\fIwindow\\fR\nis returned, most recently managed first.\n\\fIOption\\fR can be either \\fB\\-row\\fR or \\fB\\-column\\fR which\ncauses only the content in the row (or column) specified by \\fIvalue\\fR\nto be returned.\n.\\\" METHOD: forget\n.TP\n\\fBgrid forget \\fIwindow \\fR?\\fIwindow ...\\fR?\n.\nRemoves each of the \\fIwindow\\fRs from grid for its\ncontainer and unmaps their windows.\nThe content will no longer be managed by the grid geometry manager.\nThe configuration options for that window are forgotten, so that if the\nwindow is managed once more by the grid geometry manager, the initial\ndefault settings are used.\n.RS\n.PP\n.VS \"TIP 518\"\nIf the last content window of the container becomes unmanaged, this will also\nsend the virtual event \\fB<>\\fR to the container; the container\nmay choose to resize itself (or otherwise respond) to such a change.\n.VE \"TIP 518\"\n.RE\n.\\\" METHOD: info\n.TP\n\\fBgrid info \\fIwindow\\fR\n.\nReturns a list whose elements are the current configuration state of\nthe content given by \\fIwindow\\fR in the same option-value form that\nmight be specified to \\fBgrid configure\\fR.\nThe first two elements of the list are\n.QW \"\\fB\\-in \\fIcontainer\\fR\"\nwhere \\fIcontainer\\fR is the windows's container window.\n.\\\" METHOD: location\n.TP\n\\fBgrid location \\fIwindow x y\\fR\n.\nGiven \\fIx\\fR and \\fIy\\fR values in screen units relative to the container\nwindow, the column and row number at that \\fIx\\fR and \\fIy\\fR location is\nreturned. For locations that are above or to the left of the grid, \\fB\\-1\\fR\nis returned.\n.\\\" METHOD: propagate\n.TP\n\\fBgrid propagate \\fIwindow\\fR ?\\fIboolean\\fR?\n.\nIf \\fIboolean\\fR has a true boolean value such as \\fB1\\fR or \\fBon\\fR\nthen propagation is enabled for \\fIwindow\\fR, which must be a window\nname (see \\fBGEOMETRY PROPAGATION\\fR below).\nIf \\fIboolean\\fR has a false boolean value then propagation is\ndisabled for \\fIwindow\\fR.\nIn either of these cases an empty string is returned.\nIf \\fIboolean\\fR is omitted then the command returns \\fB0\\fR or\n\\fB1\\fR to indicate whether propagation is currently enabled\nfor \\fIwindow\\fR.\n.RS\n.PP\nPropagation is enabled by default.\n.RE\n.\\\" METHOD: rowconfigure\n.TP\n\\fBgrid rowconfigure \\fIwindow index \\fR?\\fI\\-option value...\\fR?\n.\nQuery or set the row properties of the \\fIindex\\fR row of the\ngeometry container, \\fIwindow\\fR.\nThe valid options are \\fB\\-minsize\\fR, \\fB\\-weight\\fR, \\fB\\-uniform\\fR\nand \\fB\\-pad\\fR.\nIf one or more options are provided, then \\fIindex\\fR may be given as\na list of row indices to which the configuration options will operate on.\nIndices may be integers, window names or the keyword \\fIall\\fR. For \\fIall\\fR\nthe options apply to all rows currently occupied by content windows. For a\nwindow name, that window must be a content window of this container and the\noptions apply to all rows currently occupied by the container window.\nThe \\fB\\-minsize\\fR option sets the minimum size, in screen units,\nthat will be permitted for this row.\nThe \\fB\\-weight\\fR option (an integer value)\nsets the relative weight for apportioning\nany extra spaces among\nrows.\nA weight of zero (0) indicates the row will not deviate from its requested\nsize. A row whose weight is two will grow at twice the rate as a row\nof weight one when extra space is allocated to the layout.\nThe \\fB\\-uniform\\fR option, when a non-empty value is supplied, places\nthe row in a \\fIuniform group\\fR with other rows that have the\nsame value for \\fB\\-uniform\\fR. The space for rows belonging to a\nuniform group is allocated so that their sizes are always in strict\nproportion to their \\fB\\-weight\\fR values. See\n\\fBTHE GRID ALGORITHM\\fR below for further details.\nThe \\fB\\-pad\\fR option specifies the number of screen units that will be\nadded to the largest window contained completely in that row when the\ngrid geometry manager requests a size from the containing window.\nIf only an option is specified, with no value,\nthe current value of that option is returned.\nIf only the container window and index is specified, all the current settings\nare returned in a list of\n.QW \"-option value\"\npairs.\n.\\\" METHOD: remove\n.TP\n\\fBgrid remove \\fIwindow \\fR?\\fIwindow ...\\fR?\n.\nRemoves each of the \\fIwindow\\fRs from grid for its\ncontainer and unmaps their windows.\nThe content will no longer be managed by the grid geometry manager.\nHowever, the configuration options for that window are remembered,\nso that if the content window is managed once more by the grid\ngeometry manager, the previous values are retained.\n.RS\n.PP\n.VS \"TIP 518\"\nIf the last content window of the container becomes unmanaged, this will also\nsend the virtual event \\fB<>\\fR to the container; the\ncontainer may choose to resize itself (or otherwise respond) to such a change.\n.VE \"TIP 518\"\n.RE\n.\\\" METHOD: size\n.TP\n\\fBgrid size \\fIcontainer\\fR\n.\nReturns the size of the grid (in columns then rows) for \\fIcontainer\\fR.\nThe size is determined either by the \\fIcontent\\fR occupying the largest\nrow or column, or the largest column or row with a \\fB\\-minsize\\fR,\n\\fB\\-weight\\fR, or \\fB\\-pad\\fR that is non-zero.\n.\\\" METHOD: slaves\n.TP\n\\fBgrid slaves \\fIwindow\\fR ?\\fI\\-option value\\fR?\n.\nSynonym for \\fBgrid content \\fIwindow\\fR ?\\fI\\-option value\\fR?.\n.SH \"RELATIVE PLACEMENT\"\n.PP\nThe \\fBgrid\\fR command contains a limited set of capabilities that\npermit layouts to be created without specifying the row and column\ninformation for each content. This permits content to be rearranged,\nadded, or removed without the need to explicitly specify row and\ncolumn information.\nWhen no column or row information is specified for a \\fIcontent\\fR,\ndefault values are chosen for\n\\fB\\-column\\fR, \\fB\\-row\\fR, \\fB\\-columnspan\\fR and \\fB\\-rowspan\\fR\nat the time the \\fIcontent\\fR is managed. The values are chosen\nbased upon the current layout of the grid, the position of the \\fIcontent\\fR\nrelative to other \\fIcontent\\fRs in the same grid command, and the presence\nof the characters \\fB\\-\\fR, \\fBx\\fR, and \\fB^\\fR in \\fBgrid\\fR\ncommand where \\fIcontent\\fR names are normally expected.\n.RS\n.IP \\fB\\-\\fR\nThis increases the \\fB\\-columnspan\\fR of the \\fIcontent\\fR to the left. Several\n\\fB\\-\\fR's in a row will successively increase the number of columns spanned.\nA \\fB\\-\\fR may not follow a \\fB^\\fR or a \\fBx\\fR, nor may it be the first\n\\fIcontent\\fR argument to \\fBgrid configure\\fR.\n.IP \\fBx\\fR\nThis leaves an empty column between the \\fIcontent\\fR on the left and\nthe \\fIcontent\\fR on the right.\n.IP \\fB^\\fR\nThis extends the \\fB\\-rowspan\\fR of the \\fIcontent\\fR above the \\fB^\\fR's\nin the grid. The number of \\fB^\\fR's in a row must match the number of\ncolumns spanned by the \\fIcontent\\fR above it.\n.RE\n.SH \"THE GRID ALGORITHM\"\n.PP\nThe grid geometry manager lays out its content in three steps.\nIn the first step, the minimum size needed to fit all of the content\nis computed, then (if propagation is turned on), a request is made\nof the container window to become that size.\nIn the second step, the requested size is compared against the actual size\nof the container. If the sizes are different, then spaces is added to or taken\naway from the layout as needed.\nFor the final step, each content is positioned in its row(s) and column(s)\nbased on the setting of its \\fIsticky\\fR flag.\n.PP\nTo compute the minimum size of a layout, the grid geometry manager first looks\nat all content whose \\fB\\-columnspan\\fR and \\fB\\-rowspan\\fR values are one,\nand computes the nominal size of each row or column to be either the\n\\fIminsize\\fR for that row or column, or the sum of the \\fIpad\\fRding\nplus the size of the largest content, whichever is greater. After that\nthe rows or columns in each uniform group adapt to each other. Then\nthe content whose row-spans or column-spans are greater than one are\nexamined. If a group of rows or columns need to be increased in size\nin order to accommodate these content, then extra space is added to each\nrow or column in the group according to its \\fIweight\\fR. For each\ngroup whose weights are all zero, the additional space is apportioned\nequally.\n.PP\nWhen multiple rows or columns belong to a uniform group, the space\nallocated to them is always in proportion to their weights. (A weight\nof zero is considered to be 1.) In other words, a row or column\nconfigured with \\fB\\-weight 1 \\-uniform a\\fR will have exactly the same\nsize as any other row or column configured with \\fB\\-weight 1 \\-uniform\na\\fR. A row or column configured with \\fB\\-weight 2 \\-uniform b\\fR will\nbe exactly twice as large as one that is configured with \\fB\\-weight 1\n\\-uniform b\\fR.\n.PP\nMore technically, each row or column in the group will have a size\nequal to \\fIk*weight\\fR for some constant \\fIk\\fR. The constant\n\\fIk\\fR is chosen so that no row or column becomes smaller than its\nminimum size. For example, if all rows or columns in a group have the\nsame weight, then each row or column will have the same size as the\nlargest row or column in the group.\n.PP\nFor containers whose size is larger than the requested layout, the additional\nspace is apportioned according to the row and column weights. If all of\nthe weights are zero, the layout is placed within its container according to\nthe \\fIanchor\\fR value.\nFor containers whose size is smaller than the requested layout, space is taken\naway from columns and rows according to their weights. However, once a\ncolumn or row shrinks to its minsize, its weight is taken to be zero.\nIf more space needs to be removed from a layout than would be permitted, as\nwhen all the rows or columns are at their minimum sizes, the layout is\nplaced and clipped according to the \\fIanchor\\fR value.\n.SH \"GEOMETRY PROPAGATION\"\n.PP\nThe grid geometry manager normally computes how large a container must be to\njust exactly meet the needs of its content, and it sets the\nrequested width and height of the container to these dimensions.\nThis causes geometry information to propagate up through a\nwindow hierarchy to a top-level window so that the entire\nsub-tree sizes itself to fit the needs of the leaf windows.\nHowever, the \\fBgrid propagate\\fR command may be used to\nturn off propagation for one or more containers.\nIf propagation is disabled then grid will not set\nthe requested width and height of the container window.\nThis may be useful if, for example, you wish for a container\nwindow to have a fixed size that you specify.\n.SH \"RESTRICTIONS ON CONTAINER WINDOWS\"\n.PP\nThe container for each content must either be the content's parent\n(the default) or a descendant of the content's parent.\nThis restriction is necessary to guarantee that the\ncontent can be placed over any part of its container that is\nvisible without danger of the content being clipped by its parent.\nIn addition, all content in one call to \\fBgrid\\fR must have the same container.\n.SH \"STACKING ORDER\"\n.PP\nIf the container for a content is not its parent then you must make sure\nthat the content is higher in the stacking order than the container.\nOtherwise the container will obscure the content and it will appear as\nif the content has not been managed correctly.\nThe easiest way to make sure the content is higher than the container is\nto create the container window first: the most recently created window\nwill be highest in the stacking order.\n.SH CREDITS\n.PP\nThe \\fBgrid\\fR command is based on ideas taken from the \\fIGridBag\\fR\ngeometry manager written by Doug. Stein, and the \\fBblt_table\\fR geometry\nmanager, written by George Howlett.\n.SH EXAMPLES\n.PP\nA toplevel window containing a text widget and two scrollbars:\n.PP\n.CS\n# Make the widgets\ntoplevel .t\ntext .t.txt -wrap none -xscroll {.t.h set} -yscroll {.t.v set}\nscrollbar .t.v -orient vertical -command {.t.txt yview}\nscrollbar .t.h -orient horizontal -command {.t.txt xview}\n\n# Lay them out\n\\fBgrid\\fR .t.txt .t.v -sticky nsew\n\\fBgrid\\fR .t.h -sticky nsew\n\n# Tell the text widget to take all the extra room\n\\fBgrid rowconfigure\\fR .t .t.txt -weight 1\n\\fBgrid columnconfigure\\fR .t .t.txt -weight 1\n.CE\n.PP\nThree widgets of equal width, despite their different\n.QW natural\nwidths:\n.PP\n.CS\nbutton .b -text \"Foo\"\nentry .e -textvariable foo ; set foo \"Hello World!\"\nlabel .l -text \"This is a fairly long piece of text\"\n\n\\fBgrid\\fR .b .e .l -sticky ew\n\\fBgrid columnconfigure\\fR . \"all\" -uniform allTheSame\n.CE\n.SH \"SEE ALSO\"\npack(n), place(n)\n.SH KEYWORDS\ngeometry manager, location, grid, cell, propagation, size, pack\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/image.n", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH image n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nimage \\- Create and manipulate images\n.SH SYNOPSIS\n\\fBimage\\fI option \\fR?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBimage\\fR command is used to create, delete, and query images.\nIt can take several different forms, depending on the\n\\fIoption\\fR argument. The legal forms are:\n.\\\" METHOD: create\n.TP\n\\fBimage create \\fItype \\fR?\\fIname\\fR? ?\\fIoption value ...\\fR?\n.\nCreates a new image and a command with the same name and returns its name.\n\\fItype\\fR specifies the type of the image, which must be one of\nthe types currently defined (e.g., \\fBbitmap\\fR).\n\\fIname\\fR specifies the name for the image; if it is omitted then\nTk picks a name of the form \\fBimage\\fIx\\fR, where \\fIx\\fR is\nan integer.\nThere may be any number of \\fIoption\\fR\\-\\fIvalue\\fR pairs,\nwhich provide configuration options for the new image.\nThe legal set of options is defined separately for each image\ntype; see below for details on the options for built-in image types.\nIf an image already exists by the given name then it is replaced\nwith the new image and any instances of that image will redisplay\nwith the new contents.\nIt is important to note that the image command will silently overwrite any\nprocedure that may currently be defined by the given name, so choose the\nname wisely. It is recommended to use a separate namespace for image names\n(e.g., \\fB::img::logo\\fR, \\fB::img::large\\fR).\n.\\\" METHOD: delete\n.TP\n\\fBimage delete \\fR?\\fIname name\\fR ...?\n.\nDeletes each of the named images and returns an empty string.\nIf there are instances of the images displayed in widgets,\nthe images will not actually be deleted until all of the instances\nare released.\nHowever, the association between the instances and the image\nmanager will be dropped.\nExisting instances will retain their sizes but redisplay as\nempty areas.\nIf a deleted image is recreated with another call to \\fBimage create\\fR,\nthe existing instances will use the new image.\n.\\\" METHOD: height\n.TP\n\\fBimage height \\fIname\\fR\n.\nReturns a decimal string giving the height of image \\fIname\\fR\nin pixels.\n.\\\" METHOD: inuse\n.TP\n\\fBimage inuse \\fIname\\fR\n.\nReturns a boolean value indicating whether or not the image given by\n\\fIname\\fR is in use by any widgets.\n.\\\" METHOD: names\n.TP\n\\fBimage names\\fR\n.\nReturns a list containing the names of all existing images.\n.\\\" METHOD: type\n.TP\n\\fBimage type \\fIname\\fR\n.\nReturns the type of image \\fIname\\fR (the value of the \\fItype\\fR\nargument to \\fBimage create\\fR when the image was created).\n.\\\" METHOD: types\n.TP\n\\fBimage types\\fR\n.\nReturns a list whose elements are all of the valid image types\n(i.e., all of the values that may be supplied for the \\fItype\\fR\nargument to \\fBimage create\\fR).\n.\\\" METHOD: width\n.TP\n\\fBimage width \\fIname\\fR\n.\nReturns a decimal string giving the width of image \\fIname\\fR\nin pixels.\n.PP\nAdditional operations (e.g. writing the image to a file) may be\navailable as subcommands of the image instance command. See the manual\npage for the particular image type for details.\n.SH \"BUILT-IN IMAGE TYPES\"\n.PP\nThe following image types are defined by Tk so they will be available\nin any Tk application.\nIndividual applications or extensions may define additional types.\n.IP \\fBbitmap\\fR\nEach pixel in the image displays a foreground color, a background\ncolor, or nothing.\nSee the \\fBbitmap\\fR manual entry for more information.\n.IP \\fBphoto\\fR\nDisplays a variety of full-color images, using dithering to\napproximate colors on displays with limited color capabilities.\nSee the \\fBphoto\\fR manual entry for more information.\n.IP \\fBnsimage\\fR\nThis type is only available in the Aqua platform. It is a full-color\nimage which may be created from a named system image. It has options\ndesigned to facilitate the use of these images in buttons. An\n\\fBnsimage\\fR can be based on an a \\fItemplate image\\fR, which is an\nanti-aliased 2-color image format that automatically interchanges\nblack and white in response to changes between the light and dark\nmodes on macOS. An \\fBnsimage\\fR can also generate an alternate\n\\fIpressed\\fR variant which is lighter in dark mode and darker in\nlight mode. These are for use in image buttons. See the \\fBnsimage\\fR\nmanual entry for more information.\n.SH \"SEE ALSO\"\nbitmap(n), options(n), photo(n), nsimage(n)\n.SH KEYWORDS\nheight, image, types of images, width\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/keysyms.n", "content": "'\\\"\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" All rights reserved.\n'\\\"\n.TH keysyms n 8.3 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nkeysyms \\- keysyms recognized by Tk\n.BE\n.SH DESCRIPTION\n.PP\nTk recognizes many keysyms when specifying key bindings (e.g.,\n.QW \"\\fBbind\\fR \\fB. <\\fR\\fIkeysym\\fR\\fB>\\fR\" ).\nThe following list enumerates the\nkeysyms that will be recognized by Tk. Note that not all keysyms will\nbe valid on all platforms, and some keysyms are also available on\nplatforms that have a different native name for that key.\nFor example, on Unix systems, the presence\nof a particular keysym is dependent on the configuration of the\nkeyboard modifier map. This list shows keysyms along with their\ndecimal and hexadecimal values.\n.PP\n.CS\nspace 32 0x20\n! (exclam) 33 0x21\nquotedbl 34 0x22\nnumbersign 35 0x23\ndollar 36 0x24\n% (percent) 37 0x25\n& (ampersand) 38 0x26\n' (apostrophe) 39 0x27\n( (parenleft) 40 0x28\n) (parenright) 41 0x29\n* (asterisk) 42 0x2A\n+ (plus) 43 0x2B\n, (comma) 44 0x2C\nminus 45 0x2D\n. (period) 46 0x2E\n/ (slash) 47 0x2F\n0 48 0x30\n1 49 0x31\n2 50 0x32\n3 51 0x33\n4 52 0x34\n5 53 0x35\n6 54 0x36\n7 55 0x37\n8 56 0x38\n9 57 0x39\n: (colon) 58 0x3A\nsemicolon 59 0x3B\nless 60 0x3C\n= (equal) 61 0x3D\ngreater 62 0x3E\n? (question) 63 0x3F\n@ (at) 64 0x40\nA 65 0x41\nB 66 0x42\nC 67 0x43\nD 68 0x44\nE 69 0x45\nF 70 0x46\nG 71 0x47\nH 72 0x48\nI 73 0x49\nJ 74 0x4A\nK 75 0x4B\nL 76 0x4C\nM 77 0x4D\nN 78 0x4E\nO 79 0x4F\nP 80 0x50\nQ 81 0x51\nR 82 0x52\nS 83 0x53\nT 84 0x54\nU 85 0x55\nV 86 0x56\nW 87 0x57\nX 88 0x58\nY 89 0x59\nZ 90 0x5A\nbracketleft 91 0x5B\nbackslash 92 0x5C\nbracketright 93 0x5D\n^ (asciicircum) 94 0x5E\n_ (underscore) 95 0x5F\n` (grave) 96 0x60\na 97 0x61\nb 98 0x62\nc 99 0x63\nd 100 0x64\ne 101 0x65\nf 102 0x66\ng 103 0x67\nh 104 0x68\ni 105 0x69\nj 106 0x6A\nk 107 0x6B\nl 108 0x6C\nm 109 0x6D\nn 110 0x6E\no 111 0x6F\np 112 0x70\nq 113 0x71\nr 114 0x72\ns 115 0x73\nt 116 0x74\nu 117 0x75\nv 118 0x76\nw 119 0x77\nx 120 0x78\ny 121 0x79\nz 122 0x7A\nbraceleft 123 0x7B\n| (bar) 124 0x7C\nbraceright 125 0x7D\n~ (asciitilde) 126 0x7E\nnobreakspace 160 0xA0\n\\(r! (exclamdown) 161 0xA1\n\\(ct (cent) 162 0xA2\n\\(Po (sterling) 163 0xA3\n\\(Cs (currency) 164 0xA4\n\\(Ye (yen) 165 0xA5\n\\(bb (brokenbar) 166 0xA6\n\\(sc (section) 167 0xA7\n\\(ad (diaeresis) 168 0xA8\n\\(co (copyright) 169 0xA9\n\\(Of (ordfeminine) 170 0xAA\n\\(Fo (guillemetleft) 171 0xAB\n\\(no (notsign) 172 0xAC\nhyphen 173 0xAD\n\\(rg (registered) 174 0xAE\n\\(a- (macron) 175 0xAF\n\\(de (degree) 176 0xB0\n\\(+- (plusminus) 177 0xB1\n\\(S2 (twosuperior) 178 0xB2\n\\(S3 (threesuperior) 179 0xB3\n\\(aa (acute) 180 0xB4\n\\(mc (mu) 181 0xB5\n\\(ps (paragraph) 182 0xB6\n\\(pc (periodcentered) 183 0xB7\n\\(ac (cedilla) 184 0xB8\n\\(S1 (onesuperior) 185 0xB9\n\\(Om (ordmasculine) 186 0xBA\n\\(Fc (guillemetright) 187 0xBB\n\\(14 (onequarter) 188 0xBC\n\\(12 (onehalf) 189 0xBD\n\\(34 (threequarters) 190 0xBE\n\\(r? (questiondown) 191 0xBF\n\\(`A (Agrave) 192 0xC0\n\\('A (Aacute) 193 0xC1\n\\(^A (Acircumflex) 194 0xC2\n\\(~A (Atilde) 195 0xC3\n\\(:A (Adiaeresis) 196 0xC4\n\\(oA (Aring) 197 0xC5\n\\(AE (AE) 198 0xC6\n\\(,C (Ccedilla) 199 0xC7\n\\(`E (Egrave) 200 0xC8\n\\('E (Eacute) 201 0xC9\n\\(^E (Ecircumflex) 202 0xCA\n\\(:E (Ediaeresis) 203 0xCB\n\\(`I (Igrave) 204 0xCC\n\\('I (Iacute) 205 0xCD\n\\(^I (Icircumflex) 206 0xCE\n\\(:I (Idiaeresis) 207 0xCF\n\\(-D (ETH) 208 0xD0\n\\(~N (Ntilde) 209 0xD1\n\\(`O (Ograve) 210 0xD2\n\\('O (Oacute) 211 0xD3\n\\(^O (Ocircumflex) 212 0xD4\n\\(~O (Otilde) 213 0xD5\n\\(:O (Odiaeresis) 214 0xD6\n\\(mu (multiply) 215 0xD7\n\\(/O (Oslash) 216 0xD8\n\\(`U (Ugrave) 217 0xD9\n\\('U (Uacute) 218 0xDA\n\\(^U (Ucircumflex) 219 0xDB\n\\(:U (Udiaeresis) 220 0xDC\n\\('Y (Yacute) 221 0xDD\n\\(TP (THORN) 222 0xDE\n\\(ss (ssharp) 223 0xDF\n\\(`a (agrave) 224 0xE0\n\\('a (aacute) 225 0xE1\n\\(^a (acircumflex) 226 0xE2\n\\(~a (atilde) 227 0xE3\n\\(:a (adiaeresis) 228 0xE4\n\\(oa (aring) 229 0xE5\n\\(ae (ae) 230 0xE6\n\\(,c (ccedilla) 231 0xE7\n\\(`e (egrave) 232 0xE8\n\\('e (eacute) 233 0xE9\n\\(^e (ecircumflex) 234 0xEA\n\\(:e (ediaeresis) 235 0xEB\n\\(`i (igrave) 236 0xEC\n\\('i (iacute) 237 0xED\n\\(^i (icircumflex) 238 0xEE\n\\(:i (idiaeresis) 239 0xEF\n\\(Sd (eth) 240 0xF0\n\\(~n (ntilde) 241 0xF1\n\\(`o (ograve) 242 0xF2\n\\('o (oacute) 243 0xF3\n\\(^o (ocircumflex) 244 0xF4\n\\(~o (otilde) 245 0xF5\n\\(:o (odiaeresis) 246 0xF6\n\\(di (division) 247 0xF7\n\\(/o (oslash) 248 0xF8\n\\(`u (ugrave) 249 0xF9\n\\('u (uacute) 250 0xFA\n\\(^u (ucircumflex) 251 0xFB\n\\(:u (udiaeresis) 252 0xFC\n\\('y (yacute) 253 0xFD\n\\(Tp (thorn) 254 0xFE\n\\(:y (ydiaeresis) 255 0xFF\n.CE\n.CS\nAogonek 417 0x1A1\nbreve 418 0x1A2\nLstroke 419 0x1A3\nLcaron 421 0x1A5\nSacute 422 0x1A6\nScaron 425 0x1A9\nScedilla 426 0x1AA\nTcaron 427 0x1AB\nZacute 428 0x1AC\nZcaron 430 0x1AE\nZabovedot 431 0x1AF\naogonek 433 0x1B1\nogonek 434 0x1B2\nlstroke 435 0x1B3\nlcaron 437 0x1B5\nsacute 438 0x1B6\ncaron 439 0x1B7\nscaron 441 0x1B9\nscedilla 442 0x1BA\ntcaron 443 0x1BB\nzacute 444 0x1BC\ndoubleacute 445 0x1BD\nzcaron 446 0x1BE\nzabovedot 447 0x1BF\nRacute 448 0x1C0\nAbreve 451 0x1C3\nLacute 453 0x1C5\nCacute 454 0x1C6\nCcaron 456 0x1C8\nEogonek 458 0x1CA\nEcaron 460 0x1CC\nDcaron 463 0x1CF\nDstroke 464 0x1D0\nNacute 465 0x1D1\nNcaron 466 0x1D2\nOdoubleacute 469 0x1D5\nRcaron 472 0x1D8\nUring 473 0x1D9\nUdoubleacute 475 0x1DB\nTcedilla 478 0x1DE\nracute 480 0x1E0\nabreve 483 0x1E3\nlacute 485 0x1E5\ncacute 486 0x1E6\nccaron 488 0x1E8\neogonek 490 0x1EA\necaron 492 0x1EC\ndcaron 495 0x1EF\ndstroke 496 0x1F0\nnacute 497 0x1F1\nncaron 498 0x1F2\nodoubleacute 501 0x1F5\nrcaron 504 0x1F8\nuring 505 0x1F9\nudoubleacute 507 0x1FB\ntcedilla 510 0x1FE\nabovedot 511 0x1FF\nHstroke 673 0x2A1\nHcircumflex 678 0x2A6\nIabovedot 681 0x2A9\nGbreve 683 0x2AB\nJcircumflex 684 0x2AC\nhstroke 689 0x2B1\nhcircumflex 694 0x2B6\nidotless 697 0x2B9\ngbreve 699 0x2BB\njcircumflex 700 0x2BC\nCabovedot 709 0x2C5\nCcircumflex 710 0x2C6\nGabovedot 725 0x2D5\nGcircumflex 728 0x2D8\nUbreve 733 0x2DD\nScircumflex 734 0x2DE\ncabovedot 741 0x2E5\nccircumflex 742 0x2E6\ngabovedot 757 0x2F5\ngcircumflex 760 0x2F8\nubreve 765 0x2FD\nscircumflex 766 0x2FE\nkra 930 0x3A2\nRcedilla 931 0x3A3\nItilde 933 0x3A5\nLcedilla 934 0x3A6\nEmacron 938 0x3AA\nGcedilla 939 0x3AB\nTslash 940 0x3AC\nrcedilla 947 0x3B3\nitilde 949 0x3B5\nlcedilla 950 0x3B6\nemacron 954 0x3BA\ngcedilla 955 0x3BB\ntslash 956 0x3BC\nENG 957 0x3BD\neng 959 0x3BF\nAmacron 960 0x3C0\nIogonek 967 0x3C7\nEabovedot 972 0x3CC\nImacron 975 0x3CF\nNcedilla 977 0x3D1\nOmacron 978 0x3D2\nKcedilla 979 0x3D3\nUogonek 985 0x3D9\nUtilde 989 0x3DD\nUmacron 990 0x3DE\namacron 992 0x3E0\niogonek 999 0x3E7\neabovedot 1004 0x3EC\nimacron 1007 0x3EF\nncedilla 1009 0x3F1\nomacron 1010 0x3F2\nkcedilla 1011 0x3F3\nuogonek 1017 0x3F9\nutilde 1021 0x3FD\numacron 1022 0x3FE\noverline 1150 0x47E\nkana_fullstop 1185 0x4A1\nkana_openingbracket 1186 0x4A2\nkana_closingbracket 1187 0x4A3\nkana_comma 1188 0x4A4\nkana_conjunctive 1189 0x4A5\nkana_WO 1190 0x4A6\nkana_a 1191 0x4A7\nkana_i 1192 0x4A8\nkana_u 1193 0x4A9\nkana_e 1194 0x4AA\nkana_o 1195 0x4AB\nkana_ya 1196 0x4AC\nkana_yu 1197 0x4AD\nkana_yo 1198 0x4AE\nkana_tsu 1199 0x4AF\nprolongedsound 1200 0x4B0\nkana_A 1201 0x4B1\nkana_I 1202 0x4B2\nkana_U 1203 0x4B3\nkana_E 1204 0x4B4\nkana_O 1205 0x4B5\nkana_KA 1206 0x4B6\nkana_KI 1207 0x4B7\nkana_KU 1208 0x4B8\nkana_KE 1209 0x4B9\nkana_KO 1210 0x4BA\nkana_SA 1211 0x4BB\nkana_SHI 1212 0x4BC\nkana_SU 1213 0x4BD\nkana_SE 1214 0x4BE\nkana_SO 1215 0x4BF\nkana_TA 1216 0x4C0\nkana_CHI 1217 0x4C1\nkana_TSU 1218 0x4C2\nkana_TE 1219 0x4C3\nkana_TO 1220 0x4C4\nkana_NA 1221 0x4C5\nkana_NI 1222 0x4C6\nkana_NU 1223 0x4C7\nkana_NE 1224 0x4C8\nkana_NO 1225 0x4C9\nkana_HA 1226 0x4CA\nkana_HI 1227 0x4CB\nkana_FU 1228 0x4CC\nkana_HE 1229 0x4CD\nkana_HO 1230 0x4CE\nkana_MA 1231 0x4CF\nkana_MI 1232 0x4D0\nkana_MU 1233 0x4D1\nkana_ME 1234 0x4D2\nkana_MO 1235 0x4D3\nkana_YA 1236 0x4D4\nkana_YU 1237 0x4D5\nkana_YO 1238 0x4D6\nkana_RA 1239 0x4D7\nkana_RI 1240 0x4D8\nkana_RU 1241 0x4D9\nkana_RE 1242 0x4DA\nkana_RO 1243 0x4DB\nkana_WA 1244 0x4DC\nkana_N 1245 0x4DD\nvoicedsound 1246 0x4DE\nsemivoicedsound 1247 0x4DF\n.CE\n.CS\nArabic_comma 1452 0x5AC\nArabic_semicolon 1467 0x5BB\nArabic_question_mark 1471 0x5BF\nArabic_hamza 1473 0x5C1\nArabic_maddaonalef 1474 0x5C2\nArabic_hamzaonalef 1475 0x5C3\nArabic_hamzaonwaw 1476 0x5C4\nArabic_hamzaunderalef 1477 0x5C5\nArabic_hamzaonyeh 1478 0x5C6\nArabic_alef 1479 0x5C7\nArabic_beh 1480 0x5C8\nArabic_tehmarbuta 1481 0x5C9\nArabic_teh 1482 0x5CA\nArabic_theh 1483 0x5CB\nArabic_jeem 1484 0x5CC\nArabic_hah 1485 0x5CD\nArabic_khah 1486 0x5CE\nArabic_dal 1487 0x5CF\nArabic_thal 1488 0x5D0\nArabic_ra 1489 0x5D1\nArabic_zain 1490 0x5D2\nArabic_seen 1491 0x5D3\nArabic_sheen 1492 0x5D4\nArabic_sad 1493 0x5D5\nArabic_dad 1494 0x5D6\nArabic_tah 1495 0x5D7\nArabic_zah 1496 0x5D8\nArabic_ain 1497 0x5D9\nArabic_ghain 1498 0x5DA\nArabic_tatweel 1504 0x5E0\nArabic_feh 1505 0x5E1\nArabic_qaf 1506 0x5E2\nArabic_kaf 1507 0x5E3\nArabic_lam 1508 0x5E4\nArabic_meem 1509 0x5E5\nArabic_noon 1510 0x5E6\nArabic_ha 1511 0x5E7\nArabic_waw 1512 0x5E8\nArabic_alefmaksura 1513 0x5E9\nArabic_yeh 1514 0x5EA\nArabic_fathatan 1515 0x5EB\nArabic_dammatan 1516 0x5EC\nArabic_kasratan 1517 0x5ED\nArabic_fatha 1518 0x5EE\nArabic_damma 1519 0x5EF\nArabic_kasra 1520 0x5F0\nArabic_shadda 1521 0x5F1\nArabic_sukun 1522 0x5F2\nSerbian_dje 1697 0x6A1\nMacedonia_gje 1698 0x6A2\nCyrillic_io 1699 0x6A3\nUkrainian_ie 1700 0x6A4\nMacedonia_dse 1701 0x6A5\nUkrainian_i 1702 0x6A6\nUkrainian_yi 1703 0x6A7\nCyrillic_je 1704 0x6A8\nCyrillic_lje 1705 0x6A9\nCyrillic_nje 1706 0x6AA\nSerbian_tshe 1707 0x6AB\nMacedonia_kje 1708 0x6AC\nUkrainian_ghe_with_upturn 1709 0x6AD\nByelorussian_shortu 1710 0x6AE\nCyrillic_dzhe 1711 0x6AF\nnumerosign 1712 0x6B0\nSerbian_DJE 1713 0x6B1\nMacedonia_GJE 1714 0x6B2\nCyrillic_IO 1715 0x6B3\nUkrainian_IE 1716 0x6B4\nMacedonia_DSE 1717 0x6B5\nUkrainian_I 1718 0x6B6\nUkrainian_YI 1719 0x6B7\nCyrillic_JE 1720 0x6B8\nCyrillic_LJE 1721 0x6B9\nCyrillic_NJE 1722 0x6BA\nSerbian_TSHE 1723 0x6BB\nMacedonia_KJE 1724 0x6BC\nUkrainian_GHE_WITH_UPTURN 1725 0x6BD\nByelorussian_SHORTU 1726 0x6BE\nCyrillic_DZHE 1727 0x6BF\nCyrillic_yu 1728 0x6C0\nCyrillic_a 1729 0x6C1\nCyrillic_be 1730 0x6C2\nCyrillic_tse 1731 0x6C3\nCyrillic_de 1732 0x6C4\nCyrillic_ie 1733 0x6C5\nCyrillic_ef 1734 0x6C6\nCyrillic_ghe 1735 0x6C7\nCyrillic_ha 1736 0x6C8\nCyrillic_i 1737 0x6C9\nCyrillic_shorti 1738 0x6CA\nCyrillic_ka 1739 0x6CB\nCyrillic_el 1740 0x6CC\nCyrillic_em 1741 0x6CD\nCyrillic_en 1742 0x6CE\nCyrillic_o 1743 0x6CF\nCyrillic_pe 1744 0x6D0\nCyrillic_ya 1745 0x6D1\nCyrillic_er 1746 0x6D2\nCyrillic_es 1747 0x6D3\nCyrillic_te 1748 0x6D4\nCyrillic_u 1749 0x6D5\nCyrillic_zhe 1750 0x6D6\nCyrillic_ve 1751 0x6D7\nCyrillic_softsign 1752 0x6D8\nCyrillic_yeru 1753 0x6D9\nCyrillic_ze 1754 0x6DA\nCyrillic_sha 1755 0x6DB\nCyrillic_e 1756 0x6DC\nCyrillic_shcha 1757 0x6DD\nCyrillic_che 1758 0x6DE\nCyrillic_hardsign 1759 0x6DF\nCyrillic_YU 1760 0x6E0\nCyrillic_A 1761 0x6E1\nCyrillic_BE 1762 0x6E2\nCyrillic_TSE 1763 0x6E3\nCyrillic_DE 1764 0x6E4\nCyrillic_IE 1765 0x6E5\nCyrillic_EF 1766 0x6E6\nCyrillic_GHE 1767 0x6E7\nCyrillic_HA 1768 0x6E8\nCyrillic_I 1769 0x6E9\nCyrillic_SHORTI 1770 0x6EA\nCyrillic_KA 1771 0x6EB\nCyrillic_EL 1772 0x6EC\nCyrillic_EM 1773 0x6ED\nCyrillic_EN 1774 0x6EE\nCyrillic_O 1775 0x6EF\nCyrillic_PE 1776 0x6F0\nCyrillic_YA 1777 0x6F1\nCyrillic_ER 1778 0x6F2\nCyrillic_ES 1779 0x6F3\nCyrillic_TE 1780 0x6F4\nCyrillic_U 1781 0x6F5\nCyrillic_ZHE 1782 0x6F6\nCyrillic_VE 1783 0x6F7\nCyrillic_SOFTSIGN 1784 0x6F8\nCyrillic_YERU 1785 0x6F9\nCyrillic_ZE 1786 0x6FA\nCyrillic_SHA 1787 0x6FB\nCyrillic_E 1788 0x6FC\nCyrillic_SHCHA 1789 0x6FD\nCyrillic_CHE 1790 0x6FE\nCyrillic_HARDSIGN 1791 0x6FF\nGreek_ALPHAaccent 1953 0x7A1\nGreek_EPSILONaccent 1954 0x7A2\nGreek_ETAaccent 1955 0x7A3\nGreek_IOTAaccent 1956 0x7A4\nGreek_IOTAdieresis 1957 0x7A5\nGreek_IOTAaccentdiaeresis 1958 0x7A6\nGreek_OMICRONaccent 1959 0x7A7\nGreek_UPSILONaccent 1960 0x7A8\nGreek_UPSILONdieresis 1961 0x7A9\nGreek_UPSILONaccentdieresis 1962 0x7AA\nGreek_OMEGAaccent 1963 0x7AB\nGreek_accentdieresis 1966 0x7AE\nGreek_horizbar 1967 0x7AF\nGreek_alphaaccent 1969 0x7B1\nGreek_epsilonaccent 1970 0x7B2\nGreek_etaaccent 1971 0x7B3\nGreek_iotaaccent 1972 0x7B4\nGreek_iotadieresis 1973 0x7B5\nGreek_iotaaccentdieresis 1974 0x7B6\nGreek_omicronaccent 1975 0x7B7\nGreek_upsilonaccent 1976 0x7B8\nGreek_upsilondieresis 1977 0x7B9\nGreek_upsilonaccentdieresis 1978 0x7BA\nGreek_omegaaccent 1979 0x7BB\nGreek_ALPHA 1985 0x7C1\nGreek_BETA 1986 0x7C2\nGreek_GAMMA 1987 0x7C3\nGreek_DELTA 1988 0x7C4\nGreek_EPSILON 1989 0x7C5\nGreek_ZETA 1990 0x7C6\nGreek_ETA 1991 0x7C7\nGreek_THETA 1992 0x7C8\nGreek_IOTA 1993 0x7C9\nGreek_KAPPA 1994 0x7CA\nGreek_LAMBDA 1995 0x7CB\nGreek_MU 1996 0x7CC\nGreek_NU 1997 0x7CD\nGreek_XI 1998 0x7CE\nGreek_OMICRON 1999 0x7CF\nGreek_PI 2000 0x7D0\nGreek_RHO 2001 0x7D1\nGreek_SIGMA 2002 0x7D2\nGreek_TAU 2004 0x7D4\nGreek_UPSILON 2005 0x7D5\nGreek_PHI 2006 0x7D6\nGreek_CHI 2007 0x7D7\nGreek_PSI 2008 0x7D8\nGreek_OMEGA 2009 0x7D9\nGreek_alpha 2017 0x7E1\nGreek_beta 2018 0x7E2\nGreek_gamma 2019 0x7E3\nGreek_delta 2020 0x7E4\nGreek_epsilon 2021 0x7E5\nGreek_zeta 2022 0x7E6\nGreek_eta 2023 0x7E7\nGreek_theta 2024 0x7E8\nGreek_iota 2025 0x7E9\nGreek_kappa 2026 0x7EA\nGreek_lambda 2027 0x7EB\nGreek_mu 2028 0x7EC\nGreek_nu 2029 0x7ED\nGreek_xi 2030 0x7EE\nGreek_omicron 2031 0x7EF\nGreek_pi 2032 0x7F0\nGreek_rho 2033 0x7F1\nGreek_sigma 2034 0x7F2\nGreek_finalsmallsigma 2035 0x7F3\nGreek_tau 2036 0x7F4\nGreek_upsilon 2037 0x7F5\nGreek_phi 2038 0x7F6\nGreek_chi 2039 0x7F7\nGreek_psi 2040 0x7F8\nGreek_omega 2041 0x7F9\n.CE\n.CS\nleftradical 2209 0x8A1\ntopleftradical 2210 0x8A2\nhorizconnector 2211 0x8A3\ntopintegral 2212 0x8A4\nbotintegral 2213 0x8A5\nvertconnector 2214 0x8A6\ntopleftsqbracket 2215 0x8A7\nbotleftsqbracket 2216 0x8A8\ntoprightsqbracket 2217 0x8A9\nbotrightsqbracket 2218 0x8AA\ntopleftparens 2219 0x8AB\nbotleftparens 2220 0x8AC\ntoprightparens 2221 0x8AD\nbotrightparens 2222 0x8AE\nleftmiddlecurlybrace 2223 0x8AF\nrightmiddlecurlybrace 2224 0x8B0\ntopleftsummation 2225 0x8B1\nbotleftsummation 2226 0x8B2\ntopvertsummationconnector 2227 0x8B3\nbotvertsummationconnector 2228 0x8B4\ntoprightsummation 2229 0x8B5\nbotrightsummation 2230 0x8B6\nrightmiddlesummation 2231 0x8B7\nlessthanequal 2236 0x8BC\nnotequal 2237 0x8BD\ngreaterthanequal 2238 0x8BE\nintegral 2239 0x8BF\ntherefore 2240 0x8C0\nvariation 2241 0x8C1\ninfinity 2242 0x8C2\nnabla 2245 0x8C5\napproximate 2248 0x8C8\nsimilarequal 2249 0x8C9\nifonlyif 2253 0x8CD\nimplies 2254 0x8CE\nidentical 2255 0x8CF\nradical 2262 0x8D6\nincludedin 2266 0x8DA\nincludes 2267 0x8DB\nintersection 2268 0x8DC\nunion 2269 0x8DD\nlogicaland 2270 0x8DE\nlogicalor 2271 0x8DF\npartialderivative 2287 0x8EF\nfunction 2294 0x8F6\nleftarrow 2299 0x8FB\nuparrow 2300 0x8FC\nrightarrow 2301 0x8FD\ndownarrow 2302 0x8FE\nblank 2527 0x9DF\nsoliddiamond 2528 0x9E0\ncheckerboard 2529 0x9E1\nht 2530 0x9E2\nff 2531 0x9E3\ncr 2532 0x9E4\nlf 2533 0x9E5\nnl 2536 0x9E8\nvt 2537 0x9E9\nlowrightcorner 2538 0x9EA\nuprightcorner 2539 0x9EB\nupleftcorner 2540 0x9EC\nlowleftcorner 2541 0x9ED\ncrossinglines 2542 0x9EE\nhorizlinescan1 2543 0x9EF\nhorizlinescan3 2544 0x9F0\nhorizlinescan5 2545 0x9F1\nhorizlinescan7 2546 0x9F2\nhorizlinescan9 2547 0x9F3\nleftt 2548 0x9F4\nrightt 2549 0x9F5\nbott 2550 0x9F6\ntopt 2551 0x9F7\nvertbar 2552 0x9F8\nemspace 2721 0xAA1\nenspace 2722 0xAA2\nem3space 2723 0xAA3\nem4space 2724 0xAA4\ndigitspace 2725 0xAA5\npunctspace 2726 0xAA6\nthinspace 2727 0xAA7\nhairspace 2728 0xAA8\nemdash 2729 0xAA9\nendash 2730 0xAAA\nsignifblank 2732 0xAAC\nellipsis 2734 0xAAE\ndoubbaselinedot 2735 0xAAF\nonethird 2736 0xAB0\ntwothirds 2737 0xAB1\nonefifth 2738 0xAB2\ntwofifths 2739 0xAB3\nthreefifths 2740 0xAB4\nfourfifths 2741 0xAB5\nonesixth 2742 0xAB6\nfivesixths 2743 0xAB7\ncareof 2744 0xAB8\nfigdash 2747 0xABB\nleftanglebracket 2748 0xABC\ndecimalpoint 2749 0xABD\nrightanglebracket 2750 0xABE\nmarker 2751 0xABF\noneeighth 2755 0xAC3\nthreeeighths 2756 0xAC4\nfiveeighths 2757 0xAC5\nseveneighths 2758 0xAC6\ntrademark 2761 0xAC9\nsignaturemark 2762 0xACA\ntrademarkincircle 2763 0xACB\nleftopentriangle 2764 0xACC\nrightopentriangle 2765 0xACD\nemopencircle 2766 0xACE\nemopenrectangle 2767 0xACF\nleftsinglequotemark 2768 0xAD0\nrightsinglequotemark 2769 0xAD1\nleftdoublequotemark 2770 0xAD2\nrightdoublequotemark 2771 0xAD3\nprescription 2772 0xAD4\npermille 2773 0xAD5\nminutes 2774 0xAD6\nseconds 2775 0xAD7\nlatincross 2777 0xAD9\nhexagram 2778 0xADA\nfilledrectbullet 2779 0xADB\nfilledlefttribullet 2780 0xADC\nfilledrighttribullet 2781 0xADD\nemfilledcircle 2782 0xADE\nemfilledrect 2783 0xADF\nenopencircbullet 2784 0xAE0\nenopensquarebullet 2785 0xAE1\nopenrectbullet 2786 0xAE2\nopentribulletup 2787 0xAE3\nopentribulletdown 2788 0xAE4\nopenstar 2789 0xAE5\nenfilledcircbullet 2790 0xAE6\nenfilledsqbullet 2791 0xAE7\nfilledtribulletup 2792 0xAE8\nfilledtribulletdown 2793 0xAE9\nleftpointer 2794 0xAEA\nrightpointer 2795 0xAEB\nclub 2796 0xAEC\ndiamond 2797 0xAED\nheart 2798 0xAEE\nmaltesecross 2800 0xAF0\ndagger 2801 0xAF1\ndoubledagger 2802 0xAF2\ncheckmark 2803 0xAF3\nballotcross 2804 0xAF4\nmusicalsharp 2805 0xAF5\nmusicalflat 2806 0xAF6\nmalesymbol 2807 0xAF7\nfemalesymbol 2808 0xAF8\ntelephone 2809 0xAF9\ntelephonerecorder 2810 0xAFA\nphonographcopyright 2811 0xAFB\ncaret 2812 0xAFC\nsinglelowquotemark 2813 0xAFD\ndoublelowquotemark 2814 0xAFE\ncursor 2815 0xAFF\nleftcaret 2979 0xBA3\nrightcaret 2982 0xBA6\ndowncaret 2984 0xBA8\nupcaret 2985 0xBA9\noverbar 3008 0xBC0\ndowntack 3010 0xBC2\nupshoe 3011 0xBC3\ndownstile 3012 0xBC4\nunderbar 3014 0xBC6\njot 3018 0xBCA\nquad 3020 0xBCC\nuptack 3022 0xBCE\ncircle 3023 0xBCF\nupstile 3027 0xBD3\ndownshoe 3030 0xBD6\nrightshoe 3032 0xBD8\nleftshoe 3034 0xBDA\nlefttack 3036 0xBDC\nrighttack 3068 0xBFC\nhebrew_doublelowline 3295 0xCDF\nhebrew_aleph 3296 0xCE0\nhebrew_bet 3297 0xCE1\nhebrew_gimel 3298 0xCE2\nhebrew_dalet 3299 0xCE3\nhebrew_he 3300 0xCE4\nhebrew_waw 3301 0xCE5\nhebrew_zain 3302 0xCE6\nhebrew_chet 3303 0xCE7\nhebrew_tet 3304 0xCE8\nhebrew_yod 3305 0xCE9\nhebrew_finalkaph 3306 0xCEA\nhebrew_kaph 3307 0xCEB\nhebrew_lamed 3308 0xCEC\nhebrew_finalmem 3309 0xCED\nhebrew_mem 3310 0xCEE\nhebrew_finalnun 3311 0xCEF\nhebrew_nun 3312 0xCF0\nhebrew_samech 3313 0xCF1\nhebrew_ayin 3314 0xCF2\nhebrew_finalpe 3315 0xCF3\nhebrew_pe 3316 0xCF4\nhebrew_finalzade 3317 0xCF5\nhebrew_zade 3318 0xCF6\nhebrew_qoph 3319 0xCF7\nhebrew_resh 3320 0xCF8\nhebrew_shin 3321 0xCF9\nhebrew_taw 3322 0xCFA\n.CE\n.CS\nThai_kokai 3489 0xDA1\nThai_khokhai 3490 0xDA2\nThai_khokhuat 3491 0xDA3\nThai_khokhwai 3492 0xDA4\nThai_khokhon 3493 0xDA5\nThai_khorakhang 3494 0xDA6\nThai_ngongu 3495 0xDA7\nThai_chochan 3496 0xDA8\nThai_choching 3497 0xDA9\nThai_chochang 3498 0xDAA\nThai_soso 3499 0xDAB\nThai_chochoe 3500 0xDAC\nThai_yoying 3501 0xDAD\nThai_dochada 3502 0xDAE\nThai_topatak 3503 0xDAF\nThai_thothan 3504 0xDB0\nThai_thonangmontho 3505 0xDB1\nThai_thophuthao 3506 0xDB2\nThai_nonen 3507 0xDB3\nThai_dodek 3508 0xDB4\nThai_totao 3509 0xDB5\nThai_thothung 3510 0xDB6\nThai_thothahan 3511 0xDB7\nThai_thothong 3512 0xDB8\nThai_nonu 3513 0xDB9\nThai_bobaimai 3514 0xDBA\nThai_popla 3515 0xDBB\nThai_phophung 3516 0xDBC\nThai_fofa 3517 0xDBD\nThai_phophan 3518 0xDBE\nThai_fofan 3519 0xDBF\nThai_phosamphao 3520 0xDC0\nThai_moma 3521 0xDC1\nThai_yoyak 3522 0xDC2\nThai_rorua 3523 0xDC3\nThai_ru 3524 0xDC4\nThai_loling 3525 0xDC5\nThai_lu 3526 0xDC6\nThai_wowaen 3527 0xDC7\nThai_sosala 3528 0xDC8\nThai_sorusi 3529 0xDC9\nThai_sosua 3530 0xDCA\nThai_hohip 3531 0xDCB\nThai_lochula 3532 0xDCC\nThai_oang 3533 0xDCD\nThai_honokhuk 3534 0xDCE\nThai_paiyannoi 3535 0xDCF\nThai_saraa 3536 0xDD0\nThai_maihanakat 3537 0xDD1\nThai_saraaa 3538 0xDD2\nThai_saraam 3539 0xDD3\nThai_sarai 3540 0xDD4\nThai_saraii 3541 0xDD5\nThai_saraue 3542 0xDD6\nThai_sarauee 3543 0xDD7\nThai_sarau 3544 0xDD8\nThai_sarauu 3545 0xDD9\nThai_phinthu 3546 0xDDA\nThai_maihanakat_maitho 3550 0xDDE\nThai_baht 3551 0xDDF\nThai_sarae 3552 0xDE0\nThai_saraae 3553 0xDE1\nThai_sarao 3554 0xDE2\nThai_saraaimaimuan 3555 0xDE3\nThai_saraaimaimalai 3556 0xDE4\nThai_lakkhangyao 3557 0xDE5\nThai_maiyamok 3558 0xDE6\nThai_maitaikhu 3559 0xDE7\nThai_maiek 3560 0xDE8\nThai_maitho 3561 0xDE9\nThai_maitri 3562 0xDEA\nThai_maichattawa 3563 0xDEB\nThai_thanthakhat 3564 0xDEC\nThai_nikhahit 3565 0xDED\nThai_leksun 3568 0xDF0\nThai_leknung 3569 0xDF1\nThai_leksong 3570 0xDF2\nThai_leksam 3571 0xDF3\nThai_leksi 3572 0xDF4\nThai_lekha 3573 0xDF5\nThai_lekhok 3574 0xDF6\nThai_lekchet 3575 0xDF7\nThai_lekpaet 3576 0xDF8\nThai_lekkao 3577 0xDF9\nHangul_Kiyeog 3745 0xEA1\nHangul_SsangKiyeog 3746 0xEA2\nHangul_KiyeogSios 3747 0xEA3\nHangul_Nieun 3748 0xEA4\nHangul_NieunJieuj 3749 0xEA5\nHangul_NieunHieuh 3750 0xEA6\nHangul_Dikeud 3751 0xEA7\nHangul_SsangDikeud 3752 0xEA8\nHangul_Rieul 3753 0xEA9\nHangul_RieulKiyeog 3754 0xEAA\nHangul_RieulMieum 3755 0xEAB\nHangul_RieulPieub 3756 0xEAC\nHangul_RieulSios 3757 0xEAD\nHangul_RieulTieut 3758 0xEAE\nHangul_RieulPhieuf 3759 0xEAF\nHangul_RieulHieuh 3760 0xEB0\nHangul_Mieum 3761 0xEB1\nHangul_Pieub 3762 0xEB2\nHangul_SsangPieub 3763 0xEB3\nHangul_PieubSios 3764 0xEB4\nHangul_Sios 3765 0xEB5\nHangul_SsangSios 3766 0xEB6\nHangul_Ieung 3767 0xEB7\nHangul_Jieuj 3768 0xEB8\nHangul_SsangJieuj 3769 0xEB9\nHangul_Cieuc 3770 0xEBA\nHangul_Khieuq 3771 0xEBB\nHangul_Tieut 3772 0xEBC\nHangul_Phieuf 3773 0xEBD\nHangul_Hieuh 3774 0xEBE\nHangul_A 3775 0xEBF\nHangul_AE 3776 0xEC0\nHangul_YA 3777 0xEC1\nHangul_YAE 3778 0xEC2\nHangul_EO 3779 0xEC3\nHangul_E 3780 0xEC4\nHangul_YEO 3781 0xEC5\nHangul_YE 3782 0xEC6\nHangul_O 3783 0xEC7\nHangul_WA 3784 0xEC8\nHangul_WAE 3785 0xEC9\nHangul_OE 3786 0xECA\nHangul_YO 3787 0xECB\nHangul_U 3788 0xECC\nHangul_WEO 3789 0xECD\nHangul_WE 3790 0xECE\nHangul_WI 3791 0xECF\nHangul_YU 3792 0xED0\nHangul_EU 3793 0xED1\nHangul_YI 3794 0xED2\nHangul_I 3795 0xED3\nHangul_J_Kiyeog 3796 0xED4\nHangul_J_SsangKiyeog 3797 0xED5\nHangul_J_KiyeogSios 3798 0xED6\nHangul_J_Nieun 3799 0xED7\nHangul_J_NieunJieuj 3800 0xED8\nHangul_J_NieunHieuh 3801 0xED9\nHangul_J_Dikeud 3802 0xEDA\nHangul_J_Rieul 3803 0xEDB\nHangul_J_RieulKiyeog 3804 0xEDC\nHangul_J_RieulMieum 3805 0xEDD\nHangul_J_RieulPieub 3806 0xEDE\nHangul_J_RieulSios 3807 0xEDF\nHangul_J_RieulTieut 3808 0xEE0\nHangul_J_RieulPhieuf 3809 0xEE1\nHangul_J_RieulHieuh 3810 0xEE2\nHangul_J_Mieum 3811 0xEE3\nHangul_J_Pieub 3812 0xEE4\nHangul_J_PieubSios 3813 0xEE5\nHangul_J_Sios 3814 0xEE6\nHangul_J_SsangSios 3815 0xEE7\nHangul_J_Ieung 3816 0xEE8\nHangul_J_Jieuj 3817 0xEE9\nHangul_J_Cieuc 3818 0xEEA\nHangul_J_Khieuq 3819 0xEEB\nHangul_J_Tieut 3820 0xEEC\nHangul_J_Phieuf 3821 0xEED\nHangul_J_Hieuh 3822 0xEEE\nHangul_RieulYeorinHieuh 3823 0xEEF\nHangul_SunkyeongeumMieum 3824 0xEF0\nHangul_SunkyeongeumPieub 3825 0xEF1\nHangul_PanSios 3826 0xEF2\nHangul_KkogjiDalrinIeung 3827 0xEF3\nHangul_SunkyeongeumPhieuf 3828 0xEF4\nHangul_YeorinHieuh 3829 0xEF5\nHangul_AraeA 3830 0xEF6\nHangul_AraeAE 3831 0xEF7\nHangul_J_PanSios 3832 0xEF8\nHangul_J_KkogjiDalrinIeung 3833 0xEF9\nHangul_J_YeorinHieuh 3834 0xEFA\nKorean_Won 3839 0xEFF\nOE 5052 0x13BC\noe 5053 0x13BD\nYdiaeresis 5054 0x13BE\n\\(eu (EuroSign) 8364 0x20AC\n.CE\n.CS\nISO_Lock 65025 0xFE01\nISO_Level2_Latch 65026 0xFE02\nISO_Level3_Shift 65027 0xFE03\nISO_Level3_Latch 65028 0xFE04\nISO_Level3_Lock 65029 0xFE05\nISO_Group_Latch 65030 0xFE06\nISO_Group_Lock 65031 0xFE07\nISO_Next_Group 65032 0xFE08\nISO_Next_Group_Lock 65033 0xFE09\nISO_Prev_Group 65034 0xFE0A\nISO_Prev_Group_Lock 65035 0xFE0B\nISO_First_Group 65036 0xFE0C\nISO_First_Group_Lock 65037 0xFE0D\nISO_Last_Group 65038 0xFE0E\nISO_Last_Group_Lock 65039 0xFE0F\nISO_Level5_Shift 65041 0xFE11\nISO_Level5_Latch 65042 0xFE12\nISO_Level5_Lock 65043 0xFE13\nISO_Left_Tab 65056 0xFE20\nISO_Move_Line_Up 65057 0xFE21\nISO_Move_Line_Down 65058 0xFE22\nISO_Partial_Line_Up 65059 0xFE23\nISO_Partial_Line_Down 65060 0xFE24\nISO_Partial_Space_Left 65061 0xFE25\nISO_Partial_Space_Right 65062 0xFE26\nISO_Set_Margin_Left 65063 0xFE27\nISO_Set_Margin_Right 65064 0xFE28\nISO_Release_Margin_Left 65065 0xFE29\nISO_Release_Margin_Right 65066 0xFE2A\nISO_Release_Both_Margins 65067 0xFE2B\nISO_Fast_Cursor_Left 65068 0xFE2C\nISO_Fast_Cursor_Right 65069 0xFE2D\nISO_Fast_Cursor_Up 65070 0xFE2E\nISO_Fast_Cursor_Down 65071 0xFE2F\nISO_Continuous_Underline 65072 0xFE30\nISO_Discontinuous_Underline 65073 0xFE31\nISO_Emphasize 65074 0xFE32\nISO_Center_Object 65075 0xFE33\nISO_Enter 65076 0xFE34\ndead_grave 65104 0xFE50\ndead_acute 65105 0xFE51\ndead_circumflex 65106 0xFE52\ndead_tilde 65107 0xFE53\ndead_macron 65108 0xFE54\ndead_breve 65109 0xFE55\ndead_abovedot 65110 0xFE56\ndead_diaeresis 65111 0xFE57\ndead_abovering 65112 0xFE58\ndead_doubleacute 65113 0xFE59\ndead_caron 65114 0xFE5A\ndead_cedilla 65115 0xFE5B\ndead_ogonek 65116 0xFE5C\ndead_iota 65117 0xFE5D\ndead_voiced_sound 65118 0xFE5E\ndead_semivoiced_sound 65119 0xFE5F\ndead_belowdot 65120 0xFE60\ndead_hook 65121 0xFE61\ndead_horn 65122 0xFE62\ndead_stroke 65123 0xFE63\ndead_abovecomma 65124 0xFE64\ndead_abovereversedcomma 65125 0xFE65\ndead_doublegrave 65126 0xFE66\ndead_belowring 65127 0xFE67\ndead_belowmacron 65128 0xFE68\ndead_belowcircumflex 65129 0xFE69\ndead_belowtilde 65130 0xFE6A\ndead_belowbreve 65131 0xFE6B\ndead_belowdiaeresis 65132 0xFE6C\ndead_invertedbreve 65133 0xFE6D\ndead_belowcomma 65134 0xFE6E\ndead_currency 65135 0xFE6F\nAccessX_Enable 65136 0xFE70\nAccessX_Feedback_Enable 65137 0xFE71\nRepeatKeys_Enable 65138 0xFE72\nSlowKeys_Enable 65139 0xFE73\nBounceKeys_Enable 65140 0xFE74\nStickyKeys_Enable 65141 0xFE75\nMouseKeys_Enable 65142 0xFE76\nMouseKeys_Accel_Enable 65143 0xFE77\nOverlay1_Enable 65144 0xFE78\nOverlay2_Enable 65145 0xFE79\nAudibleBell_Enable 65146 0xFE7A\ndead_a 65152 0xFE80\ndead_A 65153 0xFE81\ndead_e 65154 0xFE82\ndead_E 65155 0xFE83\ndead_i 65156 0xFE84\ndead_I 65157 0xFE85\ndead_o 65158 0xFE86\ndead_O 65159 0xFE87\ndead_u 65160 0xFE88\ndead_U 65161 0xFE89\ndead_schwa 65162 0xFE8A\ndead_SCHWA 65163 0xFE8B\ndead_greek 65164 0xFE8C\ndead_hamza 65165 0xFE8D\ndead_lowline 65168 0xFE90\ndead_aboveverticalline 65169 0xFE91\ndead_belowverticalline 65170 0xFE92\ndead_longsolidusoverlay 65171 0xFE93\nch 65184 0xFEA0\nCh 65185 0xFEA1\nCH 65186 0xFEA2\nc_h 65187 0xFEA3\nC_h 65188 0xFEA4\nC_H 65189 0xFEA5\nFirst_Virtual_Screen 65232 0xFED0\nPrev_Virtual_Screen 65233 0xFED1\nNext_Virtual_Screen 65234 0xFED2\nLast_Virtual_Screen 65236 0xFED4\nTerminate_Server 65237 0xFED5\nPointer_Left 65248 0xFEE0\nPointer_Right 65249 0xFEE1\nPointer_Up 65250 0xFEE2\nPointer_Down 65251 0xFEE3\nPointer_UpLeft 65252 0xFEE4\nPointer_UpRight 65253 0xFEE5\nPointer_DownLeft 65254 0xFEE6\nPointer_DownRight 65255 0xFEE7\nPointer_Button_Dflt 65256 0xFEE8\nPointer_Button1 65257 0xFEE9\nPointer_Button2 65258 0xFEEA\nPointer_Button3 65259 0xFEEB\nPointer_Button4 65260 0xFEEC\nPointer_Button5 65261 0xFEED\nPointer_DblClick_Dflt 65262 0xFEEE\nPointer_DblClick1 65263 0xFEEF\nPointer_DblClick2 65264 0xFEF0\nPointer_DblClick3 65265 0xFEF1\nPointer_DblClick4 65266 0xFEF2\nPointer_DblClick5 65267 0xFEF3\nPointer_Drag_Dflt 65268 0xFEF4\nPointer_Drag1 65269 0xFEF5\nPointer_Drag2 65270 0xFEF6\nPointer_Drag3 65271 0xFEF7\nPointer_Drag4 65272 0xFEF8\nPointer_EnableKeys 65273 0xFEF9\nPointer_Accelerate 65274 0xFEFA\nPointer_DfltBtnNext 65275 0xFEFB\nPointer_DfltBtnPrev 65276 0xFEFC\nPointer_Drag5 65277 0xFEFD\n.CE\n.CS\nBackSpace 65288 0xFF08\nTab 65289 0xFF09\nLinefeed 65290 0xFF0A\nClear 65291 0xFF0B\nReturn 65293 0xFF0D\nPause 65299 0xFF13\nScroll_Lock 65300 0xFF14\nSys_Req 65301 0xFF15\nEscape 65307 0xFF1B\nMulti_key 65312 0xFF20\nKanji 65313 0xFF21\nMuhenkan 65314 0xFF22\nHenkan 65315 0xFF23\nRomaji 65316 0xFF24\nHiragana 65317 0xFF25\nKatakana 65318 0xFF26\nHiragana_Katakana 65319 0xFF27\nZenkaku 65320 0xFF28\nHankaku 65321 0xFF29\nZenkaku_Hankaku 65322 0xFF2A\nTouroku 65323 0xFF2B\nMassyo 65324 0xFF2C\nKana_Lock 65325 0xFF2D\nKana_Shift 65326 0xFF2E\nEisu_Shift 65327 0xFF2F\nEisu_toggle 65328 0xFF30\nHangul 65329 0xFF31\nHangul_Start 65330 0xFF32\nHangul_End 65331 0xFF33\nHangul_Hanja 65332 0xFF34\nHangul_Jamo 65333 0xFF35\nHangul_Romaja 65334 0xFF36\nCodeinput 65335 0xFF37\nHangul_Jeonja 65336 0xFF38\nHangul_Banja 65337 0xFF39\nHangul_PreHanja 65338 0xFF3A\nHangul_PostHanja 65339 0xFF3B\nSingleCandidate 65340 0xFF3C\nMultipleCandidate 65341 0xFF3D\nPreviousCandidate 65342 0xFF3E\nHangul_Special 65343 0xFF3F\nHome 65360 0xFF50\nLeft 65361 0xFF51\nUp 65362 0xFF52\nRight 65363 0xFF53\nDown 65364 0xFF54\nPrior 65365 0xFF55\nNext 65366 0xFF56\nEnd 65367 0xFF57\nBegin 65368 0xFF58\nSelect 65376 0xFF60\nPrint 65377 0xFF61\nExecute 65378 0xFF62\nInsert 65379 0xFF63\nUndo 65381 0xFF65\nRedo 65382 0xFF66\nMenu (App) 65383 0xFF67\nFind 65384 0xFF68\nCancel 65385 0xFF69\nHelp 65386 0xFF6A\nBreak 65387 0xFF6B\nMode_switch 65406 0xFF7E\nNum_Lock 65407 0xFF7F\nKP_Space 65408 0xFF80\nKP_Tab 65417 0xFF89\nKP_Enter 65421 0xFF8D\nKP_F1 65425 0xFF91\nKP_F2 65426 0xFF92\nKP_F3 65427 0xFF93\nKP_F4 65428 0xFF94\nKP_Home 65429 0xFF95\nKP_Left 65430 0xFF96\nKP_Up 65431 0xFF97\nKP_Right 65432 0xFF98\nKP_Down 65433 0xFF99\nKP_Prior 65434 0xFF9A\nKP_Next 65435 0xFF9B\nKP_End 65436 0xFF9C\nKP_Begin 65437 0xFF9D\nKP_Insert 65438 0xFF9E\nKP_Delete 65439 0xFF9F\nKP_Multiply 65450 0xFFAA\nKP_Add 65451 0xFFAB\nKP_Separator 65452 0xFFAC\nKP_Subtract 65453 0xFFAD\nKP_Decimal 65454 0xFFAE\nKP_Divide 65455 0xFFAF\nKP_0 65456 0xFFB0\nKP_1 65457 0xFFB1\nKP_2 65458 0xFFB2\nKP_3 65459 0xFFB3\nKP_4 65460 0xFFB4\nKP_5 65461 0xFFB5\nKP_6 65462 0xFFB6\nKP_7 65463 0xFFB7\nKP_8 65464 0xFFB8\nKP_9 65465 0xFFB9\nKP_Equal 65469 0xFFBD\nF1 65470 0xFFBE\nF2 65471 0xFFBF\nF3 65472 0xFFC0\nF4 65473 0xFFC1\nF5 65474 0xFFC2\nF6 65475 0xFFC3\nF7 65476 0xFFC4\nF8 65477 0xFFC5\nF9 65478 0xFFC6\nF10 65479 0xFFC7\nF11 65480 0xFFC8\nF12 65481 0xFFC9\nF13 65482 0xFFCA\nF14 65483 0xFFCB\nF15 65484 0xFFCC\nF16 65485 0xFFCD\nF17 65486 0xFFCE\nF18 65487 0xFFCF\nF19 65488 0xFFD0\nF20 65489 0xFFD1\nF21 65490 0xFFD2\nF22 65491 0xFFD3\nF23 65492 0xFFD4\nF24 65493 0xFFD5\nF25 65494 0xFFD6\nF26 65495 0xFFD7\nF27 65496 0xFFD8\nF28 65497 0xFFD9\nF29 65498 0xFFDA\nF30 65499 0xFFDB\nF31 65500 0xFFDC\nF32 65501 0xFFDD\nF33 65502 0xFFDE\nF34 65503 0xFFDF\nF35 65504 0xFFE0\nShift_L 65505 0xFFE1\nShift_R 65506 0xFFE2\nControl_L 65507 0xFFE3\nControl_R 65508 0xFFE4\nCaps_Lock 65509 0xFFE5\nShift_Lock 65510 0xFFE6\nMeta_L 65511 0xFFE7\nMeta_R 65512 0xFFE8\nAlt_L 65513 0xFFE9\nAlt_R 65514 0xFFEA\nSuper_L (Win_L) 65515 0xFFEB\nSuper_R (Win_R) 65516 0xFFEC\nHyper_L 65517 0xFFED\nHyper_R 65518 0xFFEE\nbraille_dot_1 65521 0xFFF1\nbraille_dot_2 65522 0xFFF2\nbraille_dot_3 65523 0xFFF3\nbraille_dot_4 65524 0xFFF4\nbraille_dot_5 65525 0xFFF5\nbraille_dot_6 65526 0xFFF6\nbraille_dot_7 65527 0xFFF7\nbraille_dot_8 65528 0xFFF8\nbraille_dot_9 65529 0xFFF9\nbraille_dot_10 65530 0xFFFA\nDelete 65535 0xFFFF\n.CE\n.CS\nSunFA_Grave 268828416 0x1005FF00\nSunFA_Circum 268828417 0x1005FF01\nSunFA_Tilde 268828418 0x1005FF02\nSunFA_Acute 268828419 0x1005FF03\nSunFA_Diaeresis 268828420 0x1005FF04\nSunFA_Cedilla 268828421 0x1005FF05\nSunF36 268828432 0x1005FF10\nSunF37 268828433 0x1005FF11\nSunSys_Req 268828512 0x1005FF60\nSunProps 268828528 0x1005FF70\nSunFront 268828529 0x1005FF71\nSunCopy 268828530 0x1005FF72\nSunOpen 268828531 0x1005FF73\nSunPaste 268828532 0x1005FF74\nSunCut 268828533 0x1005FF75\nSunPowerSwitch 268828534 0x1005FF76\nSunAudioLowerVolume 268828535 0x1005FF77\nSunAudioMute 268828536 0x1005FF78\nSunAudioRaiseVolume 268828537 0x1005FF79\nSunVideoDegauss 268828538 0x1005FF7A\nSunVideoLowerBrightness 268828539 0x1005FF7B\nSunVideoRaiseBrightness 268828540 0x1005FF7C\nSunPowerSwitchShift 268828541 0x1005FF7D\nXF86BrightnessAuto 268964084 0x100810F4\nXF86DisplayOff 268964085 0x100810F5\nXF86Info 268964198 0x10081166\nXF86AspectRatio 268964215 0x10081177\nXF86DVD 268964229 0x10081185\nXF86Audio 268964232 0x10081188\nXF86ChannelUp 268964242 0x10081192\nXF86ChannelDown 268964243 0x10081193\nXF86Break 268964251 0x1008119B\nXF86VideoPhone 268964256 0x100811A0\nXF86ZoomReset 268964260 0x100811A4\nXF86Editor 268964262 0x100811A6\nXF86GraphicsEditor 268964264 0x100811A8\nXF86Presentation 268964265 0x100811A9\nXF86Database 268964266 0x100811AA\nXF86Voicemail 268964268 0x100811AC\nXF86Addressbook 268964269 0x100811AD\nXF86DisplayToggle 268964271 0x100811AF\nXF86SpellCheck 268964272 0x100811B0\nXF86ContextMenu 268964278 0x100811B6\nXF86MediaRepeat 268964279 0x100811B7\nXF8610ChannelsUp 268964280 0x100811B8\nXF8610ChannelsDown 268964281 0x100811B9\nXF86Images 268964282 0x100811BA\nXF86NotificationCenter 268964284 0x100811BC\nXF86PickupPhone 268964285 0x100811BD\nXF86HangupPhone 268964286 0x100811BE\nXF86Fn 268964304 0x100811D0\nXF86Fn_Esc 268964305 0x100811D1\nXF86FnRightShift 268964325 0x100811E5\nXF86Numeric0 268964352 0x10081200\nXF86Numeric1 268964353 0x10081201\nXF86Numeric2 268964354 0x10081202\nXF86Numeric3 268964355 0x10081203\nXF86Numeric4 268964356 0x10081204\nXF86Numeric5 268964357 0x10081205\nXF86Numeric6 268964358 0x10081206\nXF86Numeric7 268964359 0x10081207\nXF86Numeric8 268964360 0x10081208\nXF86Numeric9 268964361 0x10081209\nXF86NumericStar 268964362 0x1008120A\nXF86NumericPound 268964363 0x1008120B\nXF86NumericA 268964364 0x1008120C\nXF86NumericB 268964365 0x1008120D\nXF86NumericC 268964366 0x1008120E\nXF86NumericD 268964367 0x1008120F\nXF86CameraFocus 268964368 0x10081210\nXF86WPSButton 268964369 0x10081211\nXF86CameraZoomIn 268964373 0x10081215\nXF86CameraZoomOut 268964374 0x10081216\nXF86CameraUp 268964375 0x10081217\nXF86CameraDown 268964376 0x10081218\nXF86CameraLeft 268964377 0x10081219\nXF86CameraRight 268964378 0x1008121A\nXF86AttendantOn 268964379 0x1008121B\nXF86AttendantOff 268964380 0x1008121C\nXF86AttendantToggle 268964381 0x1008121D\nXF86LightsToggle 268964382 0x1008121E\nXF86ALSToggle 268964400 0x10081230\nXF86Buttonconfig 268964416 0x10081240\nXF86Taskmanager 268964417 0x10081241\nXF86Journal 268964418 0x10081242\nXF86ControlPanel 268964419 0x10081243\nXF86AppSelect 268964420 0x10081244\nXF86Screensaver 268964421 0x10081245\nXF86VoiceCommand 268964422 0x10081246\nXF86Assistant 268964423 0x10081247\nXF86EmojiPicker 268964425 0x10081249\nXF86Dictate 268964426 0x1008124A\nXF86BrightnessMin 268964432 0x10081250\nXF86BrightnessMax 268964433 0x10081251\nXF86KbdInputAssistPrev 268964448 0x10081260\nXF86KbdInputAssistNext 268964449 0x10081261\nXF86KbdInputAssistPrevgroup 268964450 0x10081262\nXF86KbdInputAssistNextgroup 268964451 0x10081263\nXF86KbdInputAssistAccept 268964452 0x10081264\nXF86KbdInputAssistCancel 268964453 0x10081265\nXF86RightUp 268964454 0x10081266\nXF86RightDown 268964455 0x10081267\nXF86LeftUp 268964456 0x10081268\nXF86LeftDown 268964457 0x10081269\nXF86RootMenu 268964458 0x1008126A\nXF86MediaTopMenu 268964459 0x1008126B\nXF86Numeric11 268964460 0x1008126C\nXF86Numeric12 268964461 0x1008126D\nXF86AudioDesc 268964462 0x1008126E\nXF863DMode 268964463 0x1008126F\nXF86NextFavorite 268964464 0x10081270\nXF86StopRecord 268964465 0x10081271\nXF86PauseRecord 268964466 0x10081272\nXF86VOD 268964467 0x10081273\nXF86Unmute 268964468 0x10081274\nXF86FastReverse 268964469 0x10081275\nXF86SlowReverse 268964470 0x10081276\nXF86Data 268964471 0x10081277\nXF86OnScreenKeyboard 268964472 0x10081278\nXF86PrivacyScreenToggle 268964473 0x10081279\nXF86SelectiveScreenshot 268964474 0x1008127A\nXF86Macro1 268964496 0x10081290\nXF86Macro2 268964497 0x10081291\nXF86Macro3 268964498 0x10081292\nXF86Macro4 268964499 0x10081293\nXF86Macro5 268964500 0x10081294\nXF86Macro6 268964501 0x10081295\nXF86Macro7 268964502 0x10081296\nXF86Macro8 268964503 0x10081297\nXF86Macro9 268964504 0x10081298\nXF86Macro10 268964505 0x10081299\nXF86Macro11 268964506 0x1008129A\nXF86Macro12 268964507 0x1008129B\nXF86Macro13 268964508 0x1008129C\nXF86Macro14 268964509 0x1008129D\nXF86Macro15 268964510 0x1008129E\nXF86Macro16 268964511 0x1008129F\nXF86Macro17 268964512 0x100812A0\nXF86Macro18 268964513 0x100812A1\nXF86Macro19 268964514 0x100812A2\nXF86Macro20 268964515 0x100812A3\nXF86Macro21 268964516 0x100812A4\nXF86Macro22 268964517 0x100812A5\nXF86Macro23 268964518 0x100812A6\nXF86Macro24 268964519 0x100812A7\nXF86Macro25 268964520 0x100812A8\nXF86Macro26 268964521 0x100812A9\nXF86Macro27 268964522 0x100812AA\nXF86Macro28 268964523 0x100812AB\nXF86Macro29 268964524 0x100812AC\nXF86Macro30 268964525 0x100812AD\nXF86MacroRecordStart 268964528 0x100812B0\nXF86MacroRecordStop 268964529 0x100812B1\nXF86MacroPresetCycle 268964530 0x100812B2\nXF86MacroPreset1 268964531 0x100812B3\nXF86MacroPreset2 268964532 0x100812B4\nXF86MacroPreset3 268964533 0x100812B5\nXF86KbdLcdMenu1 268964536 0x100812B8\nXF86KbdLcdMenu2 268964537 0x100812B9\nXF86KbdLcdMenu3 268964538 0x100812BA\nXF86KbdLcdMenu4 268964539 0x100812BB\nXF86KbdLcdMenu5 268964540 0x100812BC\nXF86Switch_VT_1 269024769 0x1008FE01\nXF86Switch_VT_2 269024770 0x1008FE02\nXF86Switch_VT_3 269024771 0x1008FE03\nXF86Switch_VT_4 269024772 0x1008FE04\nXF86Switch_VT_5 269024773 0x1008FE05\nXF86Switch_VT_6 269024774 0x1008FE06\nXF86Switch_VT_7 269024775 0x1008FE07\nXF86Switch_VT_8 269024776 0x1008FE08\nXF86Switch_VT_9 269024777 0x1008FE09\nXF86Switch_VT_10 269024778 0x1008FE0A\nXF86Switch_VT_11 269024779 0x1008FE0B\nXF86Switch_VT_12 269024780 0x1008FE0C\n.CE\n.CS\nXF86Ungrab 269024800 0x1008FE20\nXF86ClearGrab 269024801 0x1008FE21\nXF86Next_VMode 269024802 0x1008FE22\nXF86Prev_VMode 269024803 0x1008FE23\nXF86LogWindowTree 269024804 0x1008FE24\nXF86LogGrabInfo 269024805 0x1008FE25\nXF86ModeLock 269025025 0x1008FF01\nXF86MonBrightnessUp 269025026 0x1008FF02\nXF86MonBrightnessDown 269025027 0x1008FF03\nXF86KbdLightOnOff 269025028 0x1008FF04\nXF86KbdBrightnessUp 269025029 0x1008FF05\nXF86KbdBrightnessDown 269025030 0x1008FF06\nXF86MonBrightnessCycle 269025031 0x1008FF07\nXF86Standby 269025040 0x1008FF10\nXF86AudioLowerVolume 269025041 0x1008FF11\nXF86AudioMute 269025042 0x1008FF12\nXF86AudioRaiseVolume 269025043 0x1008FF13\nXF86AudioPlay 269025044 0x1008FF14\nXF86AudioStop 269025045 0x1008FF15\nXF86AudioPrev 269025046 0x1008FF16\nXF86AudioNext 269025047 0x1008FF17\nXF86HomePage 269025048 0x1008FF18\nXF86Mail 269025049 0x1008FF19\nXF86Start 269025050 0x1008FF1A\nXF86Search 269025051 0x1008FF1B\nXF86AudioRecord 269025052 0x1008FF1C\nXF86Calculator 269025053 0x1008FF1D\nXF86Memo 269025054 0x1008FF1E\nXF86ToDoList 269025055 0x1008FF1F\nXF86Calendar 269025056 0x1008FF20\nXF86PowerDown 269025057 0x1008FF21\nXF86ContrastAdjust 269025058 0x1008FF22\nXF86RockerUp 269025059 0x1008FF23\nXF86RockerDown 269025060 0x1008FF24\nXF86RockerEnter 269025061 0x1008FF25\nXF86Back 269025062 0x1008FF26\nXF86Forward 269025063 0x1008FF27\nXF86Stop 269025064 0x1008FF28\nXF86Refresh 269025065 0x1008FF29\nXF86PowerOff 269025066 0x1008FF2A\nXF86WakeUp 269025067 0x1008FF2B\nXF86Eject 269025068 0x1008FF2C\nXF86ScreenSaver 269025069 0x1008FF2D\nXF86WWW 269025070 0x1008FF2E\nXF86Sleep 269025071 0x1008FF2F\nXF86Favorites 269025072 0x1008FF30\nXF86AudioPause 269025073 0x1008FF31\nXF86AudioMedia 269025074 0x1008FF32\nXF86MyComputer 269025075 0x1008FF33\nXF86VendorHome 269025076 0x1008FF34\nXF86LightBulb 269025077 0x1008FF35\nXF86Shop 269025078 0x1008FF36\nXF86History 269025079 0x1008FF37\nXF86OpenURL 269025080 0x1008FF38\nXF86AddFavorite 269025081 0x1008FF39\nXF86HotLinks 269025082 0x1008FF3A\nXF86BrightnessAdjust 269025083 0x1008FF3B\nXF86Finance 269025084 0x1008FF3C\nXF86Community 269025085 0x1008FF3D\nXF86AudioRewind 269025086 0x1008FF3E\nXF86BackForward 269025087 0x1008FF3F\nXF86Launch0 269025088 0x1008FF40\nXF86Launch1 269025089 0x1008FF41\nXF86Launch2 269025090 0x1008FF42\nXF86Launch3 269025091 0x1008FF43\nXF86Launch4 269025092 0x1008FF44\nXF86Launch5 269025093 0x1008FF45\nXF86Launch6 269025094 0x1008FF46\nXF86Launch7 269025095 0x1008FF47\nXF86Launch8 269025096 0x1008FF48\nXF86Launch9 269025097 0x1008FF49\nXF86LaunchA 269025098 0x1008FF4A\nXF86LaunchB 269025099 0x1008FF4B\nXF86LaunchC 269025100 0x1008FF4C\nXF86LaunchD 269025101 0x1008FF4D\nXF86LaunchE 269025102 0x1008FF4E\nXF86LaunchF 269025103 0x1008FF4F\nXF86ApplicationLeft 269025104 0x1008FF50\nXF86ApplicationRight 269025105 0x1008FF51\nXF86Book 269025106 0x1008FF52\nXF86CD 269025107 0x1008FF53\nXF86Calculater 269025108 0x1008FF54\nXF86Clear 269025109 0x1008FF55\nXF86Close 269025110 0x1008FF56\nXF86Copy 269025111 0x1008FF57\nXF86Cut 269025112 0x1008FF58\nXF86Display 269025113 0x1008FF59\nXF86DOS 269025114 0x1008FF5A\nXF86Documents 269025115 0x1008FF5B\nXF86Excel 269025116 0x1008FF5C\nXF86Explorer 269025117 0x1008FF5D\nXF86Game 269025118 0x1008FF5E\nXF86Go 269025119 0x1008FF5F\nXF86iTouch 269025120 0x1008FF60\nXF86LogOff 269025121 0x1008FF61\nXF86Market 269025122 0x1008FF62\nXF86Meeting 269025123 0x1008FF63\nXF86MenuKB 269025125 0x1008FF65\nXF86MenuPB 269025126 0x1008FF66\nXF86MySites 269025127 0x1008FF67\nXF86New 269025128 0x1008FF68\nXF86News 269025129 0x1008FF69\nXF86OfficeHome 269025130 0x1008FF6A\nXF86Open 269025131 0x1008FF6B\nXF86Option 269025132 0x1008FF6C\nXF86Paste 269025133 0x1008FF6D\nXF86Phone 269025134 0x1008FF6E\nXF86Q 269025136 0x1008FF70\nXF86Reply 269025138 0x1008FF72\nXF86Reload 269025139 0x1008FF73\nXF86RotateWindows 269025140 0x1008FF74\nXF86RotationPB 269025141 0x1008FF75\nXF86RotationKB 269025142 0x1008FF76\nXF86Save 269025143 0x1008FF77\nXF86ScrollUp 269025144 0x1008FF78\nXF86ScrollDown 269025145 0x1008FF79\nXF86ScrollClick 269025146 0x1008FF7A\nXF86Send 269025147 0x1008FF7B\nXF86Spell 269025148 0x1008FF7C\nXF86SplitScreen 269025149 0x1008FF7D\nXF86Support 269025150 0x1008FF7E\nXF86TaskPane 269025151 0x1008FF7F\nXF86Terminal 269025152 0x1008FF80\nXF86Tools 269025153 0x1008FF81\nXF86Travel 269025154 0x1008FF82\nXF86UserPB 269025156 0x1008FF84\nXF86User1KB 269025157 0x1008FF85\nXF86User2KB 269025158 0x1008FF86\nXF86Video 269025159 0x1008FF87\nXF86WheelButton 269025160 0x1008FF88\nXF86Word 269025161 0x1008FF89\nXF86Xfer 269025162 0x1008FF8A\nXF86ZoomIn 269025163 0x1008FF8B\nXF86ZoomOut 269025164 0x1008FF8C\nXF86Away 269025165 0x1008FF8D\nXF86Messenger 269025166 0x1008FF8E\nXF86WebCam 269025167 0x1008FF8F\nXF86MailForward 269025168 0x1008FF90\nXF86Pictures 269025169 0x1008FF91\nXF86Music 269025170 0x1008FF92\nXF86Battery 269025171 0x1008FF93\nXF86Bluetooth 269025172 0x1008FF94\nXF86WLAN 269025173 0x1008FF95\nXF86UWB 269025174 0x1008FF96\nXF86AudioForward 269025175 0x1008FF97\nXF86AudioRepeat 269025176 0x1008FF98\nXF86AudioRandomPlay 269025177 0x1008FF99\nXF86Subtitle 269025178 0x1008FF9A\nXF86AudioCycleTrack 269025179 0x1008FF9B\nXF86CycleAngle 269025180 0x1008FF9C\nXF86FrameBack 269025181 0x1008FF9D\nXF86FrameForward 269025182 0x1008FF9E\nXF86Time 269025183 0x1008FF9F\nXF86Select 269025184 0x1008FFA0\nXF86View 269025185 0x1008FFA1\nXF86TopMenu 269025186 0x1008FFA2\nXF86Red 269025187 0x1008FFA3\nXF86Green 269025188 0x1008FFA4\nXF86Yellow 269025189 0x1008FFA5\nXF86Blue 269025190 0x1008FFA6\nXF86Suspend 269025191 0x1008FFA7\nXF86Hibernate 269025192 0x1008FFA8\nXF86TouchpadToggle 269025193 0x1008FFA9\nXF86TouchpadOn 269025200 0x1008FFB0\nXF86TouchpadOff 269025201 0x1008FFB1\nXF86AudioMicMute 269025202 0x1008FFB2\nXF86Keyboard 269025203 0x1008FFB3\nXF86WWAN 269025204 0x1008FFB4\nXF86RFKill 269025205 0x1008FFB5\nXF86AudioPreset 269025206 0x1008FFB6\nXF86RotationLockToggle 269025207 0x1008FFB7\nXF86FullScreen 269025208 0x1008FFB8\n.CE\n.SH \"SEE ALSO\"\nbind(n), event(n)\n.SH KEYWORDS\nbind, binding, event, keysym\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/label.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH label n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nlabel \\- Create and manipulate 'label' non-interactive text or image widgets\n.SH SYNOPSIS\n\\fBlabel\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-activebackground\t\\-disabledforeground\t\\-padx\n\\-activeforeground\t\\-font\t\\-pady\n\\-anchor\t\\-foreground\t\\-relief\n\\-background\t\\-highlightbackground\t\\-takefocus\n\\-bitmap\t\\-highlightcolor\t\\-text\n\\-borderwidth\t\\-highlightthickness\t\\-textvariable\n\\-compound\t\\-image\t\\-underline\n\\-cursor\t\\-justify\t\\-wraplength\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-height height Height\nSpecifies a desired height for the label.\nIf an image or bitmap is being displayed in the label then the value is in\nscreen units (i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR);\nfor text it is in lines of text.\nIf this option is not specified, the label's desired height is computed\nfrom the size of the image or bitmap or text being displayed in it.\n.OP \\-state state State\nSpecifies one of three states for the label: \\fBnormal\\fR, \\fBactive\\fR,\nor \\fBdisabled\\fR. In normal state the button is displayed using the\n\\fB\\-foreground\\fR and \\fB\\-background\\fR options. In active state\nthe label is displayed using the \\fB\\-activeforeground\\fR and\n\\fB\\-activebackground\\fR options. In the disabled state the\n\\fB\\-disabledforeground\\fR and \\fB\\-background\\fR options determine how\nthe button is displayed.\n.OP \\-width width Width\nSpecifies a desired width for the label.\nIf an image or bitmap is being displayed in the label then the value is in\nscreen units (i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR);\nfor text it is in characters.\nIf this option is not specified, the label's desired width is computed\nfrom the size of the image or bitmap or text being displayed in it.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBlabel\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a label widget.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the label such as its colors, font,\ntext, and initial relief. The \\fBlabel\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nA label is a widget that displays a textual string, bitmap or image.\nIf text is displayed, it must all be in a single font, but it\ncan occupy multiple lines on the screen (if it contains newlines\nor if wrapping occurs because of the \\fB\\-wraplength\\fR option) and\none of the characters may optionally be underlined using the\n\\fB\\-underline\\fR option.\nThe label can be manipulated in a few simple ways, such as\nchanging its relief or text, using the commands described below.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBlabel\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for label widgets:\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBlabel\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBlabel\\fR\ncommand.\n.SH BINDINGS\n.PP\nWhen a new label is created, it has no default event bindings:\nlabels are not intended to be interactive.\n.SH EXAMPLE\n.PP\n.CS\n# Make the widgets\n\\fBlabel\\fR .t -text \"This widget is at the top\" -bg red\n\\fBlabel\\fR .b -text \"This widget is at the bottom\" -bg green\n\\fBlabel\\fR .l -text \"Left\\enHand\\enSide\"\n\\fBlabel\\fR .r -text \"Right\\enHand\\enSide\"\ntext .mid\n\\&.mid insert end \"This layout is like Java's BorderLayout\"\n# Lay them out\npack .t -side top -fill x\npack .b -side bottom -fill x\npack .l -side left -fill y\npack .r -side right -fill y\npack .mid -expand 1 -fill both\n.CE\n.SH \"SEE ALSO\"\nlabelframe(n), button(n), ttk::label(n)\n.SH KEYWORDS\nlabel, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/labelframe.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH labelframe n 8.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nlabelframe \\- Create and manipulate 'labelframe' labelled container widgets\n.SH SYNOPSIS\n\\fBlabelframe\\fI pathName\\fR ?\\fIoptions\\fR?\n.SO\n\\-borderwidth\t\\-highlightbackground\t\\-pady\n\\-cursor\t\\-highlightcolor\t\\-relief\n\\-font\t\\-highlightthickness\t\\-takefocus\n\\-foreground\t\\-padx\t\\-text\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-background background Background\nThis option is the same as the standard \\fB\\-background\\fR option\nexcept that its value may also be specified as an empty string.\nIn this case, the widget will display no background or border, and\nno colors will be consumed from its colormap for its background\nand border.\n.OP \\-class class Class\nSpecifies a class for the window.\nThis class will be used when querying the option database for\nthe window's other options, and it will also be used later for\nother purposes such as bindings.\nThe \\fB\\-class\\fR option may not be changed with the \\fBconfigure\\fR\nwidget command.\n.OP \\-colormap colormap Colormap\nSpecifies a colormap to use for the window.\nThe value may be either \\fBnew\\fR, in which case a new colormap is\ncreated for the window and its children, or the name of another\nwindow (which must be on the same screen and have the same visual\nas \\fIpathName\\fR), in which case the new window will use the colormap\nfrom the specified window.\nIf the \\fB\\-colormap\\fR option is not specified, the new window\nuses the same colormap as its parent.\nThis option may not be changed with the \\fBconfigure\\fR\nwidget command.\n.OP \\-height height Height\nSpecifies the desired height for the window in any of the forms\nacceptable to \\fBTk_GetPixels\\fR.\nIf this option is negative or zero then the window will\nnot request any size at all.\n.OP \\-labelanchor labelAnchor LabelAnchor\nSpecifies where to place the label. A label is only displayed if the\n\\fB\\-text\\fR option is not the empty string.\nValid values for this option are (listing them clockwise)\n\\fBnw\\fR, \\fBn\\fR, \\fBne\\fR, \\fBen\\fR, \\fBe\\fR, \\fBes\\fR,\n\\fBse\\fR, \\fBs\\fR,\\fBsw\\fR, \\fBws\\fR, \\fBw\\fR and \\fBwn\\fR.\nThe default value is \\fBnw\\fR.\n.OP \\-labelwidget labelWidget LabelWidget\nSpecifies a widget to use as label. This overrides any \\fB\\-text\\fR\noption. The widget must exist before being used as \\fB\\-labelwidget\\fR\nand if it is not a descendant of this window, it will be raised\nabove it in the stacking order.\n.OP \\-visual visual Visual\nSpecifies visual information for the new window in any of the\nforms accepted by \\fBTk_GetVisual\\fR.\nIf this option is not specified, the new window will use the same\nvisual as its parent.\nThe \\fB\\-visual\\fR option may not be modified with the \\fBconfigure\\fR\nwidget command.\n.OP \\-width width Width\nSpecifies the desired width for the window in any of the forms\nacceptable to \\fBTk_GetPixels\\fR.\nIf this option is negative or zero then the window will\nnot request any size at all.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBlabelframe\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a labelframe widget.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the labelframe such as its background color\nand relief. The \\fBlabelframe\\fR command returns the\npath name of the new window.\n.PP\nA labelframe is a simple widget. Its primary purpose is to act as a\nspacer or container for complex window layouts. It has the features\nof a \\fBframe\\fR plus the ability to display a label.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBlabelframe\\fR command creates a new Tcl command whose\nname is the same as the path name of the labelframe's window. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIPathName\\fR is the name of the command, which is the same as\nthe labelframe widget's path name. \\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for frame widgets:\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBlabelframe\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBlabelframe\\fR\ncommand.\n.SH BINDINGS\n.PP\nWhen a new labelframe is created, it has no default event bindings:\nlabelframes are not intended to be interactive.\n.SH EXAMPLE\n.PP\nThis shows how to build part of a GUI for a hamburger vendor. The\n\\fBlabelframe\\fR widgets are used to organize the available choices by\nthe kinds of things that the choices are being made over.\n.PP\n.CS\ngrid [\\fBlabelframe\\fR .burger -text \"Burger\"] \\e\n [\\fBlabelframe\\fR .bun -text \"Bun\"] -sticky news\ngrid [\\fBlabelframe\\fR .cheese -text \"Cheese Option\"] \\e\n [\\fBlabelframe\\fR .pickle -text \"Pickle Option\"] -sticky news\nforeach {type name val} {\n burger Beef beef\n burger Lamb lamb\n burger Vegetarian beans\n\n bun Plain white\n bun Sesame seeds\n bun Wholemeal brown\n\n cheese None none\n cheese Cheddar cheddar\n cheese Edam edam\n cheese Brie brie\n cheese Gruy\\eu00e8re gruyere\n cheese \"Monterey Jack\" jack\n\n pickle None none\n pickle Gherkins gherkins\n pickle Onions onion\n pickle Chili chili\n} {\n set w [radiobutton .$type.$val -text $name -anchor w \\e\n -variable $type -value $val]\n pack $w -side top -fill x\n}\nset burger beef\nset bun white\nset cheese none\nset pickle none\n.CE\n.SH \"SEE ALSO\"\nframe(n), label(n), ttk::labelframe(n)\n.SH KEYWORDS\nlabelframe, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/listbox.n", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1997 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH listbox n 8.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nlistbox \\- Create and manipulate 'listbox' item list widgets\n.SH SYNOPSIS\n\\fBlistbox\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-background\t\\-highlightbackground\t\\-selectforeground\n\\-borderwidth\t\\-highlightcolor\t\\-setgrid\n\\-cursor\t\\-highlightthickness\t\\-takefocus\n\\-disabledforeground\t\\-justify\t\\-xscrollcommand\n\\-exportselection\t\\-relief\t\\-yscrollcommand\n\\-font\t\\-selectbackground\n\\-foreground\t\\-selectborderwidth\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-activestyle activeStyle ActiveStyle\nSpecifies the style in which to draw the active element. This must be\none of \\fBdotbox\\fR (show a focus ring around the active element),\n\\fBnone\\fR (no special indication of active element) or\n\\fBunderline\\fR (underline the active element).\nThe default is \\fBunderline\\fR on Windows, and \\fBdotbox\\fR elsewhere.\n.OP \\-height height Height\nSpecifies the desired height for the window, in lines.\nIf zero or less, then the desired height for the window is made just\nlarge enough to hold all the elements in the listbox.\n.OP \\-inactiveselectbackground inactiveSelectBackground Foreground\nSpecifies the background color to use for the selection when the window does\nnot have the input focus. The option's value may be an empty string or have\nany of the forms accepted by \\fBTk_GetColor\\fR. If empty then the value of the\n\\fB-selectbackground\\fR widget or item configuration option is used when the\nwindow does not have the focus. The default value depends on the windowing\nsystem: it is non-empty on \\fBaqua\\fR and \\fBwin32\\fR, and an empty string on\n\\fBx11\\fR.\n.OP \\-inactiveselectforeground inactiveSelectForeground Background\nSpecifies the foreground color to use for the selection when the window does\nnot have the input focus. The option's value may be an empty string or have\nany of the forms accepted by \\fBTk_GetColor\\fR. This option is only relevant\nif the value of the \\fB-inactiveselectbackground\\fR option is non-empty, in\nwhich case, if the value of this option is an empty string then the value of\nthe \\fB-selectforeground\\fR widget configuration option is used when the window\ndoes not have the focus. The default value depends on the windowing system: it\nis non-empty on \\fBaqua\\fR and \\fBwin32\\fR, and an empty string on \\fBx11\\fR.\n.OP \\-listvariable listVariable Variable\nSpecifies the name of a global variable. The value of the variable is a list to\nbe displayed inside the widget; if the variable value changes then the\nwidget will automatically update itself to reflect the new value. Attempts\nto assign a variable with an invalid list value to \\fB\\-listvariable\\fR\nwill cause an error. Attempts to unset a variable in use as a\n\\fB\\-listvariable\\fR will fail but will not generate an error.\n.OP \\-selectmode selectMode SelectMode\nSpecifies one of several styles for manipulating the selection.\nThe value of the option may be arbitrary, but the default bindings\nexpect it to be either \\fBsingle\\fR, \\fBbrowse\\fR, \\fBmultiple\\fR,\nor \\fBextended\\fR; the default value is \\fBbrowse\\fR.\n.OP \\-state state State\nSpecifies one of two states for the listbox: \\fBnormal\\fR or \\fBdisabled\\fR.\nIf the listbox is disabled then items may not be inserted or deleted,\nitems are drawn in the \\fB\\-disabledforeground\\fR color, and selection\ncannot be modified and is not shown (though selection information is retained).\n.OP \\-width width Width\nSpecifies the desired width for the window in characters.\nIf the font does not have a uniform width then the width of the character\n.QW 0\nis used in translating from character units to screen units.\nIf zero or less, then the desired width for the window is made just\nlarge enough to hold all the elements in the listbox.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBlistbox\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a listbox widget.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the listbox such as its colors, font,\ntext, and relief. The \\fBlistbox\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nA listbox is a widget that displays a list of strings, one per line.\nWhen first created, a new listbox has no elements.\nElements may be added or deleted using widget commands described\nbelow. In addition, one or more elements may be selected as described\nbelow.\nIf a listbox is exporting its selection (see \\fB\\-exportselection\\fR\noption), then it will observe the standard X11 protocols\nfor handling the selection.\nListbox selections are available as type \\fBSTRING\\fR;\nthe value of the selection will be the text of the selected elements, with\nnewlines separating the elements.\n.PP\nIt is not necessary for all the elements to be\ndisplayed in the listbox window at once; commands described below\nmay be used to change the view in the window. Listboxes allow\nscrolling in both directions using the standard \\fB\\-xscrollcommand\\fR\nand \\fB\\-yscrollcommand\\fR options.\nThey also support scanning, as described below.\n.SH \"INDICES\"\n.PP\nMany of the widget commands for listboxes take one or more indices\nas arguments.\nAn index specifies a particular element of the listbox, in any of\nthe following ways:\n.IP \\fInumber\\fR 12\nSpecifies the element as a numerical index, where 0 corresponds\nto the first element in the listbox.\n.IP \\fBactive\\fR 12\nIndicates the element that has the location cursor. This element\nwill be displayed as specified by \\fB\\-activestyle\\fR when the listbox\nhas the keyboard focus, and it is specified with the \\fBactivate\\fR\nwidget command.\n.IP \\fBanchor\\fR 12\nIndicates the anchor point for the selection, which is set with the\n\\fBselection anchor\\fR widget command.\n.IP \\fBend\\fR 12\nIndicates the end of the listbox.\nFor most commands this refers to the last element in the listbox,\nbut for a few commands such as \\fBindex\\fR and \\fBinsert\\fR\nit refers to the element just after the last one.\n.IP \\fB@\\fIx\\fB,\\fIy\\fR 12\nIndicates the element that covers the point in the listbox window\nspecified by \\fIx\\fR and \\fIy\\fR (in pixel coordinates). If no\nelement covers that point, then the closest element to that\npoint is used.\n.PP\nIndexes support the same simple interpretation as\nfor the command \\fBstring index\\fR, with simple integer index\narithmetic and indexing relative to \\fBend\\fR.\nIn the widget command descriptions below, arguments named \\fIindex\\fR,\n\\fIfirst\\fR, and \\fIlast\\fR always contain text indices in one of\nthe above forms.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBlistbox\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for listbox widgets:\n.\\\" METHOD: activate\n.TP\n\\fIpathName \\fBactivate\\fI index\\fR\n.\nSets the active element to the one indicated by \\fIindex\\fR.\nIf \\fIindex\\fR is outside the range of elements in the listbox\nthen the closest element is activated.\nThe active element is drawn as specified by \\fB\\-activestyle\\fR when the\nwidget has the input focus, and its index may be retrieved with the\nindex \\fBactive\\fR.\n.\\\" METHOD: bbox\n.TP\n\\fIpathName \\fBbbox\\fI index\\fR\n.\nReturns a list of four numbers describing the bounding box of\nthe text in the element given by \\fIindex\\fR.\nThe first two elements of the list give the x and y coordinates\nof the upper-left corner of the screen area covered by the text\n(specified in pixels relative to the widget) and the last two\nelements give the width and height of the area, in pixels.\nIf no part of the element given by \\fIindex\\fR is visible on the\nscreen,\nor if \\fIindex\\fR refers to a non-existent element,\nthen the result is an empty string; if the element is\npartially visible, the result gives the full area of the element,\nincluding any parts that are not visible.\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBlistbox\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBlistbox\\fR\ncommand.\n.\\\" METHOD: curselection\n.TP\n\\fIpathName \\fBcurselection\\fR\n.\nReturns a list containing the numerical indices of\nall of the elements in the listbox that are currently selected.\nIf there are no elements selected in the listbox then an empty\nstring is returned.\n.\\\" METHOD: delete\n.TP\n\\fIpathName \\fBdelete \\fIfirst \\fR?\\fIlast\\fR?\n.\nDeletes one or more elements of the listbox. \\fIFirst\\fR and \\fIlast\\fR\nare indices specifying the first and last elements in the range\nto delete. If \\fIlast\\fR is not specified it defaults to\n\\fIfirst\\fR, i.e. a single element is deleted.\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget \\fIfirst\\fR ?\\fIlast\\fR?\n.\nIf \\fIlast\\fR is omitted, returns the contents of the listbox\nelement indicated by \\fIfirst\\fR,\nor an empty string if \\fIfirst\\fR refers to a non-existent element.\nIf \\fIlast\\fR is specified, the command returns a list whose elements\nare all of the listbox elements between \\fIfirst\\fR and \\fIlast\\fR,\ninclusive.\nBoth \\fIfirst\\fR and \\fIlast\\fR may have any of the standard\nforms for indices.\n.\\\" METHOD: index\n.TP\n\\fIpathName \\fBindex \\fIindex\\fR\n.\nReturns the integer index value that corresponds to \\fIindex\\fR.\nIf \\fIindex\\fR is \\fBend\\fR the return value is a count of the number\nof elements in the listbox (not the index of the last element).\n.\\\" METHOD: insert\n.TP\n\\fIpathName \\fBinsert \\fIindex \\fR?\\fIelement element ...\\fR?\n.\nInserts zero or more new elements in the list just before the\nelement given by \\fIindex\\fR. If \\fIindex\\fR is specified as\n\\fBend\\fR then the new elements are added to the end of the\nlist. Returns an empty string.\n.\\\" METHOD: itemcget\n.TP\n\\fIpathName \\fBitemcget \\fIindex option\\fR\n.\nReturns the current value of the item configuration option given\nby \\fIoption\\fR. \\fIOption\\fR may have any of the values accepted\nby the \\fBitemconfigure\\fR command.\n.\\\" METHOD: itemconfigure\n.TP\n\\fIpathName \\fBitemconfigure \\fIindex\\fR ?\\fIoption\\fR? ?\\fIvalue\\fR? ?\\fIoption value ...\\fR?\n.\nQuery or modify the configuration options of an item in the listbox.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for the item (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string. The following options\nare currently supported for items:\n.RS\n.\\\" OPTION: -background\n.TP\n\\fB\\-background \\fIcolor\\fR\n.\n\\fIColor\\fR specifies the background color to use when displaying the\nitem. It may have any of the forms accepted by \\fBTk_GetColor\\fR.\n.\\\" OPTION: -foreground\n.TP\n\\fB\\-foreground \\fIcolor\\fR\n.\n\\fIColor\\fR specifies the foreground color to use when displaying the\nitem. It may have any of the forms accepted by \\fBTk_GetColor\\fR.\n.\\\" OPTION: -selectbackground\n.TP\n\\fB\\-selectbackground \\fIcolor\\fR\n.\n\\fIcolor\\fR specifies the background color to use when displaying the\nitem while it is selected. It may have any of the forms accepted by\n\\fBTk_GetColor\\fR.\n.\\\" OPTION: -selectforeground\n.TP\n\\fB\\-selectforeground \\fIcolor\\fR\n.\n\\fIcolor\\fR specifies the foreground color to use when displaying the\nitem while it is selected. It may have any of the forms accepted by\n\\fBTk_GetColor\\fR.\n.RE\n.\\\" METHOD: nearest\n.TP\n\\fIpathName \\fBnearest \\fIy\\fR\n.\nGiven a y-coordinate within the listbox window, this command returns\nthe index of the (visible) listbox element nearest to that y-coordinate.\n.\\\" METHOD: scan\n.TP\n\\fIpathName \\fBscan\\fI option args\\fR\n.\nThis command is used to implement scanning on listboxes. It has\ntwo forms, depending on \\fIoption\\fR:\n.RS\n.TP\n\\fIpathName \\fBscan mark \\fIx y\\fR\n.\nRecords \\fIx\\fR and \\fIy\\fR and the current view in the listbox\nwindow; used in conjunction with later \\fBscan dragto\\fR commands.\nTypically this command is associated with a mouse button press in\nthe widget. It returns an empty string.\n.TP\n\\fIpathName \\fBscan dragto \\fIx y\\fR.\n.\nThis command computes the difference between its \\fIx\\fR and \\fIy\\fR\narguments and the \\fIx\\fR and \\fIy\\fR arguments to the last\n\\fBscan mark\\fR command for the widget.\nIt then adjusts the view by 10 times the\ndifference in coordinates. This command is typically associated\nwith mouse motion events in the widget, to produce the effect of\ndragging the list at high speed through the window. The return\nvalue is an empty string.\n.RE\n.\\\" METHOD: see\n.TP\n\\fIpathName \\fBsee \\fIindex\\fR\n.\nAdjust the view in the listbox so that the element given by \\fIindex\\fR\nis visible.\nIf the element is already visible then the command has no effect;\nif the element is near one edge of the window then the listbox\nscrolls to bring the element into view at the edge; otherwise\nthe listbox scrolls to center the element.\n.\\\" METHOD: selection\n.TP\n\\fIpathName \\fBselection \\fIoption arg\\fR\n.\nThis command is used to adjust the selection within a listbox. It\nhas several forms, depending on \\fIoption\\fR:\n.RS\n.TP\n\\fIpathName \\fBselection anchor \\fIindex\\fR\n.\nSets the selection anchor to the element given by \\fIindex\\fR.\nIf \\fIindex\\fR refers to a non-existent element, then the closest\nelement is used.\nThe selection anchor is the end of the selection that is fixed\nwhile dragging out a selection with the mouse.\nThe index \\fBanchor\\fR may be used to refer to the anchor\nelement.\n.TP\n\\fIpathName \\fBselection clear \\fIfirst \\fR?\\fIlast\\fR?\n.\nIf any of the elements between \\fIfirst\\fR and \\fIlast\\fR\n(inclusive) are selected, they are deselected.\nThe selection state is not changed for elements outside\nthis range.\n.TP\n\\fIpathName \\fBselection includes \\fIindex\\fR\n.\nReturns 1 if the element indicated by \\fIindex\\fR is currently\nselected, 0 if it is not.\n.TP\n\\fIpathName \\fBselection set \\fIfirst \\fR?\\fIlast\\fR?\n.\nSelects all of the elements in the range between\n\\fIfirst\\fR and \\fIlast\\fR, inclusive, without affecting\nthe selection state of elements outside that range.\n.RE\n.\\\" METHOD: size\n.TP\n\\fIpathName \\fBsize\\fR\n.\nReturns a decimal string indicating the total number of elements\nin the listbox.\n.\\\" METHOD: xview\n.TP\n\\fIpathName \\fBxview \\fR?\\fIargs\\fR\n.\nThis command is used to query and change the horizontal position of the\ninformation in the widget's window. It can take any of the following\nforms:\n.RS\n.TP\n\\fIpathName \\fBxview\\fR\n.\nReturns a list containing two elements.\nEach element is a real fraction between 0 and 1; together they describe\nthe horizontal span that is visible in the window.\nFor example, if the first element is .2 and the second element is .6,\n20% of the listbox's text is off-screen to the left, the middle 40% is visible\nin the window, and 40% of the text is off-screen to the right.\nThese are the same values passed to scrollbars via the \\fB\\-xscrollcommand\\fR\noption.\n.TP\n\\fIpathName \\fBxview \\fIindex\\fR\n.\nAdjusts the view in the window so that the character position given by\n\\fIindex\\fR is displayed at the left edge of the window.\nCharacter positions are defined by the width of the character \\fB0\\fR.\n.TP\n\\fIpathName \\fBxview moveto\\fI fraction\\fR\n.\nAdjusts the view in the window so that \\fIfraction\\fR of the\ntotal width of the listbox text is off-screen to the left.\n\\fIfraction\\fR must be a fraction between 0 and 1.\n.TP\n\\fIpathName \\fBxview scroll \\fInumber what\\fR\n.\nThis command shifts the view in the window left or right according to\n\\fInumber\\fR and \\fIwhat\\fR.\n\\fINumber\\fR must be an integer or a float, but if it is a float then\nit is converted to an integer, rounded away from 0.\n\\fIWhat\\fR must be either \\fBpages\\fR or \\fBunits\\fR or an abbreviation\nof one of these.\nIf \\fIwhat\\fR is \\fBpages\\fR then the view adjusts by\n\\fInumber\\fR screenfuls.\nIf \\fInumber\\fR is negative then characters farther to the left\nbecome visible; if it is positive then characters farther to the right\nbecome visible.\nIf \\fIwhat\\fR is \\fBunits\\fR, the view adjusts left or right by\n\\fInumber\\fR character units (the width of the \\fB0\\fR character)\non the display.\n.RE\n.\\\" METHOD: yview\n.TP\n\\fIpathName \\fByview \\fR?\\fIargs\\fR?\n.\nThis command is used to query and change the vertical position of the\ntext in the widget's window.\nIt can take any of the following forms:\n.RS\n.TP\n\\fIpathName \\fByview\\fR\n.\nReturns a list containing two elements, both of which are real fractions\nbetween 0 and 1.\nThe first element gives the position of the listbox element at the\ntop of the window, relative to the listbox as a whole (0.5 means\nit is halfway through the listbox, for example).\nThe second element gives the position of the listbox element just after\nthe last one in the window, relative to the listbox as a whole.\nThese are the same values passed to scrollbars via the \\fB\\-yscrollcommand\\fR\noption.\n.TP\n\\fIpathName \\fByview \\fIindex\\fR\n.\nAdjusts the view in the window so that the element given by\n\\fIindex\\fR is displayed at the top of the window.\n.TP\n\\fIpathName \\fByview moveto\\fI fraction\\fR\n.\nAdjusts the view in the window so that the element given by \\fIfraction\\fR\nappears at the top of the window.\n\\fIFraction\\fR is a fraction between 0 and 1; 0 indicates the first\nelement in the listbox, 0.33 indicates the element one-third the\nway through the listbox, and so on.\n.TP\n\\fIpathName \\fByview scroll \\fInumber what\\fR\n.\nThis command adjusts the view in the window up or down according to\n\\fInumber\\fR and \\fIwhat\\fR.\n\\fINumber\\fR must be an integer or a float, but if it is a float then\nit is converted to an integer, rounded away from 0.\n\\fIWhat\\fR must be either \\fBpages\\fR or \\fBunits\\fR.\nIf \\fIwhat\\fR is \\fBpages\\fR then\nthe view adjusts by \\fInumber\\fR screenfuls.\nIf \\fInumber\\fR is negative then earlier elements\nbecome visible; if it is positive then later elements\nbecome visible.\nIf \\fIwhat\\fR is \\fBunits\\fR, the view adjusts up or down by\n\\fInumber\\fR lines.\n.RE\n.SH \"DEFAULT BINDINGS\"\n.PP\nTk automatically creates class bindings for listboxes that give them\nMotif-like behavior. Much of the behavior of a listbox is determined\nby its \\fB\\-selectmode\\fR option, which selects one of four ways\nof dealing with the selection.\n.PP\nIf the selection mode is \\fBsingle\\fR or \\fBbrowse\\fR, at most one\nelement can be selected in the listbox at once.\nIn both modes, clicking button 1 on an element selects\nit and deselects any other selected item.\nIn \\fBbrowse\\fR mode it is also possible to drag the selection\nwith button 1.\nOn button 1, the listbox will also take focus if it has a \\fBnormal\\fR\nstate.\n.PP\nIf the selection mode is \\fBmultiple\\fR or \\fBextended\\fR,\nany number of elements may be selected at once, including discontiguous\nranges. In \\fBmultiple\\fR mode, clicking button 1 on an element\ntoggles its selection state without affecting any other elements.\nIn \\fBextended\\fR mode, pressing button 1 on an element selects\nit, deselects everything else, and sets the anchor to the element\nunder the mouse; dragging the mouse with button 1\ndown extends the selection to include all the elements between\nthe anchor and the element under the mouse, inclusive.\n.PP\nMost people will probably want to use \\fBbrowse\\fR mode for\nsingle selections and \\fBextended\\fR mode for multiple selections;\nthe other modes appear to be useful only in special situations.\n.PP\nAny time the set of selected item(s) in the listbox is updated by the\nuser through the keyboard or mouse, the virtual event\n\\fB<>\\fR will be generated. This virtual event will not\nbe generated when adjusting the selection with the \\fIpathName\n\\fBselection\\fR command. It is easiest to bind to this event to be\nmade aware of any user changes to listbox selection.\n.PP\nIn addition to the above behavior, the following additional behavior\nis defined by the default bindings:\n.IP [1]\nIn \\fBextended\\fR mode, the selected range can be adjusted by pressing\nbutton 1 with the Shift key down: this modifies the selection to\nconsist of the elements between the anchor and the element under\nthe mouse, inclusive.\nThe un-anchored end of this new selection can also be dragged with\nthe button down.\n.IP [2]\nIn \\fBextended\\fR mode, pressing button 1 with the Control key down\nstarts a toggle operation: the anchor is set to the element under\nthe mouse, and its selection state is reversed. The selection state\nof other elements is not changed.\nIf the mouse is dragged with button 1 down, then the selection state\nof all elements between the anchor and the element under the mouse\nis set to match that of the anchor element; the selection state of\nall other elements remains what it was before the toggle operation\nbegan.\n.IP [3]\nIf the mouse leaves the listbox window with button 1 down, the window\nscrolls away from the mouse, making information visible that used\nto be off-screen on the side of the mouse.\nThe scrolling continues until the mouse re-enters the window, the\nbutton is released, or the end of the listbox is reached.\n.IP [4]\nMouse button 2 may be used for scanning.\nIf it is pressed and dragged over the listbox, the contents of\nthe listbox drag at high speed in the direction the mouse moves.\n.IP [5]\nIf the Up or Down key is pressed, the location cursor (active\nelement) moves up or down one element.\nIf the selection mode is \\fBbrowse\\fR or \\fBextended\\fR then the\nnew active element is also selected and all other elements are\ndeselected.\nIn \\fBextended\\fR mode the new active element becomes the\nselection anchor.\n.IP [6]\nIn \\fBextended\\fR mode, Shift-Up and Shift-Down move the location\ncursor (active element) up or down one element and also extend\nthe selection to that element in a fashion similar to dragging\nwith mouse button 1.\n.IP [7]\nThe Left and Right keys scroll the listbox view left and right\nby the width of the character \\fB0\\fR.\nControl-Left and Control-Right scroll the listbox view left and\nright by the width of the window.\nControl-Prior and Control-Next also scroll left and right by\nthe width of the window.\n.IP [8]\nThe Prior and Next keys scroll the listbox view up and down\nby one page (the height of the window).\n.IP [9]\nThe Home and End keys scroll the listbox horizontally to\nthe left and right edges, respectively.\n.IP [10]\nControl-Home sets the location cursor to the first element in\nthe listbox, selects that element, and deselects everything else\nin the listbox.\n.IP [11]\nControl-End sets the location cursor to the last element in\nthe listbox, selects that element, and deselects everything else\nin the listbox.\n.IP [12]\nIn \\fBextended\\fR mode, Control-Shift-Home extends the selection\nto the first element in the listbox and Control-Shift-End extends\nthe selection to the last element.\n.IP [13]\nIn \\fBmultiple\\fR mode, Control-Shift-Home moves the location cursor\nto the first element in the listbox and Control-Shift-End moves\nthe location cursor to the last element.\n.IP [14]\nThe space and Select keys make a selection at the location cursor\n(active element) just as if mouse button 1 had been pressed over\nthis element.\n.IP [15]\nIn \\fBextended\\fR mode, Control-Shift-space and Shift-Select\nextend the selection to the active element just as if button 1\nhad been pressed with the Shift key down.\n.IP [16]\nIn \\fBextended\\fR mode, the Escape key cancels the most recent\nselection and restores all the elements in the selected range\nto their previous selection state.\n.IP [17]\nControl-/ selects everything in the widget, except in\n\\fBsingle\\fR and \\fBbrowse\\fR modes, in which case it selects\nthe active element and deselects everything else.\n.IP [18]\nControl-backslash deselects everything in the widget, except in\n\\fBbrowse\\fR mode where it has no effect.\n.IP [19]\nThe F16 key (labelled Copy on many Sun workstations) or Meta-w\ncopies the selection in the widget to the clipboard, if there is\na selection.\n.PP\nThe behavior of listboxes can be changed by defining new bindings for\nindividual widgets or by redefining the class bindings.\n.SH \"SEE ALSO\"\nttk::treeview(n)\n.SH KEYWORDS\nlistbox, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/loadTk.n", "content": "'\\\"\n'\\\" Copyright (c) 1995-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH \"Safe Tk\" n 8.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nsafe::loadTk \\- Load Tk into a safe interpreter.\n.SH SYNOPSIS\n\\fBsafe::loadTk \\fIchild\\fR ?\\fB\\-use\\fI windowId\\fR? ?\\fB\\-display\\fI displayName\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nSafe Tk is based on Safe Tcl, which provides a mechanism that allows\nrestricted and mediated access to auto-loading and packages for safe\ninterpreters. Safe Tk adds the ability to configure the interpreter for safe\nTk operations and load Tk into safe interpreters.\n.PP\nThe \\fBsafe::loadTk\\fR command initializes the required data structures in\nthe named safe interpreter and then loads Tk into it. The interpreter must\nhave been created with \\fBsafe::interpCreate\\fR or have been initialized\nwith \\fBsafe::interpInit\\fR. The command returns the name of the safe\ninterpreter. If \\fB\\-use\\fR is specified, the window identified by the\nspecified system dependent identifier \\fIwindowId\\fR is used to contain the\n.QW .\nwindow of the safe interpreter; it can be any valid id, eventually referencing\na window belonging to another application. As a convenience, if the window you\nplan to use is a Tk Window of the application you can use the window name\n(e.g.,\n.QW \\fB.x.y\\fR )\ninstead of its window Id (e.g., from \\fBwinfo id\\fI .x.y\\fR).\nWhen \\fB\\-use\\fR is not specified, a new toplevel window is created for the\n.QW .\nwindow of the safe interpreter. On X11 if you want the embedded window to use\nanother display than the default one, specify it with \\fB\\-display\\fR. See\nthe \\fBSECURITY ISSUES\\fR section below for implementation details.\n.SH \"SECURITY ISSUES\"\n.PP\nPlease read the \\fBsafe\\fR manual page for Tcl to learn about the basic\nsecurity considerations for Safe Tcl.\n.PP\n\\fBsafe::loadTk\\fR adds the value of \\fBtk_library\\fR taken from the parent\ninterpreter to the virtual access path of the safe interpreter so that\nauto-loading will work in the safe interpreter.\n.PP\nTk initialization is now safe with respect to not trusting the child's state\nfor startup. \\fBsafe::loadTk\\fR registers the child's name so when the Tk\ninitialization (\\fBTk_SafeInit\\fR) is called and in turn calls the parent's\n\\fBsafe::InitTk\\fR it will return the desired \\fBargv\\fR equivalent\n(\\fB\\-use\\fI windowId\\fR, correct \\fB\\-display\\fR, etc.)\n.PP\nWhen \\fB\\-use\\fR is not used, the new toplevel created is specially decorated\nso the user is always aware that the user interface presented comes from a\npotentially unsafe code and can easily delete the corresponding interpreter.\n.PP\nOn X11, conflicting \\fB\\-use\\fR and \\fB\\-display\\fR are likely to generate a\nfatal X error.\n.SH \"SEE ALSO\"\nsafe(n), interp(n), library(n), load(n), package(n), source(n), unknown(n)\n.SH KEYWORDS\nalias, auto-loading, auto_mkindex, load, parent interpreter, safe\ninterpreter, child interpreter, source\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/lower.n", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH lower n 3.3 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nlower \\- Change a window's position in the stacking order\n.SH SYNOPSIS\n\\fBlower \\fIwindow \\fR?\\fIbelowThis\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nIf the \\fIbelowThis\\fR argument is omitted then the command lowers\n\\fIwindow\\fR so that it is below all of its siblings in the stacking\norder (it will be obscured by any siblings that overlap it and\nwill not obscure any siblings).\nIf \\fIbelowThis\\fR is specified then it must be the path name of\na window that is either a sibling of \\fIwindow\\fR or the descendant\nof a sibling of \\fIwindow\\fR.\nIn this case the \\fBlower\\fR command will insert\n\\fIwindow\\fR into the stacking order just below \\fIbelowThis\\fR\n(or the ancestor of \\fIbelowThis\\fR that is a sibling of \\fIwindow\\fR);\nthis could end up either raising or lowering \\fIwindow\\fR.\n.PP\nAll \\fBtoplevel\\fR windows may be restacked with respect to each\nother, whatever their relative path names, but the window manager is\nnot obligated to strictly honor requests to restack.\n.SH \"SEE ALSO\"\nraise\n.SH KEYWORDS\nlower, obscure, stacking order\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/man.macros", "content": ".\\\" The -*- nroff -*- definitions below are for supplemental macros used\n.\\\" in Tcl/Tk manual entries.\n.\\\"\n.\\\" .AP type name in/out ?indent?\n.\\\"\tStart paragraph describing an argument to a library procedure.\n.\\\"\ttype is type of argument (int, etc.), in/out is either \"in\", \"out\",\n.\\\"\tor \"in/out\" to describe whether procedure reads or modifies arg,\n.\\\"\tand indent is equivalent to second arg of .IP (shouldn't ever be\n.\\\"\tneeded; use .AS below instead)\n.\\\"\n.\\\" .AS ?type? ?name?\n.\\\"\tGive maximum sizes of arguments for setting tab stops. Type and\n.\\\"\tname are examples of largest possible arguments that will be passed\n.\\\"\tto .AP later. If args are omitted, default tab stops are used.\n.\\\"\n.\\\" .BS\n.\\\"\tStart box enclosure. From here until next .BE, everything will be\n.\\\"\tenclosed in one large box.\n.\\\"\n.\\\" .BE\n.\\\"\tEnd of box enclosure.\n.\\\"\n.\\\" .CS\n.\\\"\tBegin code excerpt.\n.\\\"\n.\\\" .CE\n.\\\"\tEnd code excerpt.\n.\\\"\n.\\\" .VS ?version? ?br?\n.\\\"\tBegin vertical sidebar, for use in marking newly-changed parts\n.\\\"\tof man pages. The first argument is ignored and used for recording\n.\\\"\tthe version when the .VS was added, so that the sidebars can be\n.\\\"\tfound and removed when they reach a certain age. If another argument\n.\\\"\tis present, then a line break is forced before starting the sidebar.\n.\\\"\n.\\\" .VE\n.\\\"\tEnd of vertical sidebar.\n.\\\"\n.\\\" .DS\n.\\\"\tBegin an indented unfilled display.\n.\\\"\n.\\\" .DE\n.\\\"\tEnd of indented unfilled display.\n.\\\"\n.\\\" .SO ?manpage?\n.\\\"\tStart of list of standard options for a Tk widget. The manpage\n.\\\"\targument defines where to look up the standard options; if\n.\\\"\tomitted, defaults to \"options\". The options follow on successive\n.\\\"\tlines, in three columns separated by tabs.\n.\\\"\n.\\\" .SE\n.\\\"\tEnd of list of standard options for a Tk widget.\n.\\\"\n.\\\" .OP cmdName dbName dbClass\n.\\\"\tStart of description of a specific option. cmdName gives the\n.\\\"\toption's name as specified in the class command, dbName gives\n.\\\"\tthe option's name in the option database, and dbClass gives\n.\\\"\tthe option's class in the option database.\n.\\\"\n.\\\" .UL arg1 arg2\n.\\\"\tPrint arg1 underlined, then print arg2 normally.\n.\\\"\n.\\\" .QW arg1 ?arg2?\n.\\\"\tPrint arg1 in quotes, then arg2 normally (for trailing punctuation).\n.\\\"\n.\\\" .PQ arg1 ?arg2?\n.\\\"\tPrint an open parenthesis, arg1 in quotes, then arg2 normally\n.\\\"\t(for trailing punctuation) and then a closing parenthesis.\n.\\\"\n.\\\"\t# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.\n.if t .wh -1.3i ^B\n.nr ^l \\n(.l\n.ad b\n.\\\"\t# Start an argument description\n.de AP\n.ie !\"\\\\$4\"\" .TP \\\\$4\n.el \\{\\\n. ie !\"\\\\$2\"\" .TP \\\\n()Cu\n. el .TP 15\n.\\}\n.ta \\\\n()Au \\\\n()Bu\n.ie !\"\\\\$3\"\" \\{\\\n\\&\\\\$1 \\\\fI\\\\$2\\\\fP (\\\\$3)\n.\\\".b\n.\\}\n.el \\{\\\n.br\n.ie !\"\\\\$2\"\" \\{\\\n\\&\\\\$1\t\\\\fI\\\\$2\\\\fP\n.\\}\n.el \\{\\\n\\&\\\\fI\\\\$1\\\\fP\n.\\}\n.\\}\n..\n.\\\"\t# define tabbing values for .AP\n.de AS\n.nr )A 10n\n.if !\"\\\\$1\"\" .nr )A \\\\w'\\\\$1'u+3n\n.nr )B \\\\n()Au+15n\n.\\\"\n.if !\"\\\\$2\"\" .nr )B \\\\w'\\\\$2'u+\\\\n()Au+3n\n.nr )C \\\\n()Bu+\\\\w'(in/out)'u+2n\n..\n.AS Tcl_Interp Tcl_CreateInterp in/out\n.\\\"\t# BS - start boxed text\n.\\\"\t# ^y = starting y location\n.\\\"\t# ^b = 1\n.de BS\n.br\n.mk ^y\n.nr ^b 1u\n.if n .nf\n.if n .ti 0\n.if n \\l'\\\\n(.lu\\(ul'\n.if n .fi\n..\n.\\\"\t# BE - end boxed text (draw box now)\n.de BE\n.nf\n.ti 0\n.mk ^t\n.ie n \\l'\\\\n(^lu\\(ul'\n.el \\{\\\n.\\\"\tDraw four-sided box normally, but don't draw top of\n.\\\"\tbox if the box started on an earlier page.\n.ie !\\\\n(^b-1 \\{\\\n\\h'-1.5n'\\L'|\\\\n(^yu-1v'\\l'\\\\n(^lu+3n\\(ul'\\L'\\\\n(^tu+1v-\\\\n(^yu'\\l'|0u-1.5n\\(ul'\n.\\}\n.el \\}\\\n\\h'-1.5n'\\L'|\\\\n(^yu-1v'\\h'\\\\n(^lu+3n'\\L'\\\\n(^tu+1v-\\\\n(^yu'\\l'|0u-1.5n\\(ul'\n.\\}\n.\\}\n.fi\n.br\n.nr ^b 0\n..\n.\\\"\t# VS - start vertical sidebar\n.\\\"\t# ^Y = starting y location\n.\\\"\t# ^v = 1 (for troff; for nroff this doesn't matter)\n.de VS\n.if !\"\\\\$2\"\" .br\n.mk ^Y\n.ie n 'mc \\s12\\(br\\s0\n.el .nr ^v 1u\n..\n.\\\"\t# VE - end of vertical sidebar\n.de VE\n.ie n 'mc\n.el \\{\\\n.ev 2\n.nf\n.ti 0\n.mk ^t\n\\h'|\\\\n(^lu+3n'\\L'|\\\\n(^Yu-1v\\(bv'\\v'\\\\n(^tu+1v-\\\\n(^Yu'\\h'-|\\\\n(^lu+3n'\n.sp -1\n.fi\n.ev\n.\\}\n.nr ^v 0\n..\n.\\\"\t# Special macro to handle page bottom: finish off current\n.\\\"\t# box/sidebar if in box/sidebar mode, then invoked standard\n.\\\"\t# page bottom macro.\n.de ^B\n.ev 2\n'ti 0\n'nf\n.mk ^t\n.if \\\\n(^b \\{\\\n.\\\"\tDraw three-sided box if this is the box's first page,\n.\\\"\tdraw two sides but no top otherwise.\n.ie !\\\\n(^b-1 \\h'-1.5n'\\L'|\\\\n(^yu-1v'\\l'\\\\n(^lu+3n\\(ul'\\L'\\\\n(^tu+1v-\\\\n(^yu'\\h'|0u'\\c\n.el \\h'-1.5n'\\L'|\\\\n(^yu-1v'\\h'\\\\n(^lu+3n'\\L'\\\\n(^tu+1v-\\\\n(^yu'\\h'|0u'\\c\n.\\}\n.if \\\\n(^v \\{\\\n.nr ^x \\\\n(^tu+1v-\\\\n(^Yu\n\\kx\\h'-\\\\nxu'\\h'|\\\\n(^lu+3n'\\ky\\L'-\\\\n(^xu'\\v'\\\\n(^xu'\\h'|0u'\\c\n.\\}\n.bp\n'fi\n.ev\n.if \\\\n(^b \\{\\\n.mk ^y\n.nr ^b 2\n.\\}\n.if \\\\n(^v \\{\\\n.mk ^Y\n.\\}\n..\n.\\\"\t# DS - begin display\n.de DS\n.RS\n.nf\n.sp\n..\n.\\\"\t# DE - end display\n.de DE\n.fi\n.RE\n.sp\n..\n.\\\"\t# SO - start of list of standard options\n.de SO\n'ie '\\\\$1'' .ds So \\\\fBoptions\\\\fR\n'el .ds So \\\\fB\\\\$1\\\\fR\n.SH \"STANDARD OPTIONS\"\n.LP\n.nf\n.ta 5.5c 11c\n.ft B\n..\n.\\\"\t# SE - end of list of standard options\n.de SE\n.fi\n.ft R\n.LP\nSee the \\\\*(So manual entry for details on the standard options.\n..\n.\\\"\t# OP - start of full description for a single option\n.de OP\n.LP\n.nf\n.ta 4c\nCommand-Line Name:\t\\\\fB\\\\$1\\\\fR\nDatabase Name:\t\\\\fB\\\\$2\\\\fR\nDatabase Class:\t\\\\fB\\\\$3\\\\fR\n.fi\n.IP\n..\n.\\\"\t# CS - begin code excerpt\n.de CS\n.RS\n.nf\n.ta .25i .5i .75i 1i\n..\n.\\\"\t# CE - end code excerpt\n.de CE\n.fi\n.RE\n..\n.\\\"\t# UL - underline word\n.de UL\n\\\\$1\\l'|0\\(ul'\\\\$2\n..\n.\\\"\t# QW - apply quotation marks to word\n.de QW\n.ie '\\\\*(lq'\"' ``\\\\$1''\\\\$2\n.\\\"\" fix emacs highlighting\n.el \\\\*(lq\\\\$1\\\\*(rq\\\\$2\n..\n.\\\"\t# PQ - apply parens and quotation marks to word\n.de PQ\n.ie '\\\\*(lq'\"' (``\\\\$1''\\\\$2)\\\\$3\n.\\\"\" fix emacs highlighting\n.el (\\\\*(lq\\\\$1\\\\*(rq\\\\$2)\\\\$3\n..\n.\\\"\t# QR - quoted range\n.de QR\n.ie '\\\\*(lq'\"' ``\\\\$1''\\\\-``\\\\$2''\\\\$3\n.\\\"\" fix emacs highlighting\n.el \\\\*(lq\\\\$1\\\\*(rq\\\\-\\\\*(lq\\\\$2\\\\*(rq\\\\$3\n..\n.\\\"\t# MT - \"empty\" string\n.de MT\n.QW \"\"\n..\n" }, { "path": "doc/menu.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1997 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH menu n 4.1 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nmenu, tk_menuSetFocus \\- Create and manipulate 'menu' widgets and menubars\n.SH SYNOPSIS\n.nf\n\\fBmenu\\fI pathName \\fR?\\fIoptions\\fR?\n\\fBtk_menuSetFocus\\fI pathName\\fR\n.fi\n.SO\n\\-activebackground\t\\-borderwidth\t\\-foreground\n\\-activeborderwidth\t\\-cursor\t\\-relief\n\\-activeforeground\t\\-disabledforeground\t\\-takefocus\n\\-background\t\\-font\t\\-activerelief\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-postcommand postCommand Command\nIf this option is specified then it provides a Tcl command to execute\neach time the menu is posted. The command is invoked by the \\fBpost\\fR\nwidget command before posting the menu. Note that in Tk 8.0 on Macintosh\nand Windows, all post-commands in a system of menus are executed before any\nof those menus are posted.\nThis is due to the limitations in the individual platforms' menu managers.\n.OP \\-selectcolor selectColor Background\nFor menu entries that are check buttons or radio buttons, this option\nspecifies the color to display in the indicator when the check button\nor radio button is selected.\n.OP \\-tearoff tearOff TearOff\nThis option must have a proper boolean value (default is false),\nwhich specifies whether or not the menu should include a tear-off\nentry at the top. If so, it will exist as entry 0 of the menu and\nthe other entries will number starting at 1. The default menu\nbindings arrange for the menu to be torn off when the tear-off entry\nis invoked.\nThis option is ignored under Aqua/macOS, where menus cannot\nbe torn off.\n.OP \\-tearoffcommand tearOffCommand TearOffCommand\nIf this option has a non-empty value, then it specifies a Tcl command\nto invoke whenever the menu is torn off. The actual command will\nconsist of the value of this option, followed by a space, followed\nby the name of the menu window, followed by a space, followed by\nthe name of the name of the torn off menu window. For example, if\nthe option's value is\n.QW \"\\fBa b\\fR\"\nand menu \\fB.x.y\\fR is torn off to\ncreate a new menu \\fB.x.tearoff1\\fR, then the command\n.QW \"\\fBa b .x.y .x.tearoff1\\fR\"\nwill be invoked.\nThis option is ignored under Aqua/macOS, where menus cannot\nbe torn off.\n.OP \\-title title Title\nThe string will be used to title the window created when this menu is\ntorn off. If the title is NULL, then the window will have the title\nof the menubutton or the text of the cascade item from which this menu\nwas invoked.\n.OP \\-type type Type\nThis option can be one of \\fBmenubar\\fR, \\fBtearoff\\fR, or\n\\fBnormal\\fR, and is set when the menu is created. While the string\nreturned by the configuration database will change if this option is\nchanged, this does not affect the menu widget's behavior. This is used\nby the cloning mechanism and is not normally set outside of the Tk\nlibrary.\n.BE\n.SH INTRODUCTION\n.PP\nThe \\fBmenu\\fR command creates a new top-level window (given\nby the \\fIpathName\\fR argument) and makes it into a menu widget.\nThat menu widget can either be used as a pop-up window or applied to a\n\\fBtoplevel\\fR (with its \\fB\\-menu\\fR option) to make it into the menubar for\nthat toplevel.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the menu such as its colors and font.\nThe \\fBmenu\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nA menu is a widget that displays a collection of one-line entries arranged\nin one or more columns. There exist several different types of entries,\neach with different properties. Entries of different types may be\ncombined in a single menu. Menu entries are not the same as\nentry widgets. In fact, menu entries are not even distinct widgets;\nthe entire menu is one widget.\n.PP\nMenu entries are displayed with up to three separate fields.\nThe main field is a label in the form of a text string,\na bitmap, or an image, controlled by the \\fB\\-label\\fR,\n\\fB\\-bitmap\\fR, and \\fB\\-image\\fR options for the entry.\nIf the \\fB\\-accelerator\\fR option is specified for an entry then a second\ntextual field is displayed to the right of the label. The accelerator\ntypically describes a keystroke sequence that may be used in the\napplication to cause the same result as invoking the menu entry.\nThis is a display option, it does not actually set the corresponding\nbinding (which can be achieved using the \\fBbind\\fR command).\nThe third field is an \\fIindicator\\fR. The indicator is present only for\ncheckbutton or radiobutton entries. It indicates whether the entry\nis selected or not, and is displayed to the left of the entry's\nstring.\n.PP\nIn normal use, an entry becomes active (displays itself differently)\nwhenever the mouse pointer is over the entry. If a mouse\nbutton is released over the entry then the entry is \\fIinvoked\\fR.\nThe effect of invocation is different for each type of entry;\nthese effects are described below in the sections on individual\nentries.\n.PP\nEntries may be \\fIdisabled\\fR, which causes their labels\nand accelerators to be displayed\nwith dimmer colors.\nThe default menu bindings will not allow\na disabled entry to be activated or invoked.\nDisabled entries may be re-enabled, at which point it becomes\npossible to activate and invoke them again.\n.PP\nWhenever a menu's active entry is changed, a <> virtual\nevent is send to the menu. The active item can then be queried from\nthe menu, and an action can be taken, such as setting\ncontext-sensitive help text for the entry.\n.SH \"TYPES OF ENTRIES\"\n.SS \"COMMAND ENTRIES\"\n.PP\nThe most common kind of menu entry is a command entry, which\nbehaves much like a button widget. When a command entry is\ninvoked, a Tcl command is executed. The Tcl\ncommand is specified with the \\fB\\-command\\fR option.\n.SS \"SEPARATOR ENTRIES\"\n.PP\nA separator is an entry that is displayed as a horizontal dividing\nline. A separator may not be activated or invoked, and it has\nno behavior other than its display appearance.\n.SS \"CHECKBUTTON ENTRIES\"\n.PP\nA checkbutton menu entry behaves much like a checkbutton widget.\nWhen it is invoked it toggles back and forth between the selected\nand deselected states. When the entry is selected, a particular\nvalue is stored in a particular global variable (as determined by\nthe \\fB\\-onvalue\\fR and \\fB\\-variable\\fR options for the entry); when\nthe entry is deselected another value (determined by the\n\\fB\\-offvalue\\fR option) is stored in the global variable.\nAn indicator box is displayed to the left of the label in a checkbutton\nentry. If the entry is selected then the indicator's center is displayed\nin the color given by the \\fB\\-selectcolor\\fR option for the entry;\notherwise the indicator's center is displayed in the background color for\nthe menu. If a \\fB\\-command\\fR option is specified for a checkbutton\nentry, then its value is evaluated as a Tcl command each time the entry\nis invoked; this happens after toggling the entry's\nselected state.\n.SS \"RADIOBUTTON ENTRIES\"\n.PP\nA radiobutton menu entry behaves much like a radiobutton widget.\nRadiobutton entries are organized in groups of which only one\nentry may be selected at a time. Whenever a particular entry\nbecomes selected it stores a particular value into a particular\nglobal variable (as determined by the \\fB\\-value\\fR and\n\\fB\\-variable\\fR options for the entry). This action\ncauses any previously-selected entry in the same group\nto deselect itself.\nOnce an entry has become selected, any change to the entry's\nassociated variable will cause the entry to deselect itself.\nGrouping of radiobutton entries is determined by their\nassociated variables: if two entries have the same associated\nvariable then they are in the same group.\nAn indicator diamond is displayed to the left of the label in each\nradiobutton entry. If the entry is selected then the indicator's\ncenter is displayed in the color given by the \\fB\\-selectcolor\\fR option\nfor the entry;\notherwise the indicator's center is displayed in the background color for\nthe menu. If a \\fB\\-command\\fR option is specified for a radiobutton\nentry, then its value is evaluated as a Tcl command each time the entry\nis invoked; this happens after selecting the entry.\n.SS \"CASCADE ENTRIES\"\n.PP\nA cascade entry is one with an associated menu (determined\nby the \\fB\\-menu\\fR option). Cascade entries allow the construction\nof cascading menus.\nThe \\fBpostcascade\\fR widget command can be used to post and unpost\nthe associated menu just next to of the cascade entry.\nThe associated menu must be a child of the menu containing\nthe cascade entry (this is needed in order for menu traversal to\nwork correctly).\n.PP\nA cascade entry posts its associated menu by invoking a\nTcl command of the form\n.CS\n\\fImenu\\fB post \\fIx y\\fR\n.CE\nwhere \\fImenu\\fR is the path name of the associated menu, and \\fIx\\fR\nand \\fIy\\fR are the root-window coordinates of the upper-right\ncorner of the cascade entry.\nOn Unix, the lower-level menu is unposted by executing a Tcl command with\nthe form\n.CS\n\\fImenu\\fB unpost\\fR\n.CE\nwhere \\fImenu\\fR is the name of the associated menu.\nOn other platforms, the platform's native code takes care of unposting the\nmenu.\n.PP\nIf a \\fB\\-command\\fR option is specified for a cascade entry then it is\nevaluated as a Tcl command whenever the entry is invoked. This is not\nsupported on Windows.\n.SS \"TEAR-OFF ENTRIES\"\n.PP\nA tear-off entry appears at the top of the menu if enabled with the\n\\fB\\-tearoff\\fR option. It is not like other menu entries in that\nit cannot be created with the \\fBadd\\fR widget command and\ncannot be deleted with the \\fBdelete\\fR widget command.\nWhen a tear-off entry is created it appears as a dashed line at\nthe top of the menu. Under the default bindings, invoking the\ntear-off entry causes a torn-off copy to be made of the menu and\nall of its submenus.\n.SH \"MENUBARS\"\n.PP\nAny menu can be set as a menubar for a toplevel window (see\n\\fBtoplevel\\fR command for syntax). On the Macintosh, whenever the\ntoplevel is in front, this menu's cascade items will appear in the\nmenubar across the top of the main screen. On Windows and Unix, this\nmenu's items will be displayed in a menubar across the top of the\nwindow. These menus will behave according to the interface guidelines\nof their platforms. In particular, since macOS requires that a\nmenubar always be displayed for the active app, if no menu is assigned\nby a \\fBconfigure -menu\\fR for a certain toplevel then a standard default\nmenu will be displayed whenever that toplevel has focus.\n\nFor every menu set as a menubar, a clone menu is\nmade. See the \\fBCLONES\\fR section for more information.\n.PP\nAs noted, menubars may behave differently on different platforms. One\nexample of this concerns the handling of checkbuttons and radiobuttons\nwithin the menu. While it is permitted to put these menu elements on\nmenubars, they may not be drawn with indicators on some platforms, due\nto system restrictions.\n.SS \"SPECIAL MENUS IN MENUBARS\"\n.PP\nCertain menus in a menubar will be treated specially. On the Macintosh,\naccess to the special Application, Window and Help menus is provided. On\nWindows, access to the Windows System menu in each window is provided.\nOn X Windows, a special right-justified help menu may be provided if\nMotif menu compatibility is enabled. In all cases, these menus must be\ncreated with the command name of the menubar menu concatenated with the\nspecial name. So for a menubar named .menubar, on the Macintosh, the\nspecial menus would be .menubar.apple, .menubar.window and .menubar.help;\non Windows, the special menu would be .menubar.system; on X Windows,\nthe help menu would be .menubar.help.\n.PP\nWhen Tk sees a .menubar.apple menu as the first menu in a menubar on the\nMacintosh, that menu's contents make up the first items of the\nApplication menu whenever the window containing the menubar is in front.\nAfter all of the Tk-defined items, the menu will have a separator,\nfollowed by all standard Application menu items.\nSuch a .apple menu must be present in a menu when that menu is first\nconfigured as a toplevel's menubar, otherwise a default application menu\n(hidden from Tk) will be inserted into the menubar at that time and\nsubsequent addition of a .apple menu will no longer result in it\nbecoming the Application menu.\n.PP\nWhen Tk sees a .menubar.window menu on the Macintosh, the menu's\ncontents are inserted into the standard Window menu of the user's\nmenubar whenever the window's menubar is in front. The first items in\nthe menu are provided by macOS, and the names of the current\ntoplevels are automatically appended after all the Tk-defined items and\na separator. The Window menu on the Mac also allows toggling the\nwindow into a fullscreen state, and managing a tabbed window interface\n(multiple windows grouped into a single window) if supported by that\nversion of the operating system.\n.PP\nWhen Tk sees a .menubar.help menu on the Macintosh, the menu's contents\nare appended to the standard Help menu of the user's menubar whenever\nthe window's menubar is in front. The first items in the menu\nare provided by macOS.\n.PP\nWhen Tk sees a System menu on Windows, its items are appended to the\nsystem menu that the menubar is attached to. This menu is tied to the\napplication icon and can be invoked with the mouse or by typing\nAlt+Spacebar. Due to limitations in the Windows API, any font changes,\ncolors, images, bitmaps, or tearoff images will not appear in the\nsystem menu.\n.PP\nWhen Tk sees a Help menu on X Windows and Motif menu compatibility is\nenabled the menu is moved to be last in the menubar and is right\njustified. Motif menu compatibility is enabled by setting the Tk option\n\\fB*Menu.useMotifHelp\\fR to true.\n.SH \"CLONES\"\n.PP\nWhen a menu is set as a menubar for a toplevel window, or when a menu\nis torn off, a clone of the menu is made. This clone is a menu widget\nin its own right, but it is a child of the original. Changes in the\nconfiguration of the original are reflected in the\nclone. Additionally, any cascades that are pointed to are also cloned\nso that menu traversal will work right. Clones are destroyed when\neither the tearoff or menubar goes away, or when the original menu is\ndestroyed.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBmenu\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command.\n.PP\nMany of the widget commands for a menu take as one argument an\nindicator of which entry of the menu to operate on. These\nindicators are called \\fIindex\\fRes and may be specified in\nany of the following forms:\n.IP \\fBactive\\fR 12\nIndicates the entry that is currently active. If no entry is\nactive then this form is equivalent to \\fB{}\\fR. This form may\nnot be abbreviated.\n.IP \\fBend\\fR 12\nIndicates the bottommost entry in the menu. If there are no\nentries in the menu then this form is equivalent to \\fB{}\\fR.\nThis form may not be abbreviated.\n.IP \\fBlast\\fR 12\nSame as \\fBend\\fR.\n.IP \\fB{}\\fR 12\nIndicates\n.QW \"no entry at all\" ;\nthis is used most commonly with\nthe \\fBactivate\\fR option to deactivate all the entries in the\nmenu. In most cases the specification of \\fB{}\\fR causes\nnothing to happen in the widget command.\n.IP \\fB@\\fIx\\fB,\\fIy\\fR 12\nIndicates the entry that covers the point in the menu's window specified\nby \\fIx\\fR and \\fIy\\fR (in pixel coordinates).\nIf no entry covers that point, then this form is equivalent to \\fB{}\\fR.\nIf only a single number is specified, it is treated as the y-coordinate.\n.IP \\fInumber\\fR 12\nSpecifies the entry numerically, where 0 corresponds\nto the top-most entry of the menu, 1 to the entry below it, and\nso on.\n.IP \\fIid\\fR 12\nIf the index does not satisfy one of the above forms then the menu is\nsearched for an entry with the specified id.\n.IP \\fIpattern\\fR 12\nIf all of the above methods for finding an entry fail, this\nform is used. \\fIPattern\\fR is pattern-matched against the label of\neach entry in the menu, in order from the top down, until a\nmatching entry is found. The rules of \\fBstring match\\fR\nare used.\n.PP\nIf the index could match more than one of the above forms, then\nthe form earlier in the above list takes precedence.\nIndexes support the same simple interpretation as\nfor the command \\fBstring index\\fR, with simple integer index\narithmetic and indexing relative to \\fBend\\fR.\n.PP\nThe following widget commands are possible for menu widgets:\n.\\\" METHOD: activate\n.TP\n\\fIpathName \\fBactivate \\fIindex\\fR\n.\nChange the state of the entry indicated by \\fIindex\\fR to \\fBactive\\fR\nand redisplay it using its active colors.\nAny previously-active entry is deactivated. If \\fIindex\\fR\nis specified as \\fB{}\\fR, or if the specified entry is\ndisabled, then the menu ends up with no active entry.\nReturns an empty string.\n.\\\" METHOD: add\n.TP\n\\fIpathName \\fBadd \\fItype \\fR?\\fIid\\fR? ?\\fIoption value option value ...\\fR?\n.\nAdd a new entry to the bottom of the menu. The new entry's type\nis given by \\fItype\\fR and must be one of \\fBcascade\\fR,\n\\fBcheckbutton\\fR, \\fBcommand\\fR, \\fBradiobutton\\fR, or \\fBseparator\\fR,\nor a unique abbreviation of one of the above.\nIf the \\fIid\\fR argument is specified, it is used as the entry identifier;\n\\fIid\\fR must not already exist in the menu. Otherwise, a new unique\nidentifier is generated.\nIf additional arguments are present, they specify the options listed in the\n\\fBMENU ENTRY OPTIONS\\fR section below.\nThe \\fBadd\\fR widget command returns the id of the new entry.\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget \\fIoption\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBmenu\\fR\ncommand.\n.\\\" METHOD: clone\n.TP\n\\fIpathName \\fBclone \\fInewPathname\\fR ?\\fIcloneType\\fR?\n.\nMakes a clone of the current menu named \\fInewPathName\\fR. This clone\nis a menu in its own right, but any changes to the clone are\npropagated to the original menu and vice versa. \\fIcloneType\\fR can be\n\\fBnormal\\fR, \\fBmenubar\\fR, or \\fBtearoff\\fR. Should not normally be\ncalled outside of the Tk library. See the \\fBCLONES\\fR section for\nmore information.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBmenu\\fR\ncommand.\n.\\\" METHOD: delete\n.TP\n\\fIpathName \\fBdelete \\fIindex1\\fR ?\\fIindex2\\fR?\n.\nDelete all of the menu entries between \\fIindex1\\fR and\n\\fIindex2\\fR inclusive.\nIf \\fIindex2\\fR is omitted then it defaults to \\fIindex1\\fR.\nAttempts to delete a tear-off menu entry are ignored (instead, you\nshould change the \\fB\\-tearoff\\fR option to remove the tear-off entry).\n.\\\" METHOD: entrycget\n.TP\n\\fIpathName \\fBentrycget \\fIindex option\\fR\n.\nReturns the current value of a configuration option for\nthe entry given by \\fIindex\\fR.\n\\fIOption\\fR may have any of the names described in the\n\\fBMENU ENTRY OPTIONS\\fR section below.\n.\\\" METHOD: entryconfigure\n.TP\n\\fIpathName \\fBentryconfigure \\fIindex \\fR?\\fIoptions...\\fR?\n.\nThis command is similar to the \\fBconfigure\\fR command, except that\nit applies to the options for an individual entry, whereas \\fBconfigure\\fR\napplies to the options for the menu as a whole.\n\\fIOptions\\fR may have any of the values described in the\n\\fBMENU ENTRY OPTIONS\\fR\nsection below. If \\fIoptions\\fR are specified, options are\nmodified as indicated in the command and the command returns an empty string.\nIf no \\fIoptions\\fR are specified, returns a list describing\nthe current options for entry \\fIindex\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list).\n.\\\" METHOD: id\n.TP\n\\fIpathName \\fBid \\fIindex\\fR\n.\nReturns the id of the menu entry given by \\fIindex\\fR.\nThis is the identifier that was assigned to the entry when it was created\nusing the \\fBadd\\fR or \\fBinsert\\fR widget command.\nReturns an empty string for the tear-off entry, or if \\fIindex\\fR is\nequivalent to \\fB{}\\fR.\n.\\\" METHOD: index\n.TP\n\\fIpathName \\fBindex \\fIindex\\fR\n.\nReturns the numerical index corresponding to \\fIindex\\fR, or\n\\fB{}\\fR if \\fIindex\\fR was specified as \\fB{}\\fR.\n.\\\" METHOD: insert\n.TP\n\\fIpathName \\fBinsert \\fIindex type \\fR?\\fIid\\fR? ?\\fIoption value option value ...\\fR?\n.\nSame as the \\fBadd\\fR widget command except that it inserts the new\nentry just before the entry given by \\fIindex\\fR, instead of appending\nto the end of the menu. The \\fItype\\fR, \\fIid\\fR, \\fIoption\\fR, and\n\\fIvalue\\fR arguments have the same interpretation as for the \\fBadd\\fR\nwidget command. It is not possible to insert new menu entries before the\ntear-off entry, if the menu has one.\nThe \\fBinsert\\fR widget command returns the id of the new entry.\n.\\\" METHOD: invoke\n.TP\n\\fIpathName \\fBinvoke \\fIindex\\fR\n.\nInvoke the action of the menu entry. See the sections on the\nindividual entries above for details on what happens. If the\nmenu entry is disabled then nothing happens. If the\nentry has a command associated with it then the result of that\ncommand is returned as the result of the \\fBinvoke\\fR widget\ncommand. Otherwise the result is an empty string. Note: invoking\na menu entry does not automatically unpost the menu; the default\nbindings normally take care of this before invoking the \\fBinvoke\\fR\nwidget command.\n.\\\" METHOD: post\n.TP\n\\fIpathName \\fBpost \\fIx y\\fR ?\\fIindex\\fR?\n.\nArrange for the menu to be displayed on the screen at the root-window\ncoordinates given by \\fIx\\fR and \\fIy\\fR. If an index is specified\nthe menu will be located so that the entry with that index is\ndisplayed at the point. These coordinates are adjusted if necessary to\nguarantee that the entire menu is visible on the screen. This command\nnormally returns an empty string. If the \\fB\\-postcommand\\fR option\nhas been specified, then its value is executed as a Tcl script before\nposting the menu and the result of that script is returned as the\nresult of the \\fBpost\\fR widget command. If an error returns while\nexecuting the command, then the error is returned without posting the\nmenu.\n.\\\" METHOD: postcascade\n.TP\n\\fIpathName \\fBpostcascade \\fIindex\\fR\n.\nPosts the submenu associated with the cascade entry given by\n\\fIindex\\fR, and unposts any previously posted submenu.\nIf \\fIindex\\fR does not correspond to a cascade entry,\nor if \\fIpathName\\fR is not posted,\nthe command has no effect except to unpost any currently posted\nsubmenu.\n.\\\" METHOD: type\n.TP\n\\fIpathName \\fBtype \\fIindex\\fR\n.\nReturns the type of the menu entry given by \\fIindex\\fR.\nThis is the \\fItype\\fR argument passed to the \\fBadd\\fR or \\fBinsert\\fR widget\ncommand when the entry was created, such as \\fBcommand\\fR\nor \\fBseparator\\fR, or \\fBtearoff\\fR for a tear-off entry.\n.\\\" METHOD: unpost\n.TP\n\\fIpathName \\fBunpost\\fR\n.\nUnmap the window so that it is no longer displayed. If a\nlower-level cascaded menu is posted, unpost that menu. Returns an\nempty string. This subcommand does not work on Windows and the\nMacintosh, as those platforms have their own way of unposting menus.\n.\\\" METHOD: xposition\n.TP\n\\fIpathName \\fBxposition \\fIindex\\fR\n.\nReturns a decimal string giving the x-coordinate within the menu\nwindow of the leftmost pixel in the entry specified by \\fIindex\\fR.\n.\\\" METHOD: yposition\n.TP\n\\fIpathName \\fByposition \\fIindex\\fR\n.\nReturns a decimal string giving the y-coordinate within the menu\nwindow of the topmost pixel in the entry specified by \\fIindex\\fR.\n.SH \"MENU ENTRY OPTIONS\"\nThe following options are allowed on menu entries. Most options are not\nsupported by all entry types.\n.\\\" OPTION: -activebackground\n.TP\n\\fB\\-activebackground \\fIvalue\\fR\n.\nSpecifies a background color to use for displaying this entry when it\nis active. This option is ignored on Aqua/macOS.\nIf it is specified as an empty string (the default), then the\n\\fB\\-activebackground\\fR option for the overall menu is used.\nIf the \\fBtk_strictMotif\\fR variable has been set to request strict\nMotif compliance, then this option is ignored and the \\fB\\-background\\fR\noption is used in its place.\nThis option is not available for separator or tear-off entries.\n.\\\" OPTION: -activeforeground\n.TP\n\\fB\\-activeforeground \\fIvalue\\fR\n.\nSpecifies a foreground color to use for displaying this entry when it\nis active. This option is ignored on Aqua/macOS.\nIf this option is specified as an empty string (the default), then the\n\\fB\\-activeforeground\\fR option for the overall menu is used.\n.\\\" OPTION: -accelerator\n.TP\n\\fB\\-accelerator \\fIvalue\\fR\n.\nSpecifies a string to display at the right side of the menu entry.\nNormally describes an accelerator keystroke sequence that may be\nused to invoke the same function as the menu entry. This is a display\noption, it does not actually set the corresponding binding (which can\nbe achieved using the \\fBbind\\fR command). This option is not available\nfor separator or tear-off entries.\n.\\\" OPTION: -background\n.TP\n\\fB\\-background \\fIvalue\\fR\n.\nSpecifies a background color to use for displaying this entry when it\nis in the normal state (neither active nor disabled).\nThis option is ignored on Aqua/macOS.\nIf it is specified as an empty string (the default), then the\n\\fB\\-background\\fR option for the overall menu is used.\nThis option is not available for separator or tear-off entries.\n.\\\" OPTION: -bitmap\n.TP\n\\fB\\-bitmap \\fIvalue\\fR\n.\nSpecifies a bitmap to display in the menu instead of a textual\nlabel, in any of the forms accepted by \\fBTk_GetBitmap\\fR.\nThis option overrides the \\fB\\-label\\fR option\n(as controlled by the \\fB\\-compound\\fR option)\nbut may be reset\nto an empty string to enable a textual label to be displayed.\nIf a \\fB\\-image\\fR option has been specified, it overrides\n\\fB\\-bitmap\\fR.\nThis option is not available for separator or tear-off entries.\n.\\\" OPTION: -columnbreak\n.TP\n\\fB\\-columnbreak \\fIvalue\\fR\n.\nWhen this option is zero, the entry appears below the previous entry. When\nthis option is one, the entry appears at the top of a new column in the\nmenu.\nThis option is ignored on Aqua/macOS, where menus are always a single\ncolumn.\n.\\\" OPTION: -command\n.TP\n\\fB\\-command \\fIvalue\\fR\n.\nSpecifies a Tcl command to execute when the menu entry is invoked.\nNot available for separator or tear-off entries.\n.\\\" OPTION: -compound\n.TP\n\\fB\\-compound \\fIvalue\\fR\n.\nSpecifies whether the menu entry should display both an image and text,\nand if so, where the image should be placed relative to the text.\nValid values for this option are \\fBbottom\\fR, \\fBcenter\\fR,\n\\fBleft\\fR, \\fBnone\\fR, \\fBright\\fR and \\fBtop\\fR. The default value\nis \\fBnone\\fR, meaning that the button will display either an image or\ntext, depending on the values of the \\fB\\-image\\fR and \\fB\\-bitmap\\fR\noptions.\n.\\\" OPTION: -font\n.TP\n\\fB\\-font \\fIvalue\\fR\n.\nSpecifies the font to use when drawing the label or accelerator\nstring in this entry.\nIf this option is specified as an empty string (the default) then\nthe \\fB\\-font\\fR option for the overall menu is used.\nThis option is not available for separator or tear-off entries.\n.\\\" OPTION: -foreground\n.TP\n\\fB\\-foreground \\fIvalue\\fR\n.\nSpecifies a foreground color to use for displaying this entry when it\nis in the normal state (neither active nor disabled).\nThis option is ignored on Aqua/macOS.\nIf it is specified as an empty string (the default), then the\n\\fB\\-foreground\\fR option for the overall menu is used.\nThis option is not available for separator or tear-off entries.\n.\\\" OPTION: -hidemargin\n.TP\n\\fB\\-hidemargin \\fIvalue\\fR\n.\nSpecifies whether the standard margins should be drawn for this menu\nentry. This is useful when creating palette with images in them, i.e.,\ncolor palettes, pattern palettes, etc. 1 indicates that the margin for\nthe entry is hidden; 0 means that the margin is used.\n.\\\" OPTION: -image\n.TP\n\\fB\\-image \\fIvalue\\fR\n.\nSpecifies an image to display in the menu instead of a text string\nor bitmap.\nThe image must have been created by some previous invocation of\n\\fBimage create\\fR.\nThis option overrides the \\fB\\-label\\fR and \\fB\\-bitmap\\fR options\n(as controlled by the \\fB\\-compound\\fR option)\nbut may be reset to an empty string to enable a textual or\nbitmap label to be displayed.\nThis option is not available for separator or tear-off entries.\n.\\\" OPTION: -indicatoron\n.TP\n\\fB\\-indicatoron \\fIvalue\\fR\n.\nAvailable only for checkbutton and radiobutton entries.\n\\fIValue\\fR is a boolean that determines whether or not the\nindicator should be displayed.\n.\\\" OPTION: -label\n.TP\n\\fB\\-label \\fIvalue\\fR\n.\nSpecifies a string to display as an identifying label in the menu\nentry. Not available for separator or tear-off entries.\n.\\\" OPTION: -menu\n.TP\n\\fB\\-menu \\fIvalue\\fR\n.\nAvailable only for cascade entries. Specifies the path name of\nthe submenu associated with this entry.\nThe submenu must be a child of the menu.\n.\\\" OPTION: -offvalue\n.TP\n\\fB\\-offvalue \\fIvalue\\fR\n.\nAvailable only for checkbutton entries. Specifies the value to\nstore in the entry's associated variable when the entry is\ndeselected.\n.\\\" OPTION: -onvalue\n.TP\n\\fB\\-onvalue \\fIvalue\\fR\n.\nAvailable only for checkbutton entries. Specifies the value to\nstore in the entry's associated variable when the entry is selected.\n.\\\" OPTION: -selectcolor\n.TP\n\\fB\\-selectcolor \\fIvalue\\fR\n.\nAvailable only for checkbutton and radiobutton entries.\nSpecifies the color to display in the indicator when the entry is\nselected.\nIf the value is an empty string (the default) then the \\fB\\-selectcolor\\fR\noption for the menu determines the indicator color.\n.\\\" OPTION: -selectimage\n.TP\n\\fB\\-selectimage \\fIvalue\\fR\n.\nAvailable only for checkbutton and radiobutton entries.\nSpecifies an image to display in the entry (in place of\nthe \\fB\\-image\\fR option) when it is selected.\n\\fIValue\\fR is the name of an image, which must have been created\nby some previous invocation of \\fBimage create\\fR.\nThis option is ignored unless the \\fB\\-image\\fR option has\nbeen specified.\n.\\\" OPTION: -state\n.TP\n\\fB\\-state \\fIvalue\\fR\n.\nSpecifies one of three states for the entry: \\fBnormal\\fR, \\fBactive\\fR,\nor \\fBdisabled\\fR. In normal state the entry is displayed using the\n\\fB\\-foreground\\fR option for the menu and the \\fB\\-background\\fR\noption from the entry or the menu.\nThe active state is typically used when the pointer is over the entry.\nIn active state the entry is displayed using the \\fB\\-activeforeground\\fR\noption for the menu along with the \\fB\\-activebackground\\fR option from\nthe entry. Disabled state means that the entry\nshould be insensitive: the default bindings will refuse to activate\nor invoke the entry.\nIn this state the entry is displayed according to the\n\\fB\\-disabledforeground\\fR option for the menu and the\n\\fB\\-background\\fR option from the entry.\nThis option is not available for separator entries.\n.\\\" OPTION: -underline\n.TP\n\\fB\\-underline \\fIvalue\\fR\n.\nSpecifies the integer index of a character to underline in the entry.\nThis option is also queried by the default bindings and used to\nimplement keyboard traversal.\n0 corresponds to the first character of the text displayed in the entry,\n1 to the next character, and so on.\nIf a bitmap or image is displayed in the entry then this option is ignored.\nThis option is not available for separator or tear-off entries.\n.\\\" OPTION: -value\n.TP\n\\fB\\-value \\fIvalue\\fR\n.\nAvailable only for radiobutton entries. Specifies the value to\nstore in the entry's associated variable when the entry is selected.\nIf an empty string is specified, then the \\fB\\-label\\fR option\nfor the entry as the value to store in the variable.\n.\\\" OPTION: -variable\n.TP\n\\fB\\-variable \\fIvalue\\fR\n.\nAvailable only for checkbutton and radiobutton entries. Specifies\nthe name of a global variable to set when the entry is selected.\nFor checkbutton entries the variable is also set when the entry\nis deselected. For radiobutton entries, changing the variable\ncauses the currently-selected entry to deselect itself.\n.RS\n.PP\nFor checkbutton entries, the default value of this option is taken from the\n\\fB\\-label\\fR option, and for radiobutton entries a single fixed value is\nused. It is recommended that you always set the \\fB\\-variable\\fR option when\ncreating either a checkbutton or a radiobutton.\n.RE\n.SH \"MENU CONFIGURATIONS\"\n.PP\nThe default bindings support four different ways of using menus:\n.TP\n\\fBPulldown Menus in Menubar\\fR\n.\nThis is the most common case. You create a menu widget that will become the\nmenu bar. You then add cascade entries to this menu, specifying the\npull down menus you wish to use in your menu bar. You then create all\nof the pulldowns. Once you have done this, specify the menu using the\n\\fB\\-menu\\fR option of the toplevel's widget command. See the\n\\fBtoplevel\\fR manual entry for details.\n.TP\n\\fBPulldown Menus in Menu Buttons\\fR\n.\nThis is the compatible way to do menu bars. You create one menubutton\nwidget for each top-level menu, and typically you arrange a series of\nmenubuttons in a row in a menubar window. You also create the top-level menus\nand any cascaded submenus, and tie them together with \\fB\\-menu\\fR\noptions in menubuttons and cascade menu entries. The top-level menu must\nbe a child of the menubutton, and each submenu must be a child of the\nmenu that refers to it. Once you have done this, the default bindings\nwill allow users to traverse and invoke the tree of menus via its\nmenubutton; see the \\fBmenubutton\\fR manual entry for details.\n.TP\n\\fBPopup Menus\\fR\n.\nPopup menus typically post in response to a mouse button press or\nkeystroke. You create the popup menus and any cascaded submenus,\nthen you call the \\fBtk_popup\\fR procedure at the appropriate time\nto post the top-level menu.\n.TP\n\\fBOption Menus\\fR\n.\nAn option menu consists of a menubutton with an associated menu\nthat allows you to select one of several values. The current value\nis displayed in the menubutton and is also stored in a global\nvariable. Use the \\fBtk_optionMenu\\fR procedure to create option\nmenubuttons and their menus.\n.TP\n\\fBTorn-off Menus\\fR\n.\nYou create a torn-off menu by invoking the tear-off entry at\nthe top of an existing menu. The default bindings will create a new menu\nthat is a copy of the original menu and leave it permanently\nposted as a top-level window. The torn-off menu behaves just\nthe same as the original menu.\n.SH \"DEFAULT BINDINGS\"\n.PP\nTk automatically creates class bindings for menus that give them\nthe following default behavior:\n.IP [1]\nWhen the mouse enters a menu, the entry underneath the mouse\ncursor activates; as the mouse moves around the menu, the active\nentry changes to track the mouse.\n.IP [2]\nWhen the mouse leaves a menu all of the entries in the menu\ndeactivate, except in the special case where the mouse moves from\na menu to a cascaded submenu.\n.IP [3]\nWhen a button is released over a menu, the active entry (if any) is invoked.\nThe menu also unposts unless it is a torn-off menu.\n.IP [4]\nThe Space and Return keys invoke the active entry and\nunpost the menu.\n.IP [5]\nIf any of the entries in a menu have letters underlined with\nthe \\fB\\-underline\\fR option, then pressing one of the underlined\nletters (or its upper-case or lower-case equivalent) invokes that\nentry and unposts the menu.\n.IP [6]\nThe Escape key aborts a menu selection in progress without invoking any\nentry. It also unposts the menu unless it is a torn-off menu.\n.IP [7]\nThe Up and Down keys activate the next higher or lower entry\nin the menu. When one end of the menu is reached, the active\nentry wraps around to the other end.\n.IP [8]\nThe Left key moves to the next menu to the left.\nIf the current menu is a cascaded submenu, then the submenu is\nunposted and the current menu entry becomes the cascade entry\nin the parent.\nIf the current menu is a top-level menu posted from a\nmenubutton, then the current menubutton is unposted and the\nnext menubutton to the left is posted.\nOtherwise the key has no effect.\nThe left-right order of menubuttons is determined by their stacking\norder: Tk assumes that the lowest menubutton (which by default\nis the first one created) is on the left.\n.IP [9]\nThe Right key moves to the next menu to the right.\nIf the current entry is a cascade entry, then the submenu is\nposted and the current menu entry becomes the first entry\nin the submenu.\nOtherwise, if the current menu was posted from a\nmenubutton, then the current menubutton is unposted and the\nnext menubutton to the right is posted.\n.PP\nDisabled menu entries are non-responsive: they do not activate and\nthey ignore mouse button presses and releases.\n.PP\nSeveral of the bindings make use of the command \\fBtk_menuSetFocus\\fR.\nIt saves the current focus and sets the focus to its \\fIpathName\\fR\nargument, which is a menu widget.\n.PP\nThe behavior of menus can be changed by defining new bindings for\nindividual widgets or by redefining the class bindings.\n.SH BUGS\n.PP\nAt present it is not possible to use the\noption database to specify values for the options to individual\nentries.\n.SH \"SEE ALSO\"\nbind(n), menubutton(n), ttk::menubutton(n), toplevel(n)\n.SH KEYWORDS\nmenu, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/menubutton.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1997 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH menubutton n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nmenubutton \\- Create and manipulate 'menubutton' pop-up menu indicator widgets\n.SH SYNOPSIS\n\\fBmenubutton\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-activebackground\t\\-disabledforeground\t\\-padx\n\\-activeforeground\t\\-font\t\\-pady\n\\-anchor\t\\-foreground\t\\-relief\n\\-background\t\\-highlightbackground\t\\-takefocus\n\\-bitmap\t\\-highlightcolor\t\\-text\n\\-borderwidth\t\\-highlightthickness\t\\-textvariable\n\\-cursor\t\\-image\t\\-underline\n\\-compound\t\\-justify\t\\-wraplength\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-direction direction Direction\nSpecifies where the menu is going to be popup up. \\fBabove\\fR tries to\npop the menu above the menubutton. \\fBbelow\\fR tries to pop the menu\nbelow the menubutton. \\fBleft\\fR tries to pop the menu to the left of\nthe menubutton. \\fBright\\fR tries to pop the menu to the right of the\nmenu button. \\fBflush\\fR pops the menu directly over the menubutton.\nIn the case of \\fBabove\\fR or \\fBbelow\\fR, the direction will be\nreversed if the menu would show offscreen.\n.OP \\-height height Height\nSpecifies a desired height for the menubutton.\nIf an image or bitmap is being displayed in the menubutton then the value is in\nscreen units (i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR);\nfor text it is in lines of text.\nIf this option is not specified, the menubutton's desired height is computed\nfrom the size of the image or bitmap or text being displayed in it.\n.OP \\-indicatoron indicatorOn IndicatorOn\nThe value must be a proper boolean value. If it is true then\na small indicator rectangle will be displayed on the right side\nof the menubutton and the default menu bindings will treat this\nas an option menubutton. If false then no indicator will be\ndisplayed.\n.OP \\-menu menu MenuName\nSpecifies the path name of the menu associated with this menubutton.\nThe menu must be a child of the menubutton.\n.OP \\-state state State\nSpecifies one of three states for the menubutton: \\fBnormal\\fR, \\fBactive\\fR,\nor \\fBdisabled\\fR. In normal state the menubutton is displayed using the\n\\fBforeground\\fR and \\fBbackground\\fR options. The active state is\ntypically used when the pointer is over the menubutton. In active state\nthe menubutton is displayed using the \\fB\\-activeforeground\\fR and\n\\fB\\-activebackground\\fR options. Disabled state means that the menubutton\nshould be insensitive: the default bindings will refuse to activate\nthe widget and will ignore mouse button presses.\nIn this state the \\fB\\-disabledforeground\\fR and\n\\fB\\-background\\fR options determine how the button is displayed.\n.OP \\-width width Width\nSpecifies a desired width for the menubutton.\nIf an image or bitmap is being displayed in the menubutton then the value is in\nscreen units (i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR);\nfor text it is in characters.\nIf this option is not specified, the menubutton's desired width is computed\nfrom the size of the image or bitmap or text being displayed in it.\n.BE\n.SH INTRODUCTION\n.PP\nThe \\fBmenubutton\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a menubutton widget.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the menubutton such as its colors, font,\ntext, and initial relief. The \\fBmenubutton\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nA menubutton is a widget that displays a textual string, bitmap, or image\nand is associated with a menu widget.\nIf text is displayed, it must all be in a single font, but it\ncan occupy multiple lines on the screen (if it contains newlines\nor if wrapping occurs because of the \\fB\\-wraplength\\fR option) and\none of the characters may optionally be underlined using the\n\\fB\\-underline\\fR option. In normal usage, pressing\nmouse button 1 over the menubutton causes the associated menu to\nbe posted just underneath the menubutton. If the mouse is moved over\nthe menu before releasing the mouse button, the button release\ncauses the underlying menu entry to be invoked. When the button\nis released, the menu is unposted.\n.PP\nMenubuttons are used to construct a \\fBtk_optionMenu\\fR, which is the\npreferred mechanism for allowing a user to select one item from a list\non macOS.\n.PP\nMenubuttons were also typically organized into groups called menu bars\nthat allow scanning:\nif the mouse button is pressed over one menubutton (causing it\nto post its menu) and the mouse is moved over another menubutton\nin the same menu bar without releasing the mouse button, then the\nmenu of the first menubutton is unposted and the menu of the\nnew menubutton is posted instead.\n\\fIThis use is deprecated\\fR in favor of setting a \\fBmenu\\fR directly as a\nmenubar; see the \\fBtoplevel\\fR's \\fB\\-menu\\fR option for how to do that.\n.PP\nThere are several interactions between menubuttons and menus; see\nthe \\fBmenu\\fR manual entry for information on various menu configurations,\nsuch as pulldown menus and option menus.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBmenubutton\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for menubutton widgets:\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget \\fIoption\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBmenubutton\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBmenubutton\\fR\ncommand.\n.SH \"DEFAULT BINDINGS\"\n.PP\nTk automatically creates class bindings for menubuttons that give them\nthe following default behavior:\n.IP [1]\nA menubutton activates whenever the mouse passes over it and deactivates\nwhenever the mouse leaves it.\n.IP [2]\nPressing mouse button 1 over a menubutton posts the menubutton:\nits relief changes to raised and its associated menu is posted\nunder the menubutton. If the mouse is dragged down into the menu\nwith the button still down, and if the mouse button is then\nreleased over an entry in the menu, the menubutton is unposted\nand the menu entry is invoked.\n.IP [3]\nIf button 1 is pressed over a menubutton and then released over that\nmenubutton, the menubutton stays posted: you can still move the mouse\nover the menu and click button 1 on an entry to invoke it.\nOnce a menu entry has been invoked, the menubutton unposts itself.\n.IP [4]\nIf button 1 is pressed over a menubutton and then dragged over some\nother menubutton, the original menubutton unposts itself and the\nnew menubutton posts.\n.IP [5]\nIf button 1 is pressed over a menubutton and released outside\nany menubutton or menu, the menubutton unposts without invoking\nany menu entry.\n.IP [6]\nWhen a menubutton is posted, its associated menu claims the input\nfocus to allow keyboard traversal of the menu and its submenus.\nSee the \\fBmenu\\fR manual entry for details on these bindings.\n.IP [7]\nIf the \\fB\\-underline\\fR option has been specified for a menubutton\nthen keyboard traversal may be used to post the menubutton:\nAlt+\\fIx\\fR, where \\fIx\\fR is the underlined character (or its\nlower-case or upper-case equivalent), may be typed in any window\nunder the menubutton's toplevel to post the menubutton.\n.IP [8]\nThe F10 key may be typed in any window to post the first menubutton\nunder its toplevel window that is not disabled.\n.IP [9]\nIf a menubutton has the input focus, the space and return keys\npost the menubutton.\n.PP\nIf the menubutton's state is \\fBdisabled\\fR then none of the above\nactions occur: the menubutton is completely non-responsive.\n.PP\nThe behavior of menubuttons can be changed by defining new bindings for\nindividual widgets or by redefining the class bindings.\n.SH \"SEE ALSO\"\nttk::menubutton(n), menu(n)\n.SH KEYWORDS\nmenubutton, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/message.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH message n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nmessage \\- Create and manipulate 'message' non-interactive text widgets\n.SH SYNOPSIS\n\\fBmessage\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-anchor\t\\-background\t\\-borderwidth\n\\-cursor\t\\-font\t\\-foreground\n\\-highlightbackground\t\\-highlightcolor\t\\-highlightthickness\n\\-padx\t\\-pady\t\\-relief\n\\-takefocus\t\\-text\t\\-textvariable\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-aspect aspect Aspect\nSpecifies a non-negative integer value indicating desired\naspect ratio for the text. The aspect ratio is specified as\n100*width/height. 100 means the text should\nbe as wide as it is tall, 200 means the text should\nbe twice as wide as it is tall, 50 means the text should\nbe twice as tall as it is wide, and so on.\nUsed to choose line length for text if \\fB\\-width\\fR option\nis not specified.\nDefaults to 150.\n.OP \\-justify justify Justify\nSpecifies how to justify lines of text.\nMust be one of \\fBleft\\fR, \\fBcenter\\fR, or \\fBright\\fR. Defaults\nto \\fBleft\\fR.\nThis option works together with the \\fB\\-anchor\\fR, \\fB\\-aspect\\fR,\n\\fB\\-padx\\fR, \\fB\\-pady\\fR, and \\fB\\-width\\fR options to provide a variety\nof arrangements of the text within the window.\nThe \\fB\\-aspect\\fR and \\fB\\-width\\fR options determine the amount of\nscreen space needed to display the text.\nThe \\fB\\-anchor\\fR, \\fB\\-padx\\fR, and \\fB\\-pady\\fR options determine where this\nrectangular area is displayed within the widget's window, and the\n\\fB\\-justify\\fR option determines how each line is displayed within that\nrectangular region.\nFor example, suppose \\fB\\-anchor\\fR is \\fBe\\fR and \\fB\\-justify\\fR is\n\\fBleft\\fR, and that the message window is much larger than needed\nfor the text.\nThe text will be displayed so that the left edges of all the lines\nline up and the right edge of the longest line is \\fB\\-padx\\fR from\nthe right side of the window; the entire text block will be centered\nin the vertical span of the window.\n.OP \\-width width Width\nSpecifies the length of lines in the window.\nThe value may have any of the forms acceptable to \\fBTk_GetPixels\\fR.\nIf this option has a value greater than zero then the \\fB\\-aspect\\fR\noption is ignored and the \\fB\\-width\\fR option determines the line\nlength.\nIf this option value is negative or zero, then\nthe \\fB\\-aspect\\fR option determines the line length.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBmessage\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a message widget.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the message such as its colors, font,\ntext, and initial relief. The \\fBmessage\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nA message is a widget that displays a textual string. A message\nwidget has three special features that differentiate it from a\n\\fBlabel\\fR widget. First, it breaks up\nits string into lines in order to produce a given aspect ratio\nfor the window. The line breaks are chosen at word boundaries\nwherever possible (if not even a single word would fit on a\nline, then the word will be split across lines). Newline characters\nin the string will force line breaks; they can be used, for example,\nto leave blank lines in the display.\n.PP\nThe second feature of a message widget is justification. The text\nmay be displayed left-justified (each line starts at the left side of\nthe window), centered on a line-by-line basis, or right-justified\n(each line ends at the right side of the window).\n.PP\nThe third feature of a message widget is that it handles control\ncharacters and non-printing characters specially. Tab characters\nare replaced with enough blank space to line up on the next\n8-character boundary. Newlines cause line breaks. Other control\ncharacters (ASCII code less than 0x20) and characters not defined\nin the font are displayed as a four-character sequence \\fB\\ex\\fIhh\\fR where\n\\fIhh\\fR is the two-digit hexadecimal number corresponding to\nthe character. In the unusual case where the font does not contain\nall of the characters in\n.QW 0123456789abcdef\\ex\nthen control characters and undefined characters are not displayed at all.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBmessage\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for message widgets:\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget \\fIoption\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBmessage\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBmessage\\fR\ncommand.\n.SH \"DEFAULT BINDINGS\"\n.PP\nWhen a new message is created, it has no default event bindings:\nmessages are intended for output purposes only.\n.SH BUGS\n.PP\nTabs do not work very well with text that is centered or right-justified.\nThe most common result is that the line is justified wrong.\n.SH \"SEE ALSO\"\nlabel(n)\n.SH KEYWORDS\nmessage, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/messageBox.n", "content": "'\\\"\n'\\\" Copyright (c) 1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk_messageBox n 4.2 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk_messageBox \\- pops up a message window and waits for user response.\n.SH SYNOPSIS\n\\fBtk_messageBox \\fR?\\fIoption value ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThis procedure creates and displays a message window with an\napplication-specified message, an icon and a set of buttons. Each of\nthe buttons in the message window is identified by a unique symbolic\nname (see the \\fB\\-type\\fR options). After the message window is\npopped up, \\fBtk_messageBox\\fR waits for the user to select one of the\nbuttons. Then it returns the symbolic name of the selected button.\n.PP\nThe following option-value pairs are supported:\n.\\\" OPTION: -command\n.TP\n\\fB\\-command\\fI string\\fR\n.\nSpecifies the prefix of a Tcl command to invoke when the user closes the\ndialog. The actual command consists of \\fIstring\\fR followed by a space\nand the name of the button clicked by the user to close the dialog. This\nis only available on macOS.\n.\\\" OPTION: -default\n.TP\n\\fB\\-default\\fI name\\fR\n.\n\\fIName\\fR gives the symbolic name of the default button for\nthis message window (\n.QW ok ,\n.QW cancel ,\nand so on). See \\fB\\-type\\fR\nfor a list of the symbolic names. If this option is not specified,\nthe first button in the dialog will be made the default.\n.\\\" OPTION: -detail\n.TP\n\\fB\\-detail\\fI string\\fR\n.\nSpecifies an auxiliary message to the main message given by the\n\\fB\\-message\\fR option. The message detail will be presented beneath the main\nmessage and, where supported by the OS, in a less emphasized font than the\nmain message.\n.\\\" OPTION: -icon\n.TP\n\\fB\\-icon\\fI iconImage\\fR\n.\nSpecifies an icon to display. \\fIIconImage\\fR must be one of the\nfollowing: \\fBerror\\fR, \\fBinfo\\fR, \\fBquestion\\fR or\n\\fBwarning\\fR. If this option is not specified, then the info icon will be\ndisplayed.\n.\\\" OPTION: -message\n.TP\n\\fB\\-message\\fI string\\fR\n.\nSpecifies the message to display in this message box. The\ndefault value is an empty string.\n.\\\" OPTION: -parent\n.TP\n\\fB\\-parent\\fI window\\fR\n.\nMakes \\fIwindow\\fR the logical parent of the message box. The message\nbox is displayed on top of its parent window.\n.\\\" OPTION: -title\n.TP\n\\fB\\-title\\fI titleString\\fR\n.\nSpecifies a string to display as the title of the message box. The\ndefault value is an empty string.\n.\\\" OPTION: -type\n.TP\n\\fB\\-type\\fI predefinedType\\fR\n.\nArranges for a predefined set of buttons to be displayed. The\nfollowing values are possible for \\fIpredefinedType\\fR:\n.RS\n.IP \\fBabortretryignore\\fR 18\nDisplays three buttons whose symbolic names are \\fBabort\\fR,\n\\fBretry\\fR and \\fBignore\\fR.\n.IP \\fBok\\fR 18\nDisplays one button whose symbolic name is \\fBok\\fR. This is the default.\n.IP \\fBokcancel\\fR 18\nDisplays two buttons whose symbolic names are \\fBok\\fR and \\fBcancel\\fR.\n.IP \\fBretrycancel\\fR 18\nDisplays two buttons whose symbolic names are \\fBretry\\fR and \\fBcancel\\fR.\n.IP \\fByesno\\fR 18\nDisplays two buttons whose symbolic names are \\fByes\\fR and \\fBno\\fR.\n.IP \\fByesnocancel\\fR 18\nDisplays three buttons whose symbolic names are \\fByes\\fR, \\fBno\\fR\nand \\fBcancel\\fR.\n.RE\n.PP\n.SH EXAMPLE\n.PP\n.CS\nset answer [\\fBtk_messageBox\\fR -message \"Really quit?\" \\e\n -icon question -type yesno \\e\n -detail \"Select \\e\"Yes\\e\" to make the application exit\"]\nswitch -- $answer {\n yes exit\n no {\\fBtk_messageBox\\fR -message \"I know you like this application!\" \\e\n -type ok}\n}\n.CE\n.SH KEYWORDS\nmessage box\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/nsimage.n", "content": "'\\\"\n'\\\" Copyright (c) 2022 Marc Culler\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH nsimage n 9.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nnsimage \\- A Tk image type for macOS based on the NSImage class.\n.BE\n.SH DESCRIPTION\nThe nsimage is implemented as a Tk image type. The \\fBimage\\fR\ncommand is used to create, delete, and query all images, including\nimages of type \\fBnsimage\\fR. The options that are available are\nspecific to the nsimage type and are described below.\n.PP\nThe command to create an \\fBnsimage\\fR:\n.TP\n\\fBimage create nsimage \\fR?\\fIname\\fR? ?\\fIoption value ...\\fR?\n.PP\ncreates a new nsimage and a command with the same name and returns its\nname.\n.SH OPTIONS\n.PP\nValid \\fIoptions\\fR are:\n.\\\" OPTION: -source\n.TP\n\\fB\\-source\\fI string\\fR\n.PP\nThe value of the \\fB\\-source\\fR option is a string describing an\nNSimage. There are several ways to interpret this string, and the\ninterpretation is determined by the value of the \\fB\\-as\\fR option.\nThis option is required.\n.PP\n.\\\" OPTION: -as\n.TP\n\\fB\\-as\\fI type\\fR\n.PP\nThere are four possible values for the \\fB\\-as\\fR option which specify\nhow the source string should be interpreted. The allowed values and\ntheir meanings are:\n.RS\n.IP \\fBname\\fR\nThe source should be interpreted as the name of a named NSImage\nprovided by the system.\nThis is the default if the \\fB\\-as\\fR option is not specified.\n.IP \\fBfile\\fR\nThe source should be interpreted as a path to an image\nfile in one of the formats understood by the NSImage class.\n.IP \\fBpath\\fR\nThe source should be interpreted as a path to an arbitrary\nfile. The type of the file will be examined and the resulting image\nwill be the system icon for files of that type.\n.IP \\fBfiletype\\fR\nThe source is interpreted as a string identifying a\nparticular file type. It may be a filename extension, an Apple Uniform Type\nIdentifier or a 4-character OSType value as used in the HFS filesystem.\n.RE\n.\\\" OPTION: -width\n.TP\n\\fB\\-width\\fI pixels\\fR\n.PP\nThe value of the \\fIwidth\\fR option is an integer specifying the width\nin pixels of the nsimage. If the width is not specified it will be\ncomputed from the height so as to preserve the aspect ration. If\nneither width nor height are specified then the width and height of\nthe underlying NSImage will be used.\n.\\\" OPTION: -height\n.TP\n\\fB\\-height\\fI pixels\\fR\n.PP\nThe value of the \\fIheight\\fR option is an integer specifying the\nheight in pixels of the nsimage. If the height is not specified it\nwill be computed from the height so as to preserve the aspect ration.\nIf neither width nor height are specified then the width and height of\nthe underlying NSImage will be used.\n.\\\" OPTION: -radius\n.TP\n\\fB\\-radius\\fI pixels\\fR\n.PP\nThe value of the \\fIradius\\fR option is an integer. If non-zero the\nimage will be clipped to a rounded rectangle with the same width and\nheight as the image, but with circular arcs of the specified radius\ncutting off the corners of the rectangle.\n.\\\" OPTION: -ring\n.TP\n\\fB\\-ring\\fI pixels\\fR\n.PP\nThe value of the \\fIring\\fR option is an integer. If non-zero then it\nspecifies the thickness of a focus ring which will be drawn around the\nimage using the control accent color specified in the System\nPreferences. The image is resized to reduce its width and height by\ntwice the thickness of the ring. Note that this may create a small\namount of distortion. The aspect ration of a non-square image will\nchange slightly.\n.\\\" OPTION: -alpha\n.TP\n\\fB\\-alpha\\fI float\\fR\n.PP\nThe value of the \\fIalpha\\fR option should be a floating point number\nbetween 0.0 and 1.0. This alpha value will be applied to each pixel\nof the nsimage, producing a partially transparent image. The default value\nis 1.0, which makes the image opaque.\n.\\\" OPTION: -pressed\n.TP\n\\fB\\-pressed\\fI boolean\\fR\n.PP\nThe \\fIpressed\\fR option takes a boolean value. If the value is true\nor 1 then the image will be algorithmically modified to become darker\nin light mode or lighter in dark mode. The default is false. For an\nimage button, the primary image should use the value false while the\npressed image should be the same image but with the \\fIpressed\\fR\noption set to true.\n.\\\" OPTION: -template\n.TP\n\\fB\\-template\\fI boolean\\fR\n.PP\nThe \\fItemplate\\fR option takes a boolean value. If the value is true\nor 1 then the image will be marked as being a template image. This\nmeans that the system will algorithmically convert the image to a\nlight colored image when in dark mode. For the algorithm to work\ncorrectly the image must consist only of black pixels with alpha\nvalues.\n.SH \"SEE ALSO\"\nimage(n), options(n), photo(n)\n.SH KEYWORDS\nheight, image, types of images, width\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/option.n", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH option n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\noption \\- Add/retrieve window options to/from the option database\n.SH SYNOPSIS\n.nf\n\\fBoption add \\fIpattern value \\fR?\\fIpriority\\fR?\n\\fBoption clear\\fR\n\\fBoption get \\fIwindow name class\\fR\n\\fBoption readfile \\fIfileName \\fR?\\fIpriority\\fR?\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBoption\\fR command allows you to add entries to the Tk option\ndatabase or to retrieve options from the database.\n.\\\" METHOD: add\nThe \\fBadd\\fR form of the command adds a new option to the database.\n\\fIPattern\\fR contains\nthe option being specified, and consists of names and/or classes\nseparated by asterisks or dots, in the usual X format (see\n\\fBPATTERN FORMAT\\fR). \\fIValue\\fR\ncontains a text string to associate with \\fIpattern\\fR; this is the\nvalue that will be returned in calls to \\fBTk_GetOption\\fR or by\ninvocations of the \\fBoption get\\fR command. If \\fIpriority\\fR\nis specified, it indicates the priority level for this option (see\nbelow for legal values); it defaults to \\fBinteractive\\fR.\nThis command always returns an empty string.\n.PP\n.\\\" METHOD: clear\nThe \\fBoption clear\\fR command clears the option database. Default\noptions (from the\n\\fBRESOURCE_MANAGER\\fR property or the \\fB.Xdefaults\\fR\nfile) will be reloaded automatically the next time an\noption is added to the database or removed from it. This command\nalways returns an empty string.\n.PP\n.\\\" METHOD: get\nThe \\fBoption get\\fR command returns the value of the option\nspecified for \\fIwindow\\fR\nunder \\fIname\\fR and \\fIclass\\fR. If several entries in the option\ndatabase match \\fIwindow\\fR, \\fIname\\fR, and \\fIclass\\fR, then\nthe command returns whichever was created with highest\n\\fIpriority\\fR level. If there are several matching\nentries at the same priority level, then it returns whichever entry\nwas most recently entered into the option database. If there are\nno matching entries, then the empty string is returned.\n.PP\n.\\\" METHOD: readfile\nThe \\fBreadfile\\fR form of the command reads \\fIfileName\\fR,\nwhich should have the standard format for an\nX resource database such as \\fB.Xdefaults\\fR, and adds all the\noptions specified in that file to the option database. If \\fIpriority\\fR\nis specified, it indicates the priority level at which to enter the\noptions; \\fIpriority\\fR defaults to \\fBinteractive\\fR.\n.PP\nThe file is read through a channel which is in \"utf-8\" encoding,\ninvalid byte sequences are automatically converted to valid ones.\nThis means that encodings like ISO 8859-1 or cp1252 with high\nprobability will work as well, but this cannot be guaranteed.\nThis cannot be changed, setting the [encoding system] has no effect.\n.PP\nThe \\fIpriority\\fR arguments to the \\fBoption\\fR command are\nnormally specified symbolically using one of the following values:\n.IP \\fBwidgetDefault\\fR\nLevel 20. Used for default values hard-coded into widgets.\n.IP \\fBstartupFile\\fR\nLevel 40. Used for options specified in application-specific\nstartup files.\n.IP \\fBuserDefault\\fR\nLevel 60. Used for options specified in user-specific defaults\nfiles, such as \\fB.Xdefaults\\fR, resource databases loaded into\nthe X server, or user-specific startup files.\n.IP \\fBinteractive\\fR\nLevel 80. Used for options specified interactively after the application\nstarts running. If \\fIpriority\\fR is not specified, it defaults to\nthis level.\n.PP\nAny of the above keywords may be abbreviated. In addition, priorities\nmay be specified numerically using integers between 0 and 100,\ninclusive. The numeric form is probably a bad idea except for new priority\nlevels other than the ones given above.\n.SH \"PATTERN FORMAT\"\n.PP\nPatterns consist of a sequence of words separated by either periods,\n.QW . ,\nor asterisks\n.QW * .\nThe overall pattern may also be optionally preceded by an asterisk.\n.PP\nEach word in the pattern conventionally starts with either an upper-case\nletter (in which case it denotes the class of either a widget or an option) or\nany other character, when it denotes the name of a widget or option. The last\nword in the pattern always indicates the option; the preceding ones constrain\nwhich widgets that option will be looked for in.\n.PP\nWhen two words are separated by a period, the latter widget must be a direct\nchild of the former (or the option must apply to only the indicated widgets).\nWhen two words are separated by an asterisk, any depth of widgets may lie\nbetween the former and latter widgets (and the option applies to all widgets\nthat are children of the former widget).\n.PP\nIf the overall pattern is preceded by an asterisk, then the overall pattern\napplies anywhere it can throughout the whole widget hierarchy. Otherwise the\nfirst word of the pattern is matched against the name and class of the\n.QW \\fB.\\fR\n\\fBtoplevel\\fR, which are usually set by options to \\fBwish\\fR.\n.SH EXAMPLES\n.PP\nInstruct every button in the application to have red text on it unless\nexplicitly overridden, by setting the \\fBforeground\\fR for the \\fBButton\\fR\nclass (note that on some platforms the option is ignored):\n.CS\n\\fBoption add\\fR *Button.foreground red startupFile\n.CE\n.PP\nAllow users to control what happens in an entry widget when the Return\nkey is pressed by specifying a script in the option database and add a\ndefault option for that which rings the bell:\n.CS\nentry .e\nbind .e [\\fBoption get\\fR .e returnCommand Command]\n\\fBoption add\\fR *.e.returnCommand bell widgetDefault\n.CE\n.SH \"SEE ALSO\"\noptions(n), wish(1)\n.SH KEYWORDS\ndatabase, option, priority, retrieve\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/optionMenu.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk_optionMenu n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk_optionMenu \\- Create an option menubutton and its menu\n.SH SYNOPSIS\n\\fBtk_optionMenu \\fIpathName varName value \\fR?\\fIvalue value ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThis procedure creates an option menubutton whose name is \\fIpathName\\fR,\nplus an associated menu.\nTogether they allow the user to select one of the values\ngiven by the \\fIvalue\\fR arguments.\nThe current value will be stored in the global variable whose\nname is given by \\fIvarName\\fR and it will also be displayed as the label\nin the option menubutton.\nThe user can click on the menubutton to display a menu containing\nall of the \\fIvalue\\fRs and thereby select a new value.\nOnce a new value is selected, it will be stored in the variable\nand appear in the option menubutton.\nThe current value can also be changed by setting the variable.\n.PP\nThe return value from \\fBtk_optionMenu\\fR is the name of the menu\nassociated with \\fIpathName\\fR, so that the caller can change its\nconfiguration options or manipulate it in other ways.\n.SH EXAMPLE\n.PP\n.CS\ntk_optionMenu .foo myVar Foo Bar Boo Spong Wibble\npack .foo\n.CE\n.SH KEYWORDS\noption menu\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/options.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH options n 4.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\noptions \\- Standard options supported by widgets\n.BE\n.SH DESCRIPTION\n.PP\nThis manual entry describes the common configuration options supported\nby widgets in the Tk toolkit. Every widget does not necessarily support\nevery option (see the manual entries for individual widgets for a list\nof the standard options supported by that widget), but if a widget does\nsupport an option with one of the names listed below, then the option\nhas exactly the effect described below.\n.PP\nIn the descriptions below,\n.QW \"Command-Line Name\"\nrefers to the\nswitch used in class commands and \\fBconfigure\\fR widget commands to\nset this value. For example, if an option's command-line switch is\n\\fB\\-foreground\\fR and there exists a widget \\fB.a.b.c\\fR, then the\ncommand\n.CS\n\\&\\fB.a.b.c\\0\\0configure\\0\\0\\-foreground black\\fR\n.CE\nmay be used to specify the value \\fBblack\\fR for the option in\nthe widget \\fB.a.b.c\\fR. Command-line switches may be abbreviated,\nas long as the abbreviation is unambiguous.\n.QW \"Database Name\"\nrefers to the option's name in the option database (e.g. in .Xdefaults files).\n.QW \"Database Class\"\nrefers to the option's class value in the option database.\n.OP \\-activebackground activeBackground Foreground\nSpecifies background color to use when drawing active elements.\nAn element (a widget or portion of a widget) is active if the\nmouse cursor is positioned over the element and pressing a mouse button\nwill cause some action to occur.\nIf strict Motif compliance has been requested by setting the\n\\fBtk_strictMotif\\fR variable, this option will normally be\nignored; the normal background color will be used instead.\nFor some elements on Windows and Macintosh systems, the active color\nwill only be used while mouse button 1 is pressed over the element.\n.OP \\-activeborderwidth activeBorderWidth BorderWidth\nSpecifies a non-negative value indicating\nthe width of the 3-D border drawn around active elements. See above for\ndefinition of active elements.\nThe value may have any of the forms acceptable to \\fBTk_GetPixels\\fR.\nThis option is typically only available in widgets displaying more\nthan one element at a time (e.g. menus but not buttons).\n.OP \\-activeforeground activeForeground Background\nSpecifies foreground color to use when drawing active elements.\nSee above for definition of active elements.\n.OP \\-activerelief activeRelief Relief\nSpecifies the 3-D effect desired for the active item of the widget.\nSee the \\fB\\-relief\\fR option for details.\n.OP \\-anchor anchor Anchor\nSpecifies how the information in a widget (e.g. text or a bitmap)\nis to be displayed in the widget.\nMust be one of the values \\fBn\\fR, \\fBne\\fR, \\fBe\\fR, \\fBse\\fR,\n\\fBs\\fR, \\fBsw\\fR, \\fBw\\fR, \\fBnw\\fR, or \\fBcenter\\fR.\nFor example, \\fBnw\\fR means display the information such that its\ntop-left corner is at the top-left corner of the widget.\n.OP \"\\-background or \\-bg\" background Background\nSpecifies the normal background color to use when displaying the\nwidget.\n.OP \\-bitmap bitmap Bitmap\nSpecifies a bitmap to display in the widget, in any of the forms\nacceptable to \\fBTk_GetBitmap\\fR.\nThe exact way in which the bitmap is displayed may be affected by\nother options such as \\fB\\-anchor\\fR or \\fB\\-justify\\fR.\nTypically, if this option is specified then it overrides other\noptions that specify a textual value to display in the widget\nbut this is controlled by the \\fB\\-compound\\fR option;\nthe \\fB\\-bitmap\\fR option may be reset to an empty string to re-enable\na text display.\nIn widgets that support both \\fB\\-bitmap\\fR and \\fB\\-image\\fR options,\n\\fB\\-image\\fR will usually override \\fB\\-bitmap\\fR.\n.OP \"\\-borderwidth or \\-bd\" borderWidth BorderWidth\nSpecifies a non-negative value indicating the width\nof the 3-D border to draw around the outside of the widget (if such a\nborder is being drawn; the \\fB\\-relief\\fR option typically determines\nthis). The value may also be used when drawing 3-D effects in the\ninterior of the widget.\nThe value may have any of the forms acceptable to \\fBTk_GetPixels\\fR.\n.OP \\-cursor cursor Cursor\nSpecifies the mouse cursor to be used for the widget.\nThe value may have any of the forms acceptable to \\fBTk_GetCursor\\fR.\nIn addition, if an empty string is specified, it indicates that the\nwidget should defer to its parent for cursor specification.\n.OP \\-compound compound Compound\nSpecifies if the widget should display text and bitmaps/images at the\nsame time, and if so, where the bitmap/image should be placed relative\nto the text. Must be one of the values \\fBnone\\fR, \\fBbottom\\fR,\n\\fBtop\\fR, \\fBleft\\fR, \\fBright\\fR, or \\fBcenter\\fR. For example, the\n(default) value \\fBnone\\fR specifies that the bitmap or image should\n(if defined) be displayed instead of the text, the value \\fBleft\\fR\nspecifies that the bitmap or image should be displayed to the left of\nthe text, and the value \\fBcenter\\fR specifies that the bitmap or\nimage should be displayed on top of the text.\n.OP \\-disabledforeground disabledForeground DisabledForeground\nSpecifies foreground color to use when drawing a disabled element.\nIf the option is specified as an empty string (which is typically the\ncase on monochrome displays), disabled elements are drawn with the\nnormal foreground color but they are dimmed by drawing them\nwith a stippled fill pattern.\n.OP \\-exportselection exportSelection ExportSelection\nSpecifies whether or not a selection in the widget should also be\nthe X selection.\nThe value may have any of the forms accepted by \\fBTcl_GetBoolean\\fR,\nsuch as \\fBtrue\\fR, \\fBfalse\\fR, \\fB0\\fR, \\fB1\\fR, \\fByes\\fR, or \\fBno\\fR.\nIf the selection is exported, then selecting in the widget deselects\nthe current X selection, selecting outside the widget deselects any\nwidget selection, and the widget will respond to selection retrieval\nrequests when it has a selection. The default is usually for widgets\nto export selections.\n.OP \\-font font Font\nSpecifies the font to use when drawing text inside the widget.\nThe value may have any of the forms described in the \\fBfont\\fR manual\npage under \\fBFONT DESCRIPTION\\fR.\n.OP \"\\-foreground or \\-fg\" foreground Foreground\nSpecifies the normal foreground color to use when displaying the widget.\n.OP \\-highlightbackground highlightBackground HighlightBackground\nSpecifies the color to display in the traversal highlight region when\nthe widget does not have the input focus.\n.OP \\-highlightcolor highlightColor HighlightColor\nSpecifies the color to use for the traversal highlight rectangle that is\ndrawn around the widget when it has the input focus.\n.OP \\-highlightthickness highlightThickness HighlightThickness\nSpecifies a non-negative value indicating the width of the highlight\nrectangle to draw around the outside of the widget when it has the\ninput focus.\nThe value may have any of the forms acceptable to \\fBTk_GetPixels\\fR.\nIf the value is zero, no focus highlight is drawn around the widget.\n.OP \\-image image Image\nSpecifies an image to display in the widget, which must have been\ncreated with the \\fBimage create\\fR command.\nTypically, if the \\fB\\-image\\fR option is specified then it overrides other\noptions that specify a bitmap or textual value to display in the\nwidget, though this is controlled by the \\fB\\-compound\\fR option;\nthe \\fB\\-image\\fR option may be reset to an empty string to re-enable\na bitmap or text display.\n.OP \\-insertbackground insertBackground Foreground\nSpecifies the color to use as background in the area covered by the\ninsertion cursor. This color will normally override either the normal\nbackground for the widget (or the selection background if the insertion\ncursor happens to fall in the selection).\n.OP \\-insertborderwidth insertBorderWidth BorderWidth\nSpecifies a non-negative value indicating the width\nof the 3-D border to draw around the insertion cursor.\nThe value may have any of the forms acceptable to \\fBTk_GetPixels\\fR.\n.OP \\-insertofftime insertOffTime OffTime\nSpecifies a non-negative integer value indicating the number of\nmilliseconds the insertion cursor should remain\n.QW off\nin each blink cycle.\nIf this option is zero then the cursor does not blink: it is on\nall the time.\n.OP \\-insertontime insertOnTime OnTime\nSpecifies a non-negative integer value indicating the number of\nmilliseconds the insertion cursor should remain\n.QW on\nin each blink cycle.\n.OP \\-insertwidth insertWidth InsertWidth\nSpecifies a non-negative value indicating the total width of the insertion cursor.\nThe value may have any of the forms acceptable to \\fBTk_GetPixels\\fR.\nIf a border has been specified for the insertion\ncursor (using the \\fB\\-insertborderwidth\\fR option), the border\nwill be drawn inside the width specified by the \\fB\\-insertwidth\\fR\noption.\n.OP \\-jump jump Jump\nFor widgets with a slider that can be dragged to adjust a value,\nsuch as scrollbars, this option determines when\nnotifications are made about changes in the value.\nThe option's value must be a boolean of the form accepted by\n\\fBTcl_GetBoolean\\fR.\nIf the value is false, updates are made continuously as the\nslider is dragged.\nIf the value is true, updates are delayed until the mouse button\nis released to end the drag; at that point a single notification\nis made (the value\n.QW jumps\nrather than changing smoothly).\n.OP \\-justify justify Justify\nWhen there are multiple lines of text displayed in a widget, this\noption determines how the lines line up with each other.\nMust be one of \\fBleft\\fR, \\fBcenter\\fR, or \\fBright\\fR.\n\\fBLeft\\fR means that the lines' left edges all line up, \\fBcenter\\fR\nmeans that the lines' centers are aligned, and \\fBright\\fR means\nthat the lines' right edges line up.\n.OP \\-orient orient Orient\nFor widgets that can lay themselves out with either a horizontal\nor vertical orientation, such as scrollbars, this option specifies\nwhich orientation should be used. Must be either \\fBhorizontal\\fR\nor \\fBvertical\\fR or an abbreviation of one of these.\n.OP \\-padx padX Pad\nSpecifies a non-negative value indicating how much extra space\nto request for the widget in the X-direction.\nThe value may have any of the forms acceptable to \\fBTk_GetPixels\\fR.\nWhen computing how large a window it needs, the widget will\nadd this amount to the width it would normally need (as determined\nby the width of the things displayed in the widget); if the geometry\nmanager can satisfy this request, the widget will end up with extra\ninternal space to the left and/or right of what it displays inside.\nMost widgets only use this option for padding text: if they are\ndisplaying a bitmap or image, then they usually ignore padding\noptions.\n.OP \\-pady padY Pad\nSpecifies a non-negative value indicating how much extra space\nto request for the widget in the Y-direction.\nThe value may have any of the forms acceptable to \\fBTk_GetPixels\\fR.\nWhen computing how large a window it needs, the widget will add\nthis amount to the height it would normally need (as determined by\nthe height of the things displayed in the widget); if the geometry\nmanager can satisfy this request, the widget will end up with extra\ninternal space above and/or below what it displays inside.\nMost widgets only use this option for padding text: if they are\ndisplaying a bitmap or image, then they usually ignore padding\noptions.\n.OP \\-placeholder placeHolder PlaceHolder\nSpecifies a help text string to display if no text is otherwise displayed,\nthat is when the widget is empty. The placeholder text is displayed using\nthe values of the \\fB\\-font\\fR and \\fB\\-justify\\fR options.\n.OP \\-placeholderforeground placeholderForeground PlaceholderForeground\nSpecifies the foreground color to use when the placeholder text is\ndisplayed. The default color is platform-specific.\n.OP \\-relief relief Relief\nSpecifies the 3-D effect desired for the widget. Acceptable\nvalues are \\fBraised\\fR, \\fBsunken\\fR, \\fBflat\\fR, \\fBridge\\fR,\n\\fBsolid\\fR, and \\fBgroove\\fR.\nThe value\nindicates how the interior of the widget should appear relative\nto its exterior; for example, \\fBraised\\fR means the interior of\nthe widget should appear to protrude from the screen, relative to\nthe exterior of the widget.\n.OP \\-repeatdelay repeatDelay RepeatDelay\nSpecifies the number of milliseconds a button or key must be held\ndown before it begins to auto-repeat. Used, for example, on the\nup- and down-arrows in scrollbars.\n.OP \\-repeatinterval repeatInterval RepeatInterval\nUsed in conjunction with \\fB\\-repeatdelay\\fR: once auto-repeat\nbegins, this option determines the number of milliseconds between\nauto-repeats.\n.OP \\-selectbackground selectBackground Foreground\nSpecifies the background color to use when displaying selected\nitems.\n.OP \\-selectborderwidth selectBorderWidth BorderWidth\nSpecifies a non-negative value indicating the width\nof the 3-D border to draw around selected items.\nThe value may have any of the forms acceptable to \\fBTk_GetPixels\\fR.\n.OP \\-selectforeground selectForeground Background\nSpecifies the foreground color to use when displaying selected\nitems.\n.OP \\-setgrid setGrid SetGrid\nSpecifies a boolean value that determines whether this widget controls the\nresizing grid for its top-level window.\nThis option is typically used in text widgets, where the information\nin the widget has a natural size (the size of a character) and it makes\nsense for the window's dimensions to be integral numbers of these units.\nThese natural window sizes form a grid.\nIf the \\fB\\-setgrid\\fR option is set to true then the widget will\ncommunicate with the window manager so that when the user interactively\nresizes the top-level window that contains the widget, the dimensions of\nthe window will be displayed to the user in grid units and the window\nsize will be constrained to integral numbers of grid units.\nSee the section \\fBGRIDDED GEOMETRY MANAGEMENT\\fR in the \\fBwm\\fR manual\nentry for more details.\n.OP \\-takefocus takeFocus TakeFocus\nDetermines whether the window accepts the focus during keyboard\ntraversal (e.g., Tab and Shift-Tab).\nBefore setting the focus to a window, the traversal scripts\nconsult the value of the \\fB\\-takefocus\\fR option.\nA value of \\fB0\\fR means that the window should be skipped entirely\nduring keyboard traversal.\n\\fB1\\fR means that the window should receive the input\nfocus as long as it is viewable (it and all of its ancestors are mapped).\nAn empty value for the option means that the traversal scripts make\nthe decision about whether or not to focus on the window: the current\nalgorithm is to skip the window if it is\ndisabled, if it has no key bindings, or if it is not viewable.\nIf the value has any other form, then the traversal scripts take\nthe value, append the name of the window to it (with a separator space),\nand evaluate the resulting string as a Tcl script.\nThe script must return \\fB0\\fR, \\fB1\\fR, or an empty string: a\n\\fB0\\fR or \\fB1\\fR value specifies whether the window will receive\nthe input focus, and an empty string results in the default decision\ndescribed above.\nNote that this interpretation of the option is defined entirely by\nthe Tcl scripts that implement traversal: the widget implementations\nignore the option entirely, so you can change its meaning if you\nredefine the keyboard traversal scripts.\n.OP \\-text text Text\nSpecifies a string to be displayed inside the widget. The way in which\nthe string is displayed depends on the particular widget and may be\ndetermined by other options, such as \\fB\\-anchor\\fR or \\fB\\-justify\\fR.\n.OP \\-textvariable textVariable Variable\nSpecifies the name of a global variable. The value of the variable is a text\nstring to be displayed inside the widget; if the variable value changes\nthen the widget will automatically update itself to reflect the new value.\nThe way in which the string is displayed in the widget depends on the\nparticular widget and may be determined by other options, such as\n\\fB\\-anchor\\fR or \\fB\\-justify\\fR.\n.OP \\-troughcolor troughColor Background\nSpecifies the color to use for the rectangular trough areas\nin widgets such as scrollbars and scales. This option is ignored for\nscrollbars on Windows (native widget does not recognize this option).\n.OP \\-underline underline Underline\nSpecifies the integer index of a character to underline in the widget.\nThis option is used by the default bindings to implement keyboard\ntraversal for menu buttons and menu entries.\n0 corresponds to the first character of the text displayed in the\nwidget, 1 to the next character, and so on. \\fBend\\fR corresponds to the\nlast character, \\fBend\\fR-1 to the before last character, and so on.\n.OP \\-wraplength wrapLength WrapLength\nFor widgets that can perform word-wrapping, this option specifies\nthe maximum line length.\nLines that would exceed this length are wrapped onto the next line,\nso that no line is longer than the specified length.\nThe value may be specified in any of the standard forms for\nscreen distances.\nIf this value is negative or zero then no wrapping is done: lines\nwill break only at newline characters in the text.\n.OP \\-xscrollcommand xScrollCommand ScrollCommand\nSpecifies the prefix for a command used to communicate with horizontal\nscrollbars.\nWhen the view in the widget's window changes (or\nwhenever anything else occurs that could change the display in a\nscrollbar, such as a change in the total size of the widget's\ncontents), the widget will\ngenerate a Tcl command by concatenating the scroll command and\ntwo numbers.\nEach of the numbers is a fraction between 0 and 1, which indicates\na position in the document. 0 indicates the beginning of the document,\n1 indicates the end, .333 indicates a position one third the way through\nthe document, and so on.\nThe first fraction indicates the first information in the document\nthat is visible in the window, and the second fraction indicates\nthe information just after the last portion that is visible.\nThe command is\nthen passed to the Tcl interpreter for execution. Typically the\n\\fB\\-xscrollcommand\\fR option consists of the path name of a scrollbar\nwidget followed by\n.QW set ,\ne.g.\n.QW \".x.scrollbar set\" :\nthis will cause\nthe scrollbar to be updated whenever the view in the window changes.\nIf this option is not specified, then no command will be executed.\n.OP \\-yscrollcommand yScrollCommand ScrollCommand\nSpecifies the prefix for a command used to communicate with vertical\nscrollbars. This option is treated in the same way as the\n\\fB\\-xscrollcommand\\fR option, except that it is used for vertical\nscrollbars and is provided by widgets that support vertical scrolling.\nSee the description of \\fB\\-xscrollcommand\\fR for details\non how this option is used.\n.SH \"SEE ALSO\"\ncolors, cursors, font\n.SH KEYWORDS\nclass, name, standard option, switch\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/pack.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH pack n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\npack \\- Geometry manager that packs around edges of cavity\n.SH SYNOPSIS\n\\fBpack \\fIoption arg \\fR?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBpack\\fR command is used to communicate with the packer,\na geometry manager that arranges the children of a parent by\npacking them in order around the edges of the parent.\nThe \\fBpack\\fR command can have any of several forms, depending\non the \\fIoption\\fR argument:\n.TP\n\\fBpack \\fIwindow \\fR?\\fIwindow ...\\fR? ?\\fIoptions\\fR?\n.\nIf the first argument to \\fBpack\\fR is a window name (any value\nstarting with\n.QW . ),\nthen the command is processed in the same way as \\fBpack configure\\fR.\n.\\\" METHOD: configure\n.TP\n\\fBpack configure \\fIwindow \\fR?\\fIwindow ...\\fR? ?\\fIoptions\\fR?\n.\nThe arguments consist of the names of one or more content windows\nfollowed by pairs of arguments that specify how\nto manage the content.\nSee \\fBTHE PACKER ALGORITHM\\fR below for details on how the options\nare used by the packer.\nThe following options are supported:\n.RS\n.\\\" OPTION: -after\n.TP\n\\fB\\-after \\fIother\\fR\n.\n\\fIOther\\fR must the name of another window.\nUse its container as the container for the content, and insert\nthe content just after \\fIother\\fR in the packing order.\n.\\\" OPTION: -anchor\n.TP\n\\fB\\-anchor \\fIanchor\\fR\n.\n\\fIAnchor\\fR must be a valid anchor position such as \\fBn\\fR\nor \\fBsw\\fR; it specifies where to position each content in its\nparcel.\nDefaults to \\fBcenter\\fR.\n.\\\" OPTION: -before\n.TP\n\\fB\\-before \\fIother\\fR\n.\n\\fIOther\\fR must the name of another window.\nUse its container as the container for the content, and insert\nthe content just before \\fIother\\fR in the packing order.\n.\\\" OPTION: -expand\n.TP\n\\fB\\-expand \\fIboolean\\fR\n.\nSpecifies whether the content should be expanded to consume\nextra space in their container.\n\\fIBoolean\\fR may have any proper boolean value, such as \\fB1\\fR\nor \\fBno\\fR.\nDefaults to 0.\n.\\\" OPTION: -fill\n.TP\n\\fB\\-fill \\fIstyle\\fR\n.\nIf a content's parcel is larger than its requested dimensions, this\noption may be used to stretch the content.\n\\fIStyle\\fR must have one of the following values:\n.RS\n.IP \\fBnone\\fR\nGive the content its requested dimensions plus any internal padding\nrequested with \\fB\\-ipadx\\fR or \\fB\\-ipady\\fR. This is the default.\n.IP \\fBx\\fR\nStretch the content horizontally to fill the entire width of its\nparcel (except leave external padding as specified by \\fB\\-padx\\fR).\n.IP \\fBy\\fR\nStretch the content vertically to fill the entire height of its\nparcel (except leave external padding as specified by \\fB\\-pady\\fR).\n.IP \\fBboth\\fR\nStretch the content both horizontally and vertically.\n.RE\n.\\\" OPTION: -in\n.TP\n\\fB\\-in \\fIcontainer\\fR\n.\nInsert the window at the end of the packing order for the container\nwindow given by \\fIcontainer\\fR.\n.\\\" OPTION: -ipadx\n.TP\n\\fB\\-ipadx \\fIamount\\fR\n.\n\\fIAmount\\fR specifies how much horizontal internal padding to\nleave on each side of the content.\n\\fIAmount\\fR must be a valid screen distance, such as \\fB2\\fR or \\fB.5c\\fR.\nIt defaults to 0.\n.\\\" OPTION: -ipady\n.TP\n\\fB\\-ipady \\fIamount\\fR\n.\n\\fIAmount\\fR specifies how much vertical internal padding to\nleave on each side of the content.\n\\fIAmount\\fR defaults to 0.\n.\\\" OPTION: -padx\n.TP\n\\fB\\-padx \\fIamount\\fR\n.\n\\fIAmount\\fR specifies how much horizontal external padding to\nleave on each side of the content. \\fIAmount\\fR may be a list\nof two values to specify padding for left and right separately.\n\\fIAmount\\fR defaults to 0.\n.\\\" OPTION: -pady\n.TP\n\\fB\\-pady \\fIamount\\fR\n.\n\\fIAmount\\fR specifies how much vertical external padding to\nleave on each side of the content. \\fIAmount\\fR may be a list\nof two values to specify padding for top and bottom separately.\n\\fIAmount\\fR defaults to 0.\n.\\\" OPTION: -side\n.TP\n\\fB\\-side \\fIside\\fR\n.\nSpecifies which side of the container the content will be packed against.\nMust be \\fBleft\\fR, \\fBright\\fR, \\fBtop\\fR, or \\fBbottom\\fR.\nDefaults to \\fBtop\\fR.\n.LP\nIf no \\fB\\-in\\fR, \\fB\\-after\\fR or \\fB\\-before\\fR option is specified\nthen each of the content will be inserted at the end of the packing list\nfor its parent unless it is already managed by the packer (in which\ncase it will be left where it is).\nIf one of these options is specified then all the content will be\ninserted at the specified point.\nIf any of the content are already managed by the geometry manager\nthen any unspecified options for them retain their previous values rather\nthan receiving default values.\n.RE\n.\\\" METHOD: content\n.TP\n\\fBpack content \\fIwindow\\fR\n.\nReturns a list of all of the content windows in the packing order for\n\\fIwindow\\fR. The order of the content windows in the list is the same as\ntheir order in the packing order.\nIf \\fIwindow\\fR has no content then an empty string is returned.\n.\\\" METHOD: forget\n.TP\n\\fBpack forget \\fIwindow \\fR?\\fIwindow ...\\fR?\n.\nRemoves each of the \\fIwindow\\fRs from the packing order for its\ncontainer and unmaps their windows.\nThe content will no longer be managed by the packer.\n.RS\n.PP\n.VS \"TIP 518\"\nIf the last content window of the container becomes unmanaged, this will\nalso send the virtual event \\fB<>\\fR to the container; the\ncontainer may choose to resize itself (or otherwise respond) to such a change.\n.VE \"TIP 518\"\n.RE\n.\\\" METHOD: info\n.TP\n\\fBpack info \\fIwindow\\fR\n.\nReturns a list whose elements are the current configuration state of\nthe window given by \\fIwindow\\fR in the same option-value form that\nmight be specified to \\fBpack configure\\fR.\nThe first two elements of the list are\n.QW \"\\fB\\-in \\fIcontainer\\fR\"\nwhere \\fIcontainer\\fR is the window's container.\n.\\\" METHOD: propagate\n.TP\n\\fBpack propagate \\fIcontainer\\fR ?\\fIboolean\\fR?\n.\nIf \\fIboolean\\fR has a true boolean value such as \\fB1\\fR or \\fBon\\fR\nthen propagation is enabled for \\fIcontainer\\fR, which must be a window\nname (see \\fBGEOMETRY PROPAGATION\\fR below).\nIf \\fIboolean\\fR has a false boolean value then propagation is\ndisabled for \\fIcontainer\\fR.\nIn either of these cases an empty string is returned.\nIf \\fIboolean\\fR is omitted then the command returns \\fB0\\fR or\n\\fB1\\fR to indicate whether propagation is currently enabled\nfor \\fIcontainer\\fR.\nPropagation is enabled by default.\n.\\\" METHOD: slaves\n.TP\n\\fBpack slaves \\fIwindow\\fR\n.\nSynonym for \\fBpack content \\fIwindow\\fR.\n.SH \"THE PACKER ALGORITHM\"\n.PP\nFor each container the packer maintains an ordered list of content\nwindows called the \\fIpacking list\\fR.\nThe \\fB\\-in\\fR, \\fB\\-after\\fR, and \\fB\\-before\\fR configuration\noptions are used to specify the container for each content and the content's\nposition in the packing list.\nIf none of these options is given for a content then the content\nis added to the end of the packing list for its parent.\n.PP\nThe packer arranges the content windows for a container by scanning the\npacking list in order.\nAt the time it processes each content, a rectangular area within\nthe container is still unallocated.\nThis area is called the \\fIcavity\\fR; for the first content it\nis the entire area of the container.\n.PP\nFor each content the packer carries out the following steps:\n.IP [1]\nThe packer allocates a rectangular \\fIparcel\\fR for the content\nalong the side of the cavity given by the content's \\fB\\-side\\fR option.\nIf the side is top or bottom then the width of the parcel is\nthe width of the cavity and its height is the requested height\nof the content plus the \\fB\\-ipady\\fR and \\fB\\-pady\\fR options.\nFor the left or right side the height of the parcel is\nthe height of the cavity and the width is the requested width\nof the content plus the \\fB\\-ipadx\\fR and \\fB\\-padx\\fR options.\nThe parcel may be enlarged further because of the \\fB\\-expand\\fR\noption (see \\fBEXPANSION\\fR below)\n.IP [2]\nThe packer chooses the dimensions of the content.\nThe width will normally be the content's requested width plus\ntwice its \\fB\\-ipadx\\fR option and the height will normally be\nthe content's requested height plus twice its \\fB\\-ipady\\fR\noption.\nHowever, if the \\fB\\-fill\\fR option is \\fBx\\fR or \\fBboth\\fR\nthen the width of the content is expanded to fill the width of the parcel,\nminus twice the \\fB\\-padx\\fR option.\nIf the \\fB\\-fill\\fR option is \\fBy\\fR or \\fBboth\\fR\nthen the height of the content is expanded to fill the height of the parcel,\nminus twice the \\fB\\-pady\\fR option.\n.IP [3]\nThe packer positions the content over its parcel.\nIf the content is smaller than the parcel then the \\fB\\-anchor\\fR\noption determines where in the parcel the content will be placed.\nIf \\fB\\-padx\\fR or \\fB\\-pady\\fR is non-zero, then the given\namount of external padding will always be left between the\ncontent and the edges of the parcel.\n.PP\nOnce a given content has been packed, the area of its parcel\nis subtracted from the cavity, leaving a smaller rectangular\ncavity for the next content.\nIf a content does not use all of its parcel, the unused space\nin the parcel will not be used by subsequent content.\nIf the cavity should become too small to meet the needs of\na content then the content will be given whatever space is\nleft in the cavity.\nIf the cavity shrinks to zero size, then all remaining content\non the packing list will be unmapped from the screen until\nthe container window becomes large enough to hold them again.\n.SS \"EXPANSION\"\n.PP\nIf a container window is so large that there will be extra space\nleft over after all of its content have been packed, then the\nextra space is distributed uniformly among all of the content\nfor which the \\fB\\-expand\\fR option is set.\nExtra horizontal space is distributed among the expandable\ncontent whose \\fB\\-side\\fR is \\fBleft\\fR or \\fBright\\fR,\nand extra vertical space is distributed among the expandable\ncontent whose \\fB\\-side\\fR is \\fBtop\\fR or \\fBbottom\\fR.\n.SS \"GEOMETRY PROPAGATION\"\n.PP\nThe packer normally computes how large a container must be to\njust exactly meet the needs of its content, and it sets the\nrequested width and height of the container to these dimensions.\nThis causes geometry information to propagate up through a\nwindow hierarchy to a top-level window so that the entire\nsub-tree sizes itself to fit the needs of the leaf windows.\nHowever, the \\fBpack propagate\\fR command may be used to\nturn off propagation for one or more containers.\nIf propagation is disabled then the packer will not set\nthe requested width and height of the packer.\nThis may be useful if, for example, you wish for a container\nwindow to have a fixed size that you specify.\n.SH \"RESTRICTIONS ON CONTAINER WINDOWS\"\n.PP\nThe container for each content must either be the content's parent\n(the default) or a descendant of the content's parent.\nThis restriction is necessary to guarantee that the\ncontent can be placed over any part of its container that is\nvisible without danger of the content being clipped by its parent.\n.SH \"PACKING ORDER\"\n.PP\nIf the container for a content is not its parent then you must make sure\nthat the content is higher in the stacking order than the container.\nOtherwise the container will obscure the content and it will appear as\nif the content has not been packed correctly.\nThe easiest way to make sure the content is higher than the container is\nto create the container window first: the most recently created window\nwill be highest in the stacking order.\nOr, you can use the \\fBraise\\fR and \\fBlower\\fR commands to change\nthe stacking order of either the container or the content.\n.SH EXAMPLE\n.PP\n.CS\n# Make the widgets\nlabel .t -text \"This widget is at the top\" -bg red\nlabel .b -text \"This widget is at the bottom\" -bg green\nlabel .l -text \"Left\\enHand\\enSide\"\nlabel .r -text \"Right\\enHand\\enSide\"\ntext .mid\n\\&.mid insert end \"This layout is like Java's BorderLayout\"\n# Lay them out\n\\fBpack\\fR .t -side top -fill x\n\\fBpack\\fR .b -side bottom -fill x\n\\fBpack\\fR .l -side left -fill y\n\\fBpack\\fR .r -side right -fill y\n\\fBpack\\fR .mid -expand 1 -fill both\n.CE\n.SH \"SEE ALSO\"\ngrid(n), place(n)\n.SH KEYWORDS\ngeometry manager, location, packer, parcel, propagation, size\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/palette.n", "content": "'\\\"\n'\\\" Copyright (c) 1995-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk_setPalette n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk_setPalette, tk_bisque \\- Modify the Tk color palette\n.SH SYNOPSIS\n.nf\n\\fBtk_setPalette \\fIbackground\\fR\n\\fBtk_setPalette \\fIname value \\fR?\\fIname value ...\\fR?\n\\fBtk_bisque\\fR\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBtk_setPalette\\fR procedure changes the color scheme for Tk.\nIt does this by modifying the colors of existing widgets and by changing\nthe option database so that future widgets will use the new color scheme.\nIf \\fBtk_setPalette\\fR is invoked with a single argument, the\nargument is the name of a color to use as the normal background\ncolor; \\fBtk_setPalette\\fR will compute a complete color palette\nfrom this background color.\nAlternatively, the arguments to \\fBtk_setPalette\\fR may consist of any number\nof \\fIname\\fR\\-\\fIvalue\\fR pairs, where the first argument of the pair\nis the name of an option in the Tk option database and the second\nargument is the new value to use for that option. The following\ndatabase names are currently supported:\n.DS\n.ta 4c 8c\n\\fBactiveBackground\\fR\t\\fBforeground\\fR\t\\fBselectColor\\fR\n\\fBactiveForeground\\fR\t\\fBhighlightBackground\\fR\t\\fBselectBackground\\fR\n\\fBbackground\\fR\t\\fBhighlightColor\\fR\t\\fBselectForeground\\fR\n\\fBdisabledForeground\\fR\t\\fBinsertBackground\\fR\t\\fBtroughColor\\fR\n.DE\n\\fBtk_setPalette\\fR tries to compute reasonable defaults for any\noptions that you do not specify. You can specify options other\nthan the above ones and Tk will change those options on widgets as\nwell. This feature may be useful if you are using custom widgets with\nadditional color options.\n.PP\nOnce it has computed the new value to use for each of the color options,\n\\fBtk_setPalette\\fR scans the widget hierarchy to modify the options\nof all existing widgets. For each widget, it checks to see if any\nof the above options is defined for the widget. If so, and if the\noption's current value is the default, then the value is changed; if\nthe option has a value other than the default, \\fBtk_setPalette\\fR\nwill not change it. The default for an option is the one provided by\nthe widget (\\fB[lindex [$w configure $option] 3]\\fR) unless\n\\fBtk_setPalette\\fR has been run previously, in which case it is the\nvalue specified in the previous invocation of \\fBtk_setPalette\\fR.\n.PP\nAfter modifying all the widgets in the application, \\fBtk_setPalette\\fR\nadds options to the option database to change the defaults for\nwidgets created in the future. The new options are added at\npriority \\fBwidgetDefault\\fR, so they will be overridden by options\nfrom the .Xdefaults file or options specified on the command-line\nthat creates a widget.\n.PP\nThe procedure \\fBtk_bisque\\fR is provided for backward compatibility:\nit restores the application's colors to the light brown\n.PQ bisque\ncolor scheme used in Tk 3.6 and earlier versions.\n.SH KEYWORDS\nbisque, color, palette\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/panedwindow.n", "content": "'\\\"\n'\\\" Copyright (c) 1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH panedwindow n 8.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\npanedwindow \\- Create and manipulate 'panedwindow' split container widgets\n.SH SYNOPSIS\n\\fBpanedwindow\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-background\t\\-borderwidth\t\\-cursor\n\\-orient\t\\-relief\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-handlepad handlePad HandlePad\nWhen sash handles are drawn, specifies the distance from the top or\nleft end of the sash (depending on the orientation of the widget) at\nwhich to draw the handle. May be any value accepted by \\fBTk_GetPixels\\fR.\n.OP \\-handlesize handleSize HandleSize\nSpecifies the side length of a sash handle. Handles are always\ndrawn as squares. May be any value accepted by \\fBTk_GetPixels\\fR.\n.OP \\-height height Height\nSpecifies a desired height for the overall panedwindow widget. May be any\nvalue accepted by \\fBTk_GetPixels\\fR. If an empty string, the widget will be\nmade high enough to allow all contained widgets to have their natural height.\n.OP \\-opaqueresize opaqueResize OpaqueResize\nSpecifies whether panes should be resized as a sash is moved (true),\nor if resizing should be deferred until the sash is placed (false).\nIn the latter case, a\n.QW ghost\nversion of the sash is displayed during the resizing to show where the\npanes will be resized to when releasing the mouse button. This\n.QW ghost\nversion of the sash is the proxy. It's rendering can be configured\nusing the \\fB\\-proxybackground\\fR, \\fB\\-proxyborderwidth\\fR and\n\\fB\\-proxyrelief\\fR options.\n.OP \\-proxybackground proxyBackground ProxyBackground\nBackground color to use when drawing the proxy. If an empty string, the\nvalue of the \\fB\\-background\\fR option will be used.\n.OP \\-proxyborderwidth proxyBorderWidth ProxyBorderWidth\nSpecifies the borderwidth of the proxy. May be any value accepted by\n\\fBTk_GetPixels\\fR.\n.OP \\-proxyrelief proxyRelief ProxyRelief\nRelief to use when drawing the proxy. May be any of the standard Tk\nrelief values. If an empty string, the value of the \\fB\\-sashrelief\\fR\noption will be used.\n.OP \\-sashcursor sashCursor SashCursor\nMouse cursor to use when over a sash. If null,\n\\fBsb_h_double_arrow\\fR will be used for horizontal panedwindows, and\n\\fBsb_v_double_arrow\\fR will be used for vertical panedwindows.\n.OP \\-sashpad sashPad SashPad\nSpecifies the amount of padding to leave of each side of a sash. May\nbe any value accepted by \\fBTk_GetPixels\\fR.\n.OP \\-sashrelief sashRelief SashRelief\nRelief to use when drawing a sash. May be any of the standard Tk\nrelief values.\n.OP \\-sashwidth sashWidth SashWidth\nSpecifies the width of each sash. May be any value accepted by\n\\fBTk_GetPixels\\fR.\n.OP \\-showhandle showHandle ShowHandle\nSpecifies whether sash handles should be shown. May be any valid Tcl\nboolean value.\n.OP \\-width width Width\nSpecifies a desired width for the overall panedwindow widget. May be any\nvalue accepted by \\fBTk_GetPixels\\fR. If an empty string, the widget will be\nmade wide enough to allow all contained widgets to have their natural width.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBpanedwindow\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a panedwindow widget.\nAdditional options, described above, may be specified on the command\nline or in the option database to configure aspects of the panedwindow\nsuch as its default background color and relief. The\n\\fBpanedwindow\\fR command returns the path name of the new window.\n.PP\nA panedwindow widget contains any number of panes, arranged\nhorizontally or vertically, according to the value of the\n\\fB\\-orient\\fR option. Each pane contains one widget, and each pair of\npanes is separated by a moveable (via mouse movements) sash. Moving a\nsash causes the widgets on either side of the sash to be resized.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBpanedwindow\\fR command creates a new Tcl command whose name is\nthe same as the path name of the panedwindow's window. This command\nmay be used to invoke various operations on the widget. It has the\nfollowing general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIPathName\\fR is the name of the command, which is the same as\nthe panedwindow widget's path name. \\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for panedwindow widgets:\n.\\\" METHOD: add\n.TP\n\\fIpathName \\fBadd \\fIwindow \\fR?\\fIwindow ...\\fR? ?\\fIoption value ...\\fR?\n.\nAdd one or more windows to the panedwindow, each in a separate pane.\nThe arguments consist of the names of one or more windows\nfollowed by pairs of arguments that specify how to manage the windows.\n\\fIOption\\fR may have any of the values accepted by the\n\\fBconfigure\\fR subcommand.\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget \\fIoption\\fR\n.\nReturns the current value of the configuration option given by\n\\fIoption\\fR. \\fIOption\\fR may have any of the values accepted by the\n\\fBpanedwindow\\fR command.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure \\fR?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget. If no\n\\fIoption\\fR is specified, returns a list describing all of the\navailable options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string. \\fIOption\\fR may have\nany of the values accepted by the \\fBpanedwindow\\fR command.\n.\\\" METHOD: forget\n.TP\n\\fIpathName \\fBforget \\fIwindow \\fR?\\fIwindow ...\\fR?\n.\nRemove the pane containing \\fIwindow\\fR from the panedwindow. All\ngeometry management options for \\fIwindow\\fR will be forgotten.\n.\\\" METHOD: identify\n.TP\n\\fIpathName \\fBidentify \\fIx y\\fR\n.\nIdentify the panedwindow component underneath the point given by\n\\fIx\\fR and \\fIy\\fR, in window coordinates. If the point is over a\nsash or a sash handle, the result is a two element list containing the\nindex of the sash or handle, and a word indicating whether it is over\na sash or a handle, such as {0 sash} or {2 handle}. If the point is\nover any other part of the panedwindow, the result is an empty list.\n.\\\" METHOD: panecget\n.TP\n\\fIpathName \\fBpanecget \\fIwindow option\\fR\n.\nQuery a management option for \\fIwindow\\fR. \\fIOption\\fR may be any\nvalue allowed by the \\fBpaneconfigure\\fR subcommand.\n.\\\" METHOD: paneconfigure\n.TP\n\\fIpathName \\fBpaneconfigure \\fIwindow \\fR?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the management options for \\fIwindow\\fR. If no\n\\fIoption\\fR is specified, returns a list describing all of the\navailable options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string. The following options\nare supported:\n.RS\n.\\\" OPTION: -after\n.TP\n\\fB\\-after \\fIwindow\\fR\n.\nInsert the window after the window specified. \\fIwindow\\fR should be the\nname of a window already managed by \\fIpathName\\fR.\n.\\\" OPTION: -before\n.TP\n\\fB\\-before \\fIwindow\\fR\n.\nInsert the window before the window specified. \\fIwindow\\fR should be\nthe name of a window already managed by \\fIpathName\\fR.\n.\\\" OPTION: -height\n.TP\n\\fB\\-height \\fIsize\\fR\n.\nSpecify a height for the window. The height will be the outer\ndimension of the window including its border, if any. If \\fIsize\\fR\nis an empty string, or if \\fB\\-height\\fR is not specified, then the\nheight requested internally by the window will be used initially; the\nheight may later be adjusted by the movement of sashes in the\npanedwindow. \\fISize\\fR may be any value accepted by \\fBTk_GetPixels\\fR.\n.\\\" OPTION: -hide\n.TP\n\\fB\\-hide \\fIboolean\\fR\n.\nControls the visibility of a pane. When the \\fIboolean\\fR is true\n(according to \\fBTcl_GetBoolean\\fR) the pane will not be visible, but\nit will still be maintained in the list of panes.\n.\\\" OPTION: -minsize\n.TP\n\\fB\\-minsize \\fIn\\fR\n.\nSpecifies that the size of the window cannot be made less than\n\\fIn\\fR. This constraint only affects the size of the widget in the\npaned dimension \\(em the x dimension for horizontal panedwindows, the y\ndimension for vertical panedwindows. May be any value accepted by\n\\fBTk_GetPixels\\fR.\n.\\\" OPTION: -padx\n.TP\n\\fB\\-padx \\fIn\\fR\n.\nSpecifies a non-negative value indicating how much extra space to\nleave on each side of the window in the X-direction. The value may\nhave any of the forms accepted by \\fBTk_GetPixels\\fR.\n.\\\" OPTION: -pady\n.TP\n\\fB\\-pady \\fIn\\fR\n.\nSpecifies a non-negative value indicating how much extra space to\nleave on each side of the window in the Y-direction. The value may\nhave any of the forms accepted by \\fBTk_GetPixels\\fR.\n.\\\" OPTION: -sticky\n.TP\n\\fB\\-sticky \\fIstyle\\fR\n.\nIf a window's pane is larger than the requested dimensions of the\nwindow, this option may be used to position (or stretch) the window\nwithin its pane. \\fIStyle\\fR is a string that contains zero or more\nof the characters \\fBn\\fR, \\fBs\\fR, \\fBe\\fR or \\fBw\\fR. The string\ncan optionally contains spaces or commas, but they are ignored. Each\nletter refers to a side (north, south, east, or west) that the window\nwill\n.QW stick\nto. If both \\fBn\\fR and \\fBs\\fR (or \\fBe\\fR and \\fBw\\fR)\nare specified, the window will be stretched to fill the entire height\n(or width) of its cavity.\n.\\\" OPTION: -stretch\n.TP\n\\fB\\-stretch \\fIwhen\\fR\n.\nControls how extra space is allocated to each of the panes.\n\\fIWhen\\fR is one of \\fBalways\\fR, \\fBfirst\\fR, \\fBlast\\fR,\n\\fBmiddle\\fR, and \\fBnever\\fR.\nThe panedwindow will calculate the required size of all its panes. Any\nremaining (or deficit) space will be distributed to those panes marked\nfor stretching. The space will be distributed based on each panes\ncurrent ratio of the whole. The \\fIwhen\\fR values have the following\ndefinition:\n.RS\n.IP \\fBalways\\fR\nThis pane will always stretch.\n.IP \\fBfirst\\fR\nOnly if this pane is the first pane (left-most or top-most) will it\nstretch.\n.IP \\fBlast\\fR\nOnly if this pane is the last pane (right-most or bottom-most) will it\nstretch. This is the default value.\n.IP \\fBmiddle\\fR\nOnly if this pane is not the first or last pane will it stretch.\n.IP \\fBnever\\fR\nThis pane will never stretch.\n.RE\n.\\\" OPTION: -width\n.TP\n\\fB\\-width \\fIsize\\fR\n.\nSpecify a width for the window. The width will be the outer\ndimension of the window including its border, if any. If \\fIsize\\fR\nis an empty string, or if \\fB\\-width\\fR is not specified, then the\nwidth requested internally by the window will be used initially; the\nwidth may later be adjusted by the movement of sashes in the\npanedwindow. \\fISize\\fR may be any value accepted by \\fBTk_GetPixels\\fR.\n.RE\n.\\\" METHOD: panes\n.TP\n\\fIpathName \\fBpanes\\fR\n.\nReturns an ordered list of the widgets managed by \\fIpathName\\fR.\n.\\\" METHOD: proxy\n.TP\n\\fIpathName \\fBproxy \\fR?\\fIargs\\fR?\n.\nThis command is used to query and change the position of the sash\nproxy, used for rubberband-style pane resizing. It can take any of\nthe following forms:\n.RS\n.TP\n\\fIpathName \\fBproxy coord\\fR\n.\nReturn a list containing the x and y coordinates of the most recent\nproxy location.\n.TP\n\\fIpathName \\fBproxy forget\\fR\n.\nRemove the proxy from the display.\n.TP\n\\fIpathName \\fBproxy place \\fIx y\\fR\n.\nPlace the proxy at the given \\fIx\\fR and \\fIy\\fR coordinates.\n.RE\n.\\\" METHOD: sash\n.TP\n\\fIpathName \\fBsash \\fR?\\fIargs\\fR?\n.\nThis command is used to query and change the position of sashes in the\npanedwindow. It can take any of the following forms:\n.RS\n.TP\n\\fIpathName \\fBsash coord \\fIindex\\fR\n.\nReturn the current x and y coordinate pair for the sash given by\n\\fIindex\\fR. \\fIIndex\\fR must be an integer between 0 and 1 less than\nthe number of panes in the panedwindow. The coordinates given are\nthose of the top left corner of the region containing the sash.\n.TP\n\\fIpathName \\fBsash dragto \\fIindex x y\\fR\n.\nThis command computes the difference between the given coordinates and the\ncoordinates given to the last \\fBsash mark\\fR command for the given\nsash. It then moves that sash the computed difference. The return\nvalue is the empty string.\n.TP\n\\fIpathName \\fBsash mark \\fIindex x y\\fR\n.\nRecords \\fIx\\fR and \\fIy\\fR for the sash given by \\fIindex\\fR; used in\nconjunction with later \\fBsash dragto\\fR commands to move the sash.\n.TP\n\\fIpathName \\fBsash place \\fIindex x y\\fR\n.\nPlace the sash given by \\fIindex\\fR at the given coordinates.\n.RE\n.SH \"RESIZING PANES\"\n.PP\nA pane is resized by grabbing the sash (or sash handle if present) and\ndragging with the mouse. This is accomplished via mouse motion\nbindings on the widget. When a sash is moved, the sizes of the panes\non each side of the sash, and thus the widgets in those panes, are\nadjusted.\n.PP\nWhen a pane is resized from outside (e.g. it is packed to expand and\nfill, and the containing toplevel is resized), space is added to the final\n(rightmost or bottommost) pane in the window.\n.PP\nUnlike child windows managed by e.g. pack or grid, the panes managed by a\npanedwindow do not change width or height to accommodate changes in the\nrequested widths or heights of the panes, once these have become mapped.\nTherefore it may be advisable, particularly when creating layouts\ninteractively, to not add a pane to the panedwindow widget until after the\ngeometry requests of that pane has been finalized (i.e., all components of\nthe pane inserted, all options affecting geometry set to their proper\nvalues, etc.).\n.SH \"SEE ALSO\"\nttk::panedwindow(n)\n.SH KEYWORDS\npanedwindow, widget, geometry management\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/photo.n", "content": "'\\\"\n'\\\" Copyright (c) 1994 The Australian National University\n'\\\" Copyright (c) 1994-1997 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n'\\\" Author: Paul Mackerras (paulus@cs.anu.edu.au),\n'\\\"\t Department of Computer Science,\n'\\\"\t Australian National University.\n'\\\"\n.TH photo n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nphoto \\- Full-color images\n.SH SYNOPSIS\n.nf\n\\fBimage create photo \\fR?\\fIname\\fR? ?\\fIoptions\\fR?\n\n\\fIimageName \\fBblank\\fR\n\\fIimageName \\fBcget \\fIoption\\fR\n\\fIimageName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n\\fIimageName \\fBcopy \\fIsourceImage\\fR ?\\fIoption value(s) ...\\fR?\n\\fIimageName \\fBdata\\fR ?\\fIoption value(s) ...\\fR?\n\\fIimageName \\fBget \\fIx y\\fR ?\\fIoption\\fR?\n\\fIimageName \\fBput \\fIdata\\fR ?\\fIoption value(s) ...\\fR?\n\\fIimageName \\fBread \\fIfilename\\fR ?\\fIoption value(s) ...\\fR?\n\\fIimageName \\fBredither\\fR\n\\fIimageName \\fBtransparency \\fIsubcommand \\fR?\\fIarg ...\\fR?\n\\fIimageName \\fBwrite \\fIfilename\\fR ?\\fIoption value(s) ...\\fR?\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nA photo is an image whose pixels can display any color with a varying\ndegree of transparency (the alpha channel). A photo image is stored\ninternally in full color (32 bits per pixel), and is displayed using\ndithering if necessary. Image data for a photo image can be obtained\nfrom a file or a string, or it can be supplied from C code through a\nprocedural interface. At present, only\n.VS 8.6\nPNG,\n.VE 8.6\nGIF, PPM/PGM,\n.VS 9.0\nand (read-only) SVG\n.VE 9.0\nformats are supported, but an interface exists to\nallow additional image file formats to be added easily. A photo image\nis (semi)transparent if the image data it was obtained from had\ntransparency information. In regions where no image data has been\nsupplied, it is fully transparent. Transparency may also be modified\nwith the \\fBtransparency set\\fR subcommand.\n.SH \"CREATING PHOTOS\"\n.PP\nLike all images, photos are created using the \\fBimage create\\fR\ncommand.\nPhotos support the following \\fIoptions\\fR:\n.\\\" OPTION: -data\n.TP\n\\fB\\-data \\fIstring\\fR\n.\nSpecifies the contents of the image as a string.\n.VS 9.0\nThe string should\ncontain data in the default list-of-lists form,\n.VE 9.0\nbinary data or, for some formats, base64-encoded data (this is\ncurrently guaranteed to be supported for PNG and GIF images). The\nformat of the string must be one of those for which there is an image\nfile format handler that will accept string data. If both the\n\\fB\\-data\\fR and \\fB\\-file\\fR options are specified, the \\fB\\-file\\fR\noption takes precedence.\n.\\\" OPTION: -format\n.TP\n\\fB\\-format\\fR {\\fIformat-name\\fR ?\\fIoption value ...\\fR?}\n.\nSpecifies the name of the file format for the data specified with the\n\\fB\\-data\\fR or \\fB\\-file\\fR option and optional arguments passed to\nthe format handler. Note that the value of this option must be a Tcl list.\nThis means that the braces may be omitted if the argument has only one\nword. Also, instead of braces, double quotes may be used for quoting.\n.\\\" OPTION: -file\n.TP\n\\fB\\-file \\fIname\\fR\n.\n\\fIname\\fR gives the name of a file that is to be read to supply data\nfor the photo image. The file format must be one of those for which\nthere is an image file format handler that can read data.\n.\\\" OPTION: -gamma\n.TP\n\\fB\\-gamma \\fIvalue\\fR\n.\nSpecifies that the colors allocated for displaying this image in a\nwindow should be corrected for a non-linear display with the specified\ngamma exponent value. (The intensity produced by most\nCRT displays is a power function of the input value, to a good\napproximation; gamma is the exponent and is typically around 2).\nThe value specified must be greater than zero. The default\nvalue is one (no correction). In general, values greater than one\nwill make the image lighter, and values less than one will make it\ndarker.\n.\\\" OPTION: -height\n.TP\n\\fB\\-height \\fInumber\\fR\n.\nSpecifies the height of the image, in pixels. This option is useful\nprimarily in situations where the user wishes to build up the contents\nof the image piece by piece. A value of zero (the default) allows the\nimage to expand or shrink vertically to fit the data stored in it.\n.VS 9.0\n.\\\" OPTION: -metadata\n.TP\n\\fB\\-metadata \\fImetadata\\fR\n.\nSet the metadata dictionary of the image.\nAdditional keys may be set within the metadata dictionary of the image,\nif image data is processed due to a \\fB\\-file\\fR or \\fB\\-data\\fR options\nand the driver outputs any metadata keys.\nSee section \\fBMETADATA DICTIONARY\\fR below.\n.VE 9.0\n.\\\" OPTION: -palette\n.TP\n\\fB\\-palette \\fIpalette-spec\\fR\n.\nSpecifies the resolution of the color cube to be allocated for\ndisplaying this image, and thus the number of colors used from the\ncolormaps of the windows where it is displayed. The\n\\fIpalette-spec\\fR string may be either a single decimal number,\nspecifying the number of shades of gray to use, or three decimal\nnumbers separated by slashes (/), specifying the number of shades of\nred, green and blue to use, respectively. If the first form (a single\nnumber) is used, the image will be displayed in monochrome (i.e.,\ngrayscale).\n.\\\" OPTION: -width\n.TP\n\\fB\\-width \\fInumber\\fR\n.\nSpecifies the width of the image, in pixels. This option is useful\nprimarily in situations where the user wishes to build up the contents\nof the image piece by piece. A value of zero (the default) allows the\nimage to expand or shrink horizontally to fit the data stored in it.\n.SH \"IMAGE COMMAND\"\n.PP\nWhen a photo image is created, Tk also creates a new command\nwhose name is the same as the image.\nThis command may be used to invoke various operations\non the image.\nIt has the following general form:\n.CS\n\\fIimageName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command.\n.PP\nThose options that write data to the image generally expand the size\nof the image, if necessary, to accommodate the data written to the\nimage, unless the user has specified non-zero values for the\n\\fB\\-width\\fR and/or \\fB\\-height\\fR configuration options, in which\ncase the width and/or height, respectively, of the image will not be\nchanged.\n.PP\nThe following commands are possible for photo images:\n.\\\" METHOD: blank\n.TP\n\\fIimageName \\fBblank\\fR\n.\nBlank the image; that is, set the entire image to have no data, so it\nwill be displayed as transparent, and the background of whatever\nwindow it is displayed in will show through. The metadata dict of the\nimage is not changed.\n.\\\" METHOD: cget\n.TP\n\\fIimageName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the\n\\fBimage create\\fR \\fBphoto\\fR command.\n.\\\" METHOD: configure\n.TP\n\\fIimageName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options for the image.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIimageName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the\n\\fBimage create\\fR \\fBphoto\\fR command.\n.VS 9.0\nNote that setting the \\fB\\-metadata\\fR option without any other option\nwill not invoke the image format driver to recreate the bitmap.\n.VE 9.0\n.\\\" METHOD: copy\n.TP\n\\fIimageName \\fBcopy\\fI sourceImage\\fR ?\\fIoption value(s) ...\\fR?\n.\nCopies a region from the image called \\fIsourceImage\\fR (which must\nbe a photo image) to the image called \\fIimageName\\fR, possibly with\npixel zooming and/or subsampling. If no options are specified, this\ncommand copies the whole of \\fIsourceImage\\fR into \\fIimageName\\fR,\nstarting at coordinates (0,0) in \\fIimageName\\fR. The following\noptions may be specified:\n.RS\n.\\\" OPTION: -from\n.TP\n\\fB\\-from \\fIx1 y1 x2 y2\\fR\n.\nSpecifies a rectangular sub-region of the source image to be copied.\n(\\fIx1,y1\\fR) and (\\fIx2,y2\\fR) specify diagonally opposite corners of\nthe rectangle. If \\fIx2\\fR and \\fIy2\\fR are not specified, the\ndefault value is the bottom-right corner of the source image. The\npixels copied will include the left and top edges of the specified\nrectangle but not the bottom or right edges. If the \\fB\\-from\\fR\noption is not given, the default is the whole source image.\n.\\\" OPTION: -to\n.TP\n\\fB\\-to \\fIx1 y1 x2 y2\\fR\n.\nSpecifies a rectangular sub-region of the destination image to be\naffected. (\\fIx1,y1\\fR) and (\\fIx2,y2\\fR) specify diagonally opposite\ncorners of the rectangle. If \\fIx2\\fR and \\fIy2\\fR are not specified,\nthe default value is (\\fIx1,y1\\fR) plus the size of the source\nregion (after subsampling and zooming, if specified). If \\fIx2\\fR and\n\\fIy2\\fR are specified, the source region will be replicated if\nnecessary to fill the destination region in a tiled fashion.\n.\\\" OPTION: -shrink\n.TP\n\\fB\\-shrink\\fR\n.\nSpecifies that the size of the destination image should be reduced, if\nnecessary, so that the region being copied into is at the bottom-right\ncorner of the image. This option will not affect the width or height\nof the image if the user has specified a non-zero value for the\n\\fB\\-width\\fR or \\fB\\-height\\fR configuration option, respectively.\n.\\\" OPTION: -zoom\n.TP\n\\fB\\-zoom \\fIx y\\fR\n.\nSpecifies that the source region should be magnified by a factor of\n\\fIx\\fR in the X direction and \\fIy\\fR in the Y direction. If \\fIy\\fR\nis not given, the default value is the same as \\fIx\\fR. With this\noption, each pixel in the source image will be expanded into a block\nof \\fIx\\fR x \\fIy\\fR pixels in the destination image, all the same\ncolor. \\fIx\\fR and \\fIy\\fR must be greater than 0.\n.\\\" OPTION: -subsample\n.TP\n\\fB\\-subsample \\fIx y\\fR\n.\nSpecifies that the source image should be reduced in size by using\nonly every \\fIx\\fRth pixel in the X direction and \\fIy\\fRth pixel in\nthe Y direction. Negative values will cause the image to be flipped\nabout the Y or X axes, respectively. If \\fIy\\fR is not given, the\ndefault value is the same as \\fIx\\fR.\n.\\\" OPTION: -compositingrule\n.TP\n\\fB\\-compositingrule \\fIrule\\fR\n.\nSpecifies how transparent pixels in the source image are combined with\nthe destination image. When a compositing rule of \\fIoverlay\\fR is\nset, the old contents of the destination image are visible, as if the\nsource image were printed on a piece of transparent film and placed\nover the top of the destination. When a compositing rule of \\fIset\\fR\nis set, the old contents of the destination image are discarded and\nthe source image is used as-is. The default compositing rule is\n\\fIoverlay\\fR.\n.RE\n.\\\" METHOD: data\n.TP\n\\fIimageName \\fBdata\\fR ?\\fIoption value(s) ...\\fR?\n.\nReturns image data in the form of a string.\n.VS 9.0\nThe format of the string depends on the format handler. By default, a\nhuman readable format as a list of lists of pixel data is used, other\nformats can be chosen with the \\fB\\-format\\fR option.\nSee \\fBIMAGE FORMATS\\fR below for details.\n.VE 9.0\nThe following options may be specified:\n.RS\n.\\\" OPTION: -background\n.TP\n\\fB\\-background\\fI color\\fR\n.\nIf the color is specified, the data will not contain any transparency\ninformation. In all transparent pixels the color will be replaced by\nthe specified color.\n.\\\" OPTION: -format\n.TP\n\\fB\\-format\\fR {\\fIformat-name\\fR ?\\fIoption value ...\\fR?}\n.\nSpecifies the name of the image file format handler to use and,\noptionally, arguments to the format handler. Specifically, this\nsubcommand searches for the first handler whose name matches an\ninitial substring of \\fIformat-name\\fR and which has the capability to\nwrite a string containing this image data.\n.VS 9.0\nIf this option is not given, this subcommand uses the default format\nthat consists of a list (one element per row) of lists (one element\nper pixel/column) of colors in\n.QW \\fB#\\fIrrggbb\\fR\nformat (see \\fBIMAGE FORMATS\\fR below).\n.VE 9.0\nNote that the value of this option must be a Tcl list.\nThis means that the braces may be omitted if the argument has only one\nword. Also, instead of braces, double quotes may be used for quoting.\n.\\\" OPTION: -from\n.TP\n\\fB\\-from \\fIx1 y1 x2 y2\\fR\n.\nSpecifies a rectangular region of \\fIimageName\\fR to be returned.\nIf only \\fIx1\\fR and \\fIy1\\fR are specified, the region\nextends from \\fI(x1,y1)\\fR to the bottom-right corner of\n\\fIimageName\\fR. If all four coordinates are given, they specify\ndiagonally opposite corners of the rectangular region, including x1,y1\nand excluding x2,y2. The default, if this option is not given, is the\nwhole image.\n.\\\" OPTION: -grayscale\n.TP\n\\fB\\-grayscale\\fR\n.\nIf this options is specified, the data will not contain color\ninformation. All pixel data will be transformed into grayscale.\n.VS 9.0\n.\\\" OPTION: -metadata\n.TP\n\\fB\\-metadata\\fI metadata\\fR\n.\nImage format handler may use metadata to be included in the returned\ndata string.\nThe specified \\fImetadata\\fR is passed to the driver for inclusion in the\ndata.\nIf no \\fB\\-metadata\\fR option is given, the current metadata of the\nimage is used.\n.VE 9.0\n.RE\n.\\\" METHOD: get\n.TP\n\\fIimageName \\fBget\\fI x y\\fR ?\\fB\\-withalpha\\fR?\n.\nReturns the color of the pixel at coordinates (\\fIx\\fR,\\fIy\\fR) in the\nimage as a list of three integers between 0 and 255, representing the\nred, green and blue components respectively. If the \\fB\\-withalpha\\fR\noption is specified, the returned list will have a fourth element\nrepresenting the alpha value of the pixel as an integer between 0 and\n255.\n.\\\" METHOD: put\n.TP\n\\fIimageName \\fBput\\fI data\\fR ?\\fIoption value(s) ...\\fR?\n.\nSets pixels in \\fI imageName\\fR to the data specified in \\fIdata\\fR.\n.VS 9.0\nThis command searches the list of image file format handlers for\na handler that can interpret the data in \\fIdata\\fR, and then reads\nthe image encoded within into \\fIimageName\\fR (the destination image).\nSee \\fBIMAGE FORMATS\\fR below for details on formats for image data.\n.VE 9.0\nThe following options may be specified:\n.RS\n.\\\" OPTION: -format\n.TP\n\\fB\\-format\\fR {\\fIformat-name\\fR ?\\fIoption value ..\\fR?}\n.\nSpecifies the format of the image data in \\fIdata\\fR and, optionally,\narguments to be passed to the format handler.\nSpecifically, only image file format handlers whose names begin with\n\\fIformat-name\\fR will be used while searching for an image data\nformat handler to read the data.\nNote that the value of this option must be a Tcl list.\nThis means that the braces may be omitted if the argument has only one\nword. Also, instead of braces, double quotes may be used for quoting.\n.VS 9.0\n.\\\" OPTION: -metadata\n.TP\n\\fB\\-metadata\\fI metadata\\fR\n.\nA specified \\fImetadata\\fR is passed to the image format driver when interpreting\nthe data.\nNote that the current metadata of the image is not passed to the format driver\nand is not changed by the command.\n.VE 9.0\n.\\\" OPTION: -to\n.TP\n\\fB\\-to \\fIx1 y1\\fR ?\\fIx2 y2\\fR?\n.\nSpecifies the coordinates of the top-left corner (\\fIx1\\fR,\\fIy1\\fR)\nof the region of \\fIimageName\\fR into which the image data will be\ncopied. The default position is (0,0). If \\fIx2\\fR,\\fIy2\\fR is given\nand \\fIdata\\fR is not large enough to cover the rectangle specified by\nthis option, the image data extracted will be tiled so it covers the\nentire destination rectangle. If the region specified with this option\nis smaller than the supplied \\fIdata\\fR, the exceeding data is silently\ndiscarded. Note that if \\fIdata\\fR specifies a\nsingle color value, then a region extending to the bottom-right corner\nrepresented by (\\fIx2\\fR,\\fIy2\\fR) will be filled with that color.\n.RE\n.\\\" METHOD: read\n.TP\n\\fIimageName \\fBread\\fI filename\\fR ?\\fIoption value(s) ...\\fR?\n.\nReads image data from the file named \\fIfilename\\fR into the image.\nThis command first searches the list of\nimage file format handlers for a handler that can interpret the data\nin \\fIfilename\\fR, and then reads the image in \\fIfilename\\fR into\n\\fIimageName\\fR (the destination image). The following options may be\nspecified:\n.RS\n.\\\" OPTION: -format\n.TP\n\\fB\\-format {\\fIformat-name\\fR ?\\fIoption value ..\\fR?}\n.\nSpecifies the format of the image data in \\fIfilename\\fR and,\noptionally, additional options to the format handler.\nSpecifically, only image file format handlers whose names begin with\n\\fIformat-name\\fR will be used while searching for an image data\nformat handler to read the data.\nNote that the value of this option must be a Tcl list.\nThis means that the braces may be omitted if the argument has only one\nword. Also, instead of braces, double quotes may be used for quoting.\n.\\\" OPTION: -from\n.TP\n\\fB\\-from \\fIx1 y1 x2 y2\\fR\n.\nSpecifies a rectangular sub-region of the image file data to be copied\nto the destination image. If only \\fIx1\\fR and \\fIy1\\fR are\nspecified, the region extends from (\\fIx1,y1\\fR) to the bottom-right\ncorner of the image in the image file. If all four coordinates are\nspecified, they specify diagonally opposite corners or the region.\nThe default, if this option is not specified, is the whole of the\nimage in the image file.\n.VS 9.0\n.\\\" OPTION: -metadata\n.TP\n\\fB\\-metadata\\fI metadata\\fR\n.\nA specified \\fImetadata\\fR is passed to the image format driver when interpreting\nthe data.\nNote that the current metadata of the image is not passed to the format driver\nand is not changed by the command.\n.VE 9.0\n.\\\" OPTION: -shrink\n.TP\n\\fB\\-shrink\\fR\n.\nIf this option, the size of \\fIimageName\\fR will be reduced, if\nnecessary, so that the region into which the image file data are read\nis at the bottom-right corner of the \\fIimageName\\fR. This option\nwill not affect the width or height of the image if the user has\nspecified a non-zero value for the \\fB\\-width\\fR or \\fB\\-height\\fR\nconfiguration option, respectively.\n.\\\" OPTION: -to\n.TP\n\\fB\\-to \\fIx y\\fR\n.\nSpecifies the coordinates of the top-left corner of the region of\n\\fIimageName\\fR into which data from \\fIfilename\\fR are to be read.\nThe default is (0,0).\n.RE\n.\\\" METHOD: redither\n.TP\n\\fIimageName \\fBredither\\fR\n.\nThe dithering algorithm used in displaying photo images propagates\nquantization errors from one pixel to its neighbors.\nIf the image data for \\fIimageName\\fR is supplied in pieces, the\ndithered image may not be exactly correct. Normally the difference is\nnot noticeable, but if it is a problem, this command can be used to\nrecalculate the dithered image in each window where the image is\ndisplayed.\n.\\\" METHOD: transparency\n.TP\n\\fIimageName \\fBtransparency \\fIsubcommand \\fR?\\fIarg ...\\fR?\n.\nAllows examination and manipulation of the transparency information in\nthe photo image. Several subcommands are available:\n.RS\n.TP\n\\fIimageName \\fBtransparency get \\fIx y\\fR ?\\fB\\-alpha\\fR?\n.VS 9.0\nReturns true if the pixel at (\\fIx\\fR,\\fIy\\fR) is fully transparent,\nfalse otherwise. If the option \\fB\\-alpha\\fR is passed, returns the\nalpha value of the pixel instead, as an integer in the range 0 to 255.\n.VE 9.0\n.TP\n\\fIimageName \\fBtransparency set \\fIx y newVal\\fR ?\\fB\\-alpha\\fR?\n.VS 9.0\nChange the transparency of the pixel at (\\fIx\\fR,\\fIy\\fR) to\n\\fInewVal.\\fR If no additional option is passed, \\fInewVal\\fR is\ninterpreted as a boolean and the pixel is made fully transparent if\nthat value is true, fully opaque otherwise. If the \\fB\\-alpha\\fR\noption is passed, \\fInewVal\\fR is interpreted as an integral alpha\nvalue for the pixel, which must be in the range 0 to 255.\n.VE 9.0\n.RE\n.\\\" METHOD: write\n.TP\n\\fIimageName \\fBwrite \\fIfilename\\fR ?\\fIoption value(s) ...\\fR?\n.\nWrites image data from \\fIimageName\\fR to a file named \\fIfilename\\fR.\nThe following options may be specified:\n.RS\n.\\\" OPTION: -background\n.TP\n\\fB\\-background\\fI color\\fR\n.\nIf the color is specified, the data will not contain any transparency\ninformation. In all transparent pixels the color will be replaced by\nthe specified color.\n.\\\" OPTION: -format\n.TP\n\\fB\\-format\\fR {\\fIformat-name\\fR ?\\fIoption value ...\\fR?}\n.\nSpecifies the name of the image file format handler to be used to\nwrite the data to the file and, optionally, options to pass to the\nformat handler. Specifically, this subcommand searches for the first\nhandler whose name matches an initial substring of \\fIformat-name\\fR\nand which has the capability to write an image file. If this option\nis not given, the format is guessed from the file extension. If that\ncannot be determined, this subcommand uses the first handler that has\nthe capability to write an image file.\nNote that the value of this option must be a Tcl list.\nThis means that the braces may be omitted if the argument has only one\nword. Also, instead of braces, double quotes may be used for quoting.\n.\\\" OPTION: -from\n.TP\n\\fB\\-from \\fIx1 y1 x2 y2\\fR\n.\nSpecifies a rectangular region of \\fIimageName\\fR to be written to the\nimage file. If only \\fIx1\\fR and \\fIy1\\fR are specified, the region\nextends from \\fI(x1,y1)\\fR to the bottom-right corner of\n\\fIimageName\\fR. If all four coordinates are given, they specify\ndiagonally opposite corners of the rectangular region. The default,\nif this option is not given, is the whole image.\n.\\\" OPTION: -grayscale\n.TP\n\\fB\\-grayscale\\fR\n.\nIf this options is specified, the data will not contain color\ninformation. All pixel data will be transformed into grayscale.\n.VS 9.0\n.\\\" OPTION: -metadata\n.TP\n\\fB\\-metadata\\fI metadata\\fR\n.\nImage format handler may use metadata to be included in the written file.\nThe specified \\fImetadata\\fR is passed to the driver for inclusion in the\nfile.\nIf no \\fB\\-metadata\\fR option is given, the current metadata of the\nimage is used.\n.VE 9.0\n.RE\n.SH \"IMAGE FORMATS\"\n.PP\nThe photo image code is structured to allow handlers for additional\nimage file formats to be added easily. The photo image code maintains\na list of these handlers. Handlers are added to the list by\nregistering them with a call to \\fBTk_CreatePhotoImageFormat\\fR. The\nstandard Tk distribution comes with handlers for PPM/PGM, PNG, GIF and\n(read-only) SVG formats,\n.VS 9.0\nas well as the \\fBdefault\\fR handler to encode/decode image\ndata in a human readable form.\n.VE 9.0\nThese handlers are automatically registered on initialization.\n.PP\nWhen reading an image file or processing string data specified with\nthe \\fB\\-data\\fR configuration option, the photo image code invokes\neach handler in turn until one is found that claims to be able to read\nthe data in the file or string. Usually this will find the correct\nhandler, but if it does not, the user may give a format name with the\n\\fB\\-format\\fR option to specify which handler to use. In this case,\nthe photo image code will try those handlers whose names begin with\nthe string specified for the \\fB\\-format\\fR option (the comparison is\ncase-insensitive). For example, if the user specifies \\fB\\-format\ngif\\fR, then a handler named GIF87 or GIF89 may be invoked, but a\nhandler named JPEG may not (assuming that such handlers had been\nregistered).\n.PP\nWhen writing image data to a file, the processing of the\n\\fB\\-format\\fR option is slightly different: the string value given\nfor the \\fB\\-format\\fR option must begin with the complete name of the\nrequested handler, and may contain additional information following\nthat, which the handler can use, for example, to specify which variant\nto use of the formats supported by the handler.\nNote that not all image handlers may support writing transparency data\nto a file, even where the target image format does.\n.VS 9.0\n.SS \"THE DEFAULT IMAGE HANDLER\"\n.PP\nThe \\fBdefault\\fR image handler cannot be used to read or write data\nfrom/to a file. Its sole purpose is to encode and decode image data in\nstring form in a clear text, human readable, form. The \\fIimageName\\fR\n\\fBdata\\fR subcommand uses this handler when no other format is\nspecified. When reading image data from a string with \\fIimageName\\fR\n\\fBput\\fR or the \\fB\\-data\\fR option, the default handler is treated\nas the other handlers.\n.PP\nImage data in the \\fBdefault\\fR string format is a (top-to-bottom)\nlist of scan-lines, with each scan-line being a (left-to-right) list\nof pixel data. Every scan-line has the same length. The color\nand, optionally, alpha value of each pixel is specified in any of\nthe forms described in the \\fBCOLOR FORMATS\\fR section below.\n.VE 9.0\n\n.SS \"FORMAT SUBOPTIONS\"\n.PP\n.VS 8.6\nImage formats may support sub-options, which are specified using\nadditional words in the value to the \\fB\\-format\\fR option. These\nsuboptions can affect how image data is read or written to file or\nstring. The nature and values of these options is up to the format\nhandler.\nThe built-in handlers support these suboptions:\n.\\\" OPTION -colorformat\n.VS 9.0\n.TP\n\\fBdefault \\-colorformat\\fI formatType\\fR\n.\nThe option is allowed when writing image data to a string with\n\\fIimageName \\fBdata\\fR. Specifies the format to use for the color\nstring of each pixel. \\fIformatType\\fR may be one of: \\fBrgb\\fR to\nencode pixel data in the form \\fB#\\fIRRGGBB\\fR, \\fBrgba\\fR to encode\npixel data in the form \\fB#\\fIRRGGBBAA\\fR or \\fBlist\\fR to encode\npixel data as a list with four elements. See \\fBCOLOR FORMATS\\fR\nbelow for details. The default is \\fBrgb\\fR.\n.VE 9.0\n.\\\" OPTION -index\n.TP\n\\fBgif \\-index\\fI indexValue\\fR\n.\nThe option has effect when reading image data from a file. When\nparsing a multi-part GIF image, Tk normally only accesses the first\nimage. By giving the \\fB\\-index\\fR sub-option, the \\fIindexValue\\fR'th\nvalue may be used instead. The \\fIindexValue\\fR must be an integer\nfrom 0 up to the number of image parts in the GIF data.\n.\\\" OPTION -alpha\n.TP\n\\fBpng \\-alpha\\fI alphaValue\\fR\n.\nThe option has effect when reading image data from a file. Specifies\nan additional alpha filtering for the overall image, which allows the\nbackground on which the image is displayed to show through. This\nusually also has the effect of desaturating the image. The\n\\fIalphaValue\\fR must be between 0.0 and 1.0.\n.\\\" OPTION -dpi\n.\\\" OPTION -scale\n.\\\" OPTION -scaletowidth\n.\\\" OPTION -scaletoheight\n.TP\n\\fBsvg \\-dpi\\fI dpiValue \\fB\\-scale\\fI scaleValue \\fB\\-scaletowidth\\fI width \\fB\\-scaletoheight\\fI height\\fR\n.\n\\fIdpiValue\\fR is used in conversion between given coordinates and\nscreen resolution. The value must be greater than 0 and the default\nvalue is 96.\n.PP\n.RS\n\\fIscaleValue\\fR is used to scale the resulting image. The value must\nbe greater than 0 and the default value is 1.\n\\fIwidth\\fR and \\fIheight\\fR are the width or height that the image\nwill be adjusted to. Only one parameter among \\fB\\-scale\\fR,\n\\fB\\-scaletowidth\\fR and \\fB\\-scaletoheight\\fR can be given at a time\nand the aspect ratio of the original image is always preserved.\nThe \\fBsvg\\fR format supports a wide range of SVG features, but the\nfull SVG standard is not available, for instance the 'text' feature\nis missing and silently ignored when reading the SVG data.\nThe supported SVG features are:\n.TP\n\\fBelements:\\fR\n.\ng, path, rect, circle, ellipse, line, polyline, polygon,\nlinearGradient, radialGradient, stop, defs, svg, style\n.TP\n\\fBattributes:\\fR\n.\nwidth, height, viewBox,\npreserveAspectRatio with none, xMin, xMid, xMax, yMin, yMid, yMax, slice\n.TP\n\\fBgradient attributes:\\fR\n.\ngradientUnits with objectBoundingBox,\ngradientTransform, cx, cy, r fx, fy x1, y1, x2, y2\nspreadMethod with pad, reflect or repeat,\nxlink:href\n.TP\n\\fBpoly attributes:\\fR\n.\npoints\n.TP\n\\fBline attributes:\\fR\n.\nx1, y1, x2, y2\n.TP\n\\fBellipse attributes:\\fR\n.\ncx, cy, rx, ry\n.TP\n\\fBcircle attributes:\\fR\n.\ncx, cy, r\n.TP\n\\fBrectangle attributes:\\fR\n.\nx, y, width, height, rx, ry\n.TP\n\\fBpath attributes:\\fR\n.\nd with m, M, l, L, h, H, v, V, c, C, s, S, q, Q, t, T, a, A, z, Z\n.TP\n\\fBstyle attributes:\\fR\n.\ndisplay with none, visibility, hidden, visible,\nfill with nonzero and evenodd, opacity, fill-opacity,\nstroke, stroke-width, stroke-dasharray, stroke-dashoffset, stroke-opacity,\nstroke-linecap with butt, round and square,\nstroke-linejoin with miter, round and bevel, stroke-miterlimit\nfill-rule, font-size,\ntransform with matrix, translate, scale, rotate, skewX and skewY,\nstop-color, stop-opacity, offset, id, class\n.RE\n.PP\n.RS\nCurrently only SVG images reading and conversion into (pixel-based\nformat) photos is supported: Tk does not (yet) support bundling photo\nimages in SVG vector graphics.\n.RE\n.VE 8.6\n.VS 9.0\n.SH \"COLOR FORMATS\"\n.PP\nThe default image handler can represent/parse color and alpha values\nof a pixel in one of the formats listed below. If a color format does\nnot contain transparency information, full opacity is assumed. The\navailable color formats are:\n.IP \\(bu 3\nThe empty string - interpreted as full transparency, the color value\nis undefined.\n.IP \\(bu 3\nAny value accepted by \\fBTk_GetColor\\fR, optionally followed by an\nalpha suffix. The alpha suffix may be one of:\n.RS\n.TP\n\\fB@\\fR\\fIA\\fR\n.\nThe alpha value \\fIA\\fR must be a fractional value in the range 0.0\n(fully transparent) to 1.0 (fully opaque).\n.TP\n\\fB#\\fR\\fIX\\fR\n.\nThe alpha value \\fIX\\fR is a hexadecimal digit that specifies an integer\nalpha value in the range 0 (fully transparent) to 255 (fully opaque).\nThis is expanded in range from 4 bits wide to 8 bits wide by\nmultiplication by 0x11.\n.TP\n\\fB#\\fR\\fIXX\\fR\n.\nThe alpha value \\fIXX\\fR is passed as two hexadecimal digits that\nspecify an integer alpha value in the range 0 (fully transparent) to 255\n(fully opaque).\n.RE\n.IP \\(bu 3\nA Tcl list with three or four integers in the range 0 to 255,\nspecifying the values for the red, green, blue and (optionally)\nalpha channels respectively.\n.IP \\(bu 3\n\\fB#\\fR\\fIRGBA\\fR format: a \\fB#\\fR followed by four hexadecimal digits,\nwhere each digit is the value for the red, green, blue and alpha\nchannels respectively. Each digit will be expanded internally to\n8 bits by multiplication by 0x11.\n.IP \\(bu 3\n\\fB#\\fR\\fIRRGGBBAA\\fR format: \\fB#\\fR followed by eight hexadecimal digits,\nwhere each pair of subsequent digits represents the value for the red,\ngreen, blue and alpha channels respectively.\n.VE 9.0\n.SH \"COLOR ALLOCATION\"\n.PP\nWhen a photo image is displayed in a window, the photo image code\nallocates colors to use to display the image and dithers the image, if\nnecessary, to display a reasonable approximation to the image using\nthe colors that are available. The colors are allocated as a color\ncube, that is, the number of colors allocated is the product of the\nnumber of shades of red, green and blue.\n.PP\nNormally, the number of\ncolors allocated is chosen based on the depth of the window. For\nexample, in an 8-bit PseudoColor window, the photo image code will\nattempt to allocate seven shades of red, seven shades of green and\nfour shades of blue, for a total of 198 colors. In a 1-bit StaticGray\n(monochrome) window, it will allocate two colors, black and white. In\na 24-bit DirectColor or TrueColor window, it will allocate 256 shades\neach of red, green and blue. Fortunately, because of the way that\npixel values can be combined in DirectColor and TrueColor windows,\nthis only requires 256 colors to be allocated. If not all of the\ncolors can be allocated, the photo image code reduces the number of\nshades of each primary color and tries again.\n.PP\nThe user can exercise some control over the number of colors that a\nphoto image uses with the \\fB\\-palette\\fR configuration option. If\nthis option is used, it specifies the maximum number of shades of\neach primary color to try to allocate. It can also be used to force\nthe image to be displayed in shades of gray, even on a color display,\nby giving a single number rather than three numbers separated by\nslashes.\n.VS 9.0\n.SH \"METADATA DICTIONARY\"\n.PP\nEach image has a metadata dictionary property.\nThis dictionary is not relevant to the bitmap representation of the\nimage, but may contain additional information like resolution or\ncomments.\nImage format drivers may output metadata when image data is\nparsed, or may use metadata to be included in image files or formats.\n.SS \"METADATA KEYS (MULTIPLE FORMATS)\"\n.PP\nEach image format driver supports an individual set of metadata dictionary\nkeys. Predefined keys are:\n.IP \\fBDPI\\fR\nHorizontal image resolution in DPI as a double value.\nSupported by format \\fBpng\\fR.\n.IP \\fBaspect\\fR\nAspect ratio horizontal divided by vertical as double value.\nSupported by formats \\fBgif\\fR and \\fBpng\\fR.\n.IP \\fBcomment\\fR\nImage text comment.\nSupported by formats \\fBgif\\fR and \\fBpng\\fR.\n.PP\nIt is valid to set any key in the metadata dict.\nA format driver will ignore keys that it does not handle.\n.SS \"METADATA KEYS FOR ANIMATED GIF INFORMATION\"\n.PP\nThe following metadata keys are reported when reading a \\fBgif\\fR format file.\nThey are typically used in conjunction with the \\fB\\-index\\fR option of an\nanimated \\fBgif\\fR file to properly display the subimage sequence.\nThe options are linked to each subimage selected by \\fB\\-index\\fR.\n.TP\n\\fBdelay time\\fI time\\fR\n.\nUpdate delay time in 10ms units.\nThis key is only present if the delay time is not 0.\n.TP\n\\fBdisposal method\\fI method\\fR\n.\nDisposal method of the preceeding image, if given for the current image.\nPossible values are: \\fBdo not dispose\\fR, \\fBrestore to background color\\fR,\n\\fBrestore to previous\\fR.\n.TP\n\\fBuser interaction\\fI bool\\fR\n.\nThe key is present with a value of 1, if user interaction is specified.\nOtherwise, the key is not present.\n.TP\n\\fBupdate region\\fI X0\\fR, \\fIY0\\fR, \\fIwidth\\fR, \\fIheight\\fR\n.\nUpdate region of the current subimage, if subimage has not the same size as\nthe full image. The pixel outside of this box are all fully transparent.\n.PP\n.VE 9.0\n.SH CREDITS\n.PP\nThe photo image type was designed and implemented by Paul Mackerras,\nbased on his earlier photo widget and some suggestions from\nJohn Ousterhout.\n.SH EXAMPLE\n.PP\nLoad an image from a file and tile it to the size of a window, which\nis useful for producing a tiled background:\n.PP\n.CS\n# These lines should be called once\n\\fBimage create photo\\fR untiled -file \"theFile.ppm\"\n\\fBimage create photo\\fR tiled\n\n# These lines should be called whenever .someWidget changes\n# size; a binding is useful here\nset width [winfo width .someWidget]\nset height [winfo height .someWidget]\ntiled \\fBcopy\\fR untiled -to 0 0 $width $height -shrink\n.CE\n.PP\n.VS 8.6\nThe PNG image loader allows the application of an additional alpha factor\nduring loading, which is useful for generating images suitable for disabled\nbuttons:\n.PP\n.CS\n\\fBimage create photo\\fR icon -file \"icon.png\"\n\\fBimage create photo\\fR iconDisabled -file \"icon.png\" \\e\n -format \"png -alpha 0.5\"\nbutton .b -image icon -disabledimage iconDisabled\n.CE\n.VE 8.6\n.PP\n.VS 9.0\nCreate a green box with a simple shadow effect\n.PP\n.CS\n\\fBimage create photo\\fR foo\n\n# Make a simple graduated fill varying in alpha for the shadow\nfor {set i 14} {$i > 0} {incr i -1} {\n set i2 [expr {$i + 30}]\n foo \\fBput\\fR [format black#%x [expr {15-$i}]] -to $i $i $i2 $i2\n}\n\n# Put a solid green rectangle on top\nfoo \\fBput\\fR #F080 -to 0 0 30 30\n.VE 9.0\n.CE\n.SH \"SEE ALSO\"\nimage(n)\n.SH KEYWORDS\nphoto, image, color\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/place.n", "content": "'\\\"\n'\\\" Copyright (c) 1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH place n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nplace \\- Geometry manager for fixed or rubber-sheet placement\n.SH SYNOPSIS\n\\fBplace \\fIoption arg \\fR?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe placer is a geometry manager for Tk.\nIt provides simple fixed placement of windows, where you specify\nthe exact size and location of one window, called the \\fIcontent\\fR,\nwithin another window, called the \\fIcontainer\\fR.\nThe placer also provides rubber-sheet placement, where you specify the\nsize and location of the content in terms of the dimensions of\nthe container, so that the content changes size and location\nin response to changes in the size of the container.\nLastly, the placer allows you to mix these styles of placement so\nthat, for example, the content has a fixed width and height but is\ncentered inside the container.\n.PP\n.TP\n\\fBplace \\fIwindow option value \\fR?\\fIoption value ...\\fR?\n.\nArrange for the placer to manage the geometry of a content whose\npathName is \\fIwindow\\fR. The remaining arguments consist of one or\nmore \\fIoption\\-value\\fR pairs that specify the way in which\n\\fIwindow\\fR's geometry is managed. \\fIOption\\fR may have any of the\nvalues accepted by the \\fBplace configure\\fR command.\n.\\\" METHOD: configure\n.TP\n\\fBplace configure \\fIwindow \\fR?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the geometry options of the content given by\n\\fIwindow\\fR. If no \\fIoption\\fR is specified, this command returns a\nlist describing the available options (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given option(s) to have the given value(s); in this case\nthe command returns an empty string.\n.RS\n.PP\nThe following \\fIoption\\-value\\fR pairs are supported:\n.\\\" OPTION: -anchor\n.TP\n\\fB\\-anchor \\fIwhere\\fR\n.\n\\fIWhere\\fR specifies which point of \\fIwindow\\fR is to be positioned\nat the (x,y) location selected by the \\fB\\-x\\fR, \\fB\\-y\\fR,\n\\fB\\-relx\\fR, and \\fB\\-rely\\fR options.\nThe anchor point is in terms of the outer area of \\fIwindow\\fR\nincluding its border, if any.\nThus if \\fIwhere\\fR is \\fBse\\fR then the lower-right corner of\n\\fIwindow\\fR's border will appear at the given (x,y) location\nin the container.\nThe anchor position defaults to \\fBnw\\fR.\n.\\\" OPTION: -bordermode\n.TP\n\\fB\\-bordermode \\fImode\\fR\n.\n\\fIMode\\fR determines the degree to which borders within the\ncontainer are used in determining the placement of the content.\nThe default and most common value is \\fBinside\\fR.\nIn this case the placer considers the area of the container to\nbe the innermost area of the container, inside any border:\nan option of \\fB\\-x 0\\fR corresponds to an x-coordinate just\ninside the border and an option of \\fB\\-relwidth 1.0\\fR\nmeans \\fIwindow\\fR will fill the area inside the container's\nborder.\n.RS\n.PP\nIf \\fImode\\fR is \\fBoutside\\fR then the placer considers\nthe area of the container to include its border;\nthis mode is typically used when placing \\fIwindow\\fR\noutside its container, as with the options \\fB\\-x 0 \\-y 0 \\-anchor ne\\fR.\nLastly, \\fImode\\fR may be specified as \\fBignore\\fR, in which\ncase borders are ignored: the area of the container is considered\nto be its official X area, which includes any internal border but\nno external border. A bordermode of \\fBignore\\fR is probably\nnot very useful.\n.RE\n.\\\" OPTION: -height\n.TP\n\\fB\\-height \\fIsize\\fR\n.\n\\fISize\\fR specifies the height for \\fIwindow\\fR in screen units\n(i.e. any of the forms accepted by \\fBTk_GetPixels\\fR).\nThe height will be the outer dimension of \\fIwindow\\fR including its\nborder, if any.\nIf \\fIsize\\fR is an empty string, or if no \\fB\\-height\\fR or\n\\fB\\-relheight\\fR option is specified, then the height requested\ninternally by the window will be used.\n.\\\" OPTION: -in\n.TP\n\\fB\\-in \\fIcontainer\\fR\n.\n\\fIContainer\\fR specifies the path name of the window relative\nto which \\fIwindow\\fR is to be placed.\n\\fIContainer\\fR must either be \\fIwindow\\fR's parent or a descendant\nof \\fIwindow\\fR's parent.\nIn addition, \\fIcontainer\\fR and \\fIwindow\\fR must both be descendants\nof the same top-level window.\nThese restrictions are necessary to guarantee\nthat \\fIwindow\\fR is visible whenever \\fIcontainer\\fR is visible.\nIf this option is not specified then the other window defaults to\n\\fIwindow\\fR's parent.\n.\\\" OPTION: -relheight\n.TP\n\\fB\\-relheight \\fIsize\\fR\n.\n\\fISize\\fR specifies the height for \\fIwindow\\fR.\nIn this case the height is specified as a floating-point number\nrelative to the height of the container: 0.5 means \\fIwindow\\fR will\nbe half as high as the container, 1.0 means \\fIwindow\\fR will have\nthe same height as the container, and so on.\nIf both \\fB\\-height\\fR and \\fB\\-relheight\\fR are specified for a content,\ntheir values are summed. For example, \\fB\\-relheight 1.0 \\-height \\-2\\fR\nmakes the content 2 pixels shorter than the container.\n.\\\" OPTION: -relwidth\n.TP\n\\fB\\-relwidth \\fIsize\\fR\n.\n\\fISize\\fR specifies the width for \\fIwindow\\fR.\nIn this case the width is specified as a floating-point number\nrelative to the width of the container: 0.5 means \\fIwindow\\fR will\nbe half as wide as the container, 1.0 means \\fIwindow\\fR will have\nthe same width as the container, and so on.\nIf both \\fB\\-width\\fR and \\fB\\-relwidth\\fR are specified for a content,\ntheir values are summed. For example, \\fB\\-relwidth 1.0 \\-width 5\\fR\nmakes the content 5 pixels wider than the container.\n.\\\" OPTION: -relx\n.TP\n\\fB\\-relx \\fIlocation\\fR\n.\n\\fILocation\\fR specifies the x-coordinate within the container window\nof the anchor point for \\fIwindow\\fR.\nIn this case the location is specified in a relative fashion\nas a floating-point number: 0.0 corresponds to the left edge\nof the container and 1.0 corresponds to the right edge of the container.\n\\fILocation\\fR need not be in the range 0.0\\-1.0.\nIf both \\fB\\-x\\fR and \\fB\\-relx\\fR are specified for a content\nthen their values are summed. For example, \\fB\\-relx 0.5 \\-x \\-2\\fR\npositions the left edge of the content 2 pixels to the left of the\ncenter of its container.\n.\\\" OPTION: -rely\n.TP\n\\fB\\-rely \\fIlocation\\fR\n.\n\\fILocation\\fR specifies the y-coordinate within the container window\nof the anchor point for \\fIwindow\\fR.\nIn this case the value is specified in a relative fashion\nas a floating-point number: 0.0 corresponds to the top edge\nof the container and 1.0 corresponds to the bottom edge of the container.\n\\fILocation\\fR need not be in the range 0.0\\-1.0.\nIf both \\fB\\-y\\fR and \\fB\\-rely\\fR are specified for a content\nthen their values are summed. For example, \\fB\\-rely 0.5 \\-x 3\\fR\npositions the top edge of the content 3 pixels below the\ncenter of its container.\n.\\\" OPTION: -width\n.TP\n\\fB\\-width \\fIsize\\fR\n.\n\\fISize\\fR specifies the width for \\fIwindow\\fR in screen units\n(i.e. any of the forms accepted by \\fBTk_GetPixels\\fR).\nThe width will be the outer width of \\fIwindow\\fR including its\nborder, if any.\nIf \\fIsize\\fR is an empty string, or if no \\fB\\-width\\fR\nor \\fB\\-relwidth\\fR option is specified, then the width requested\ninternally by the window will be used.\n.\\\" OPTION: -x\n.TP\n\\fB\\-x \\fIlocation\\fR\n.\n\\fILocation\\fR specifies the x-coordinate within the container window\nof the anchor point for \\fIwindow\\fR.\nThe location is specified in screen units (i.e. any of the forms\naccepted by \\fBTk_GetPixels\\fR) and need not lie within the bounds\nof the container window.\n.\\\" OPTION: -y\n.TP\n\\fB\\-y \\fIlocation\\fR\n.\n\\fILocation\\fR specifies the y-coordinate within the container window\nof the anchor point for \\fIwindow\\fR.\nThe location is specified in screen units (i.e. any of the forms\naccepted by \\fBTk_GetPixels\\fR) and need not lie within the bounds\nof the container window.\n.PP\nIf the same value is specified separately with\ntwo different options, such as \\fB\\-x\\fR and \\fB\\-relx\\fR, then\nthe most recent option is used and the older one is ignored.\n.RE\n.\\\" METHOD: content\n.TP\n\\fBplace content \\fIwindow\\fR\n.\nReturns a list of all the content windows for which \\fIwindow\\fR is the\ncontainer. If there is no content for \\fIwindow\\fR then an empty string\nis returned.\n.\\\" METHOD: forget\n.TP\n\\fBplace forget \\fIwindow\\fR\n.\nCauses the placer to stop managing the geometry of \\fIwindow\\fR. As a\nside effect of this command \\fIwindow\\fR will be unmapped so that it\ndoes not appear on the screen. If \\fIwindow\\fR is not currently managed\nby the placer then the command has no effect. This command returns an\nempty string.\n.\\\" METHOD: info\n.TP\n\\fBplace info \\fIwindow\\fR\n.\nReturns a list giving the current configuration of \\fIwindow\\fR.\nThe list consists of \\fIoption\\-value\\fR pairs in exactly the\nsame form as might be specified to the \\fBplace configure\\fR\ncommand.\n.\\\" METHOD: slaves\n.TP\n\\fBplace slaves \\fIwindow\\fR\n.\nSynonym for \\fBplace content \\fIwindow\\fR.\n.PP\nIf the configuration of a window has been retrieved with\n\\fBplace info\\fR, that configuration can be restored later by\nfirst using \\fBplace forget\\fR to erase any existing information\nfor the window and then invoking \\fBplace configure\\fR with\nthe saved information.\n.SH \"FINE POINTS\"\n.PP\nIt is not necessary for the container window to be the parent\nof the content window.\nThis feature is useful in at least two situations.\nFirst, for complex window layouts it means you can create a\nhierarchy of subwindows whose only purpose\nis to assist in the layout of the parent.\nThe\n.QW \"real children\"\nof the parent (i.e. the windows that\nare significant for the application's user interface) can be\nchildren of the parent yet be placed inside the windows\nof the geometry-management hierarchy.\nThis means that the path names of the\n.QW \"real children\"\ndo not reflect the geometry-management hierarchy and users\ncan specify options for the real children\nwithout being aware of the structure of the geometry-management\nhierarchy.\n.PP\nA second reason for having a container different than the content's\nparent is to tie two siblings together.\nFor example, the placer can be used to force a window always to\nbe positioned centered just below one of its\nsiblings by specifying the configuration\n.CS\n\\fB\\-in \\fIsibling\\fB \\-relx 0.5 \\-rely 1.0 \\-anchor n \\-bordermode outside\\fR\n.CE\nWhenever the sibling is repositioned in the future, the content\nwill be repositioned as well.\n.PP\nUnlike many other geometry managers (such as the packer)\nthe placer does not make any attempt to manipulate the geometry of\nthe container windows or the parents of content windows (i.e. it does not\nset their requested sizes).\nTo control the sizes of these windows, make them windows like\nframes and canvases that provide configuration options for this purpose.\n.SH EXAMPLE\n.PP\nMake the label occupy the middle bit of the toplevel, no matter how it\nis resized:\n.CS\nlabel .l -text \"In the\\enMiddle!\" -bg black -fg white\n\\fBplace\\fR .l -relwidth .3 -relx .35 -relheight .3 -rely .35\n.CE\n.SH \"SEE ALSO\"\ngrid(n), pack(n)\n.SH KEYWORDS\ngeometry manager, height, location, container, place, rubber sheet,\ncontent, width\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/popup.n", "content": "'\\\"\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk_popup n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk_popup \\- Post a popup menu\n.SH SYNOPSIS\n\\fBtk_popup \\fImenu x y \\fR?\\fIentry\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThis procedure posts a menu at a given position on the screen and\nconfigures Tk so that the menu and its cascaded children can be\ntraversed with the mouse or the keyboard.\n\\fIMenu\\fR is the name of a menu widget and \\fIx\\fR and \\fIy\\fR\nare the root coordinates at which to display the menu.\nIf \\fIentry\\fR is omitted or an empty string, the\nmenu's upper left corner is positioned at the given point.\nOtherwise \\fIentry\\fR gives the index of an entry in \\fImenu\\fR and\nthe menu will be positioned so that the entry is positioned over\nthe given point.\n.SH EXAMPLE\n.PP\nHow to attach a simple popup menu to a widget.\n.CS\n# Create a menu\nset m [menu .popupMenu]\n$m add command -label \"Example 1\" -command bell\n$m add command -label \"Example 2\" -command bell\n\n# Create something to attach it to\npack [label .l -text \"Click me!\"]\n\n# Arrange for the menu to pop up when the label is clicked\nbind .l {\\fBtk_popup\\fR .popupMenu %X %Y}\n.CE\n.SH \"SEE ALSO\"\nbind(n), menu(n), tk_optionMenu(n)\n.SH KEYWORDS\nmenu, popup\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/print.n", "content": ".\\\" Text automatically generated by txt2man\n'\\\"\n'\\\" Copyright (c) 2021 Kevin Walzer\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n\n.TH tk print n \"\" Tk \"Tk Built-in Commands\"\n.so man.macros\n.SH NAME\nprint \\- Print canvas and text widgets using native dialogs and APIs.\n.SH SYNOPSIS\n\\fBtk print \\fIwindow\\fR\n.\n.SH DESCRIPTION\n.PP\nThe \\fBtk print\\fR command posts a dialog that allows users to print output\nfrom the \\fBcanvas\\fR and \\fBtext\\fR widgets. The printing will be done using\nplatform-native APIs and dialogs where available.\n.PP\nThe \\fBcanvas\\fR widget has long supported PostScript export and both\nPostScript and text files can be sent directly to a printer on Unix-like\nsystems using the\n.QW \"lp\"\nand\n.QW \"lpr\"\nUnix commands, and the \\fBtk print\\fR command does not supersede that\nfunctionality; it builds on it. The \\fBtk print\\fR command is a fuller\nimplementation that uses native dialogs on macOS and Windows, and a Tk-based\ndialog that provides parallel functionality on X11.\n.SH PLATFORM NOTES\n.TP\n\\fBmacOS\\fR\n.\nThe Mac implementation uses native print dialogs and relies on the underlying\nCommon Unix Printing System (CUPS) to render text output from the text widget\nand PDF conversion of the canvas data to the printer or to a PDF file.\n.TP\n\\fBWindows\\fR\n.\nThe Windows implementation is based on the GDI (Graphics Device Interface)\nAPI. Because there are slight differences in how GDI and Tk's \\fBcanvas\\fR\nwidget display graphics, printed output from the \\fBcanvas\\fR on Windows may\nnot be identical to screen rendering.\n.TP\n\\fBX11\\fR\n.\nThe X11 implementation uses a Tk GUI to configure print jobs for sending to a\nprinter via the\n.QW \"lpr\"\nor\n.QW \"lp\"\ncommands or via the Common Unix Printing System (CUPS) API if libcups is installed. While these commands have a large number of parameters for\nconfiguring print jobs, printers vary widely in how they support these\nparameters. As a result, only printer selection and number of copies are\nconfigured as arguments to the print command; many aspects of print rendering,\nsuch as grayscale or color for the canvas, are instead configured when\nPostScript is generated.\n.SH \"SEE ALSO\"\ncanvas(n), text(n), tk(n)\n.SH KEYWORDS\nprint, output, graphics, text, canvas\n" }, { "path": "doc/radiobutton.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH radiobutton n 4.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nradiobutton \\- Create and manipulate 'radiobutton' pick-one widgets\n.SH SYNOPSIS\n\\fBradiobutton\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-activebackground\t\\-disabledforeground\t\\-padx\n\\-activeforeground\t\\-font\t\\-pady\n\\-anchor\t\\-foreground\t\\-relief\n\\-background\t\\-highlightbackground\t\\-takefocus\n\\-bitmap\t\\-highlightcolor\t\\-text\n\\-borderwidth\t\\-highlightthickness\t\\-textvariable\n\\-compound\t\\-image\t\\-underline\n\\-cursor\t\\-justify\t\\-wraplength\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-command command Command\nSpecifies a Tcl command to associate with the button. This command\nis typically invoked when mouse button 1 is released over the button\nwindow. The button's global variable (\\fB\\-variable\\fR option) will\nbe updated before the command is invoked.\n.OP \\-height height Height\nSpecifies a desired height for the button.\nIf an image or bitmap is being displayed in the button then the value is in\nscreen units (i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR);\nfor text it is in lines of text.\nIf this option is not specified, the button's desired height is computed\nfrom the size of the image or bitmap or text being displayed in it.\n.OP \\-indicatoron indicatorOn IndicatorOn\nSpecifies whether or not the indicator should be drawn. Must be a\nproper boolean value. If false, the \\fB\\-relief\\fR option is\nignored and the widget's relief is always sunken if the widget is\nselected and raised otherwise.\n.OP \\-offrelief offRelief OffRelief\nSpecifies the relief for the checkbutton when the indicator is not drawn and\nthe checkbutton is off. The default value is\n.QW raised .\nBy setting this option to\n.QW flat\nand setting \\fB\\-indicatoron\\fR to false and \\fB\\-overrelief\\fR to\n.QW raised ,\nthe effect is achieved\nof having a flat button that raises on mouse-over and which is\ndepressed when activated. This is the behavior typically exhibited by\nthe Align-Left, Align-Right, and Center radiobuttons on the toolbar of a\nword-processor, for example.\n.OP \\-overrelief overRelief OverRelief\nSpecifies an alternative relief for the radiobutton, to be used when the\nmouse cursor is over the widget. This option can be used to make\ntoolbar buttons, by configuring \\fB\\-relief flat \\-overrelief\nraised\\fR. If the value of this option is the empty string, then no\nalternative relief is used when the mouse cursor is over the radiobutton.\nThe empty string is the default value.\n.OP \\-selectcolor selectColor Background\nSpecifies a background color to use when the button is selected.\nIf \\fBindicatorOn\\fR is true then the color is used as the background for\nthe indicator regardless of the select state.\nIf \\fB\\-indicatoron\\fR is false, this color is used as the background for the\nentire widget, in place of \\fB\\-background\\fR or \\fB\\-activeBackground\\fR,\nwhenever the widget is selected.\nIf specified as an empty string then no special color is used for\ndisplaying when the widget is selected.\n.OP \\-selectimage selectImage SelectImage\nSpecifies an image to display (in place of the \\fB\\-image\\fR option)\nwhen the radiobutton is selected.\nThis option is ignored unless the \\fB\\-image\\fR option has been\nspecified.\n.OP \\-state state State\nSpecifies one of three states for the radiobutton: \\fBnormal\\fR, \\fBactive\\fR,\nor \\fBdisabled\\fR. In normal state the radiobutton is displayed using the\n\\fB\\-foreground\\fR and \\fB\\-background\\fR options. The active state is\ntypically used when the pointer is over the radiobutton. In active state\nthe radiobutton is displayed using the \\fB\\-activeforeground\\fR and\n\\fB\\-activebackground\\fR options. Disabled state means that the radiobutton\nshould be insensitive: the default bindings will refuse to activate\nthe widget and will ignore mouse button presses.\nIn this state the \\fB\\-disabledforeground\\fR and\n\\fB\\-background\\fR options determine how the radiobutton is displayed.\n.OP \\-tristateimage tristateImage TristateImage\nSpecifies an image to display (in place of the \\fB\\-image\\fR option)\nwhen the radiobutton is selected.\nThis option is ignored unless the \\fB\\-image\\fR option has been\nspecified.\n.OP \\-tristatevalue tristateValue Value\nSpecifies the value that causes the radiobutton to display the multi-value\nselection, also known as the tri-state mode. Defaults to\n.QW \"\" .\n.OP \\-value value Value\nSpecifies value to store in the button's associated variable whenever\nthis button is selected.\n.OP \\-variable variable Variable\nSpecifies the name of a global variable to set whenever this button is\nselected. Changes in this variable also cause the button to select\nor deselect itself.\nDefaults to the value \\fBselectedButton\\fR.\n.OP \\-width width Width\nSpecifies a desired width for the button.\nIf an image or bitmap is being displayed in the button, the value is in\nscreen units (i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR);\nfor text it is in characters.\nIf this option is not specified, the button's desired width is computed\nfrom the size of the image or bitmap or text being displayed in it.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBradiobutton\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a radiobutton widget.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the radiobutton such as its colors, font,\ntext, and initial relief. The \\fBradiobutton\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nA radiobutton is a widget that displays a textual string, bitmap or image\nand a diamond or circle called an \\fIindicator\\fR.\nIf text is displayed, it must all be in a single font, but it\ncan occupy multiple lines on the screen (if it contains newlines\nor if wrapping occurs because of the \\fB\\-wraplength\\fR option) and\none of the characters may optionally be underlined using the\n\\fB\\-underline\\fR option. A radiobutton has\nall of the behavior of a simple button: it can display itself in either\nof three different ways, according to the \\fB\\-state\\fR option;\nit can be made to appear\nraised, sunken, or flat; it can be made to flash; and it invokes\na Tcl command whenever mouse button 1 is clicked over the\ncheck button.\n.PP\nIn addition, radiobuttons can be \\fIselected\\fR.\nIf a radiobutton is selected, the indicator is normally\ndrawn with a selected appearance, and\na Tcl variable associated with the radiobutton is set to a particular\nvalue (normally 1).\nUnder Unix, the indicator is drawn with a sunken relief and a special\ncolor. Under Windows, the indicator is drawn with a round mark inside.\nIf the radiobutton is not selected, then the indicator is drawn with a\ndeselected appearance, and the associated variable is\nset to a different value (typically 0).\nThe indicator is drawn without a round mark inside.\nTypically, several radiobuttons share a single variable and the\nvalue of the variable indicates which radiobutton is to be selected.\nWhen a radiobutton is selected it sets the value of the variable to\nindicate that fact; each radiobutton also monitors the value of\nthe variable and automatically selects and deselects itself when the\nvariable's value changes.\nIf the variable's value matches the \\fB\\-tristatevalue\\fR, then the radiobutton\nis drawn using the tri-state mode. This mode is used to indicate mixed or\nmultiple values. (This is used when the radiobutton represents the state\nof multiple items.)\nBy default the variable \\fBselectedButton\\fR\nis used; its contents give the name of the button that is\nselected, or the empty string if no button associated with that\nvariable is selected.\nThe name of the variable for a radiobutton,\nplus the variable to be stored into it, may be modified with options\non the command line or in the option database.\nConfiguration options may also be used to modify the way the\nindicator is displayed (or whether it is displayed at all).\nBy default a radiobutton is configured to select itself on button clicks.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBradiobutton\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for radiobutton widgets:\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBradiobutton\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBradiobutton\\fR\ncommand.\n.\\\" METHOD: deselect\n.TP\n\\fIpathName \\fBdeselect\\fR\n.\nDeselects the radiobutton and sets the associated variable to an\nempty string.\nIf this radiobutton was not currently selected, the command has\nno effect.\n.\\\" METHOD: flash\n.TP\n\\fIpathName \\fBflash\\fR\n.\nFlashes the radiobutton. This is accomplished by redisplaying the radiobutton\nseveral times, alternating between active and normal colors. At\nthe end of the flash the radiobutton is left in the same normal/active\nstate as when the command was invoked.\nThis command is ignored if the radiobutton's state is \\fBdisabled\\fR.\n.\\\" METHOD: invoke\n.TP\n\\fIpathName \\fBinvoke\\fR\n.\nDoes just what would have happened if the user invoked the radiobutton\nwith the mouse: selects the button and invokes\nits associated Tcl command, if there is one.\nThe return value is the return value from the Tcl command, or an\nempty string if there is no command associated with the radiobutton.\nThis command is ignored if the radiobutton's state is \\fBdisabled\\fR.\n.\\\" METHOD: select\n.TP\n\\fIpathName \\fBselect\\fR\n.\nSelects the radiobutton and sets the associated variable to the\nvalue corresponding to this widget.\n.SH BINDINGS\n.PP\nTk automatically creates class bindings for radiobuttons that give them\nthe following default behavior:\n.IP [1]\nOn Unix systems, a radiobutton activates whenever the mouse passes\nover it and deactivates whenever the mouse leaves the radiobutton. On\nMac and Windows systems, when mouse button 1 is pressed over a\nradiobutton, the button activates whenever the mouse pointer is inside\nthe button, and deactivates whenever the mouse pointer leaves the\nbutton.\n.IP [2]\nWhen mouse button 1 is pressed over a radiobutton it is invoked (it\nbecomes selected and the command associated with the button is\ninvoked, if there is one).\n.IP [3]\nWhen a radiobutton has the input focus, the space key causes the radiobutton\nto be invoked.\n.PP\nIf the radiobutton's state is \\fBdisabled\\fR then none of the above\nactions occur: the radiobutton is completely non-responsive.\n.PP\nThe behavior of radiobuttons can be changed by defining new bindings for\nindividual widgets or by redefining the class bindings.\n.SH \"SEE ALSO\"\ncheckbutton(n), labelframe(n), listbox(n), options(n), scale(n),\nttk::radiobutton(n)\n.SH KEYWORDS\nradiobutton, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/raise.n", "content": "'\\\"\n'\\\" Copyright (c) 1990 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH raise n 3.3 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nraise \\- Change a window's position in the stacking order\n.SH SYNOPSIS\n\\fBraise \\fIwindow \\fR?\\fIaboveThis\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nIf the \\fIaboveThis\\fR argument is omitted then the command raises\n\\fIwindow\\fR so that it is above all of its siblings in the stacking\norder (it will not be obscured by any siblings and will obscure\nany siblings that overlap it).\nIf \\fIaboveThis\\fR is specified then it must be the path name of\na window that is either a sibling of \\fIwindow\\fR or the descendant\nof a sibling of \\fIwindow\\fR.\nIn this case the \\fBraise\\fR command will insert\n\\fIwindow\\fR into the stacking order just above \\fIaboveThis\\fR\n(or the ancestor of \\fIaboveThis\\fR that is a sibling of \\fIwindow\\fR);\nthis could end up either raising or lowering \\fIwindow\\fR.\n.PP\nAll \\fBtoplevel\\fR windows may be restacked with respect to each\nother, whatever their relative path names, but the window manager is\nnot obligated to strictly honor requests to restack.\n.PP\nOn macOS raising an iconified \\fBtoplevel\\fR window causes it to be\ndeiconified.\n.SH EXAMPLE\n.PP\nMake a button appear to be in a sibling frame that was created after\nit. This is is often necessary when building GUIs in the style where\nyou create your activity widgets first before laying them out on the\ndisplay:\n.CS\nbutton .b -text \"Hi there!\"\npack [frame .f -background blue]\npack [label .f.l1 -text \"This is above\"]\npack .b -in .f\npack [label .f.l2 -text \"This is below\"]\n\\fBraise\\fR .b\n.CE\n.SH \"SEE ALSO\"\nlower(n)\n.SH KEYWORDS\nobscure, raise, stacking order\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/scale.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH scale n 4.1 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nscale \\- Create and manipulate 'scale' value-controlled slider widgets\n.SH SYNOPSIS\n\\fBscale\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-activebackground\t\\-foreground\t\\-relief\n\\-background\t\\-highlightbackground\t\\-repeatdelay\n\\-borderwidth\t\\-highlightcolor\t\\-repeatinterval\n\\-cursor\t\\-highlightthickness\t\\-takefocus\n\\-font\t\\-orient\t\\-troughcolor\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-bigincrement bigIncrement BigIncrement\nSome interactions with the scale cause its value to change by\n.QW large\nincrements; this option specifies the size of the\nlarge increments. If specified as 0, the large increments default\nto 1/10 the range of the scale.\n.OP \\-command command Command\nSpecifies the prefix of a Tcl command to invoke whenever the scale's\nvalue is changed via a widget command.\nThe actual command consists\nof this option followed by a space and a real number indicating the\nnew value of the scale.\n.OP \\-digits digits Digits\nAn integer specifying how many significant digits should be retained\nwhen converting the value of the scale to a string.\nIf the number is negative or zero, then the scale picks\nthe smallest value that guarantees that every possible slider\nposition prints as a different string.\n.OP \\-from from From\nA real value corresponding to the left or top end of the scale.\n.OP \\-label label Label\nA string to display as a label for the scale. For\nvertical scales the label is displayed just to the right of the\ntop end of the scale. For horizontal scales the label is displayed\njust above the left end of the scale. If the option is specified\nas an empty string, no label is displayed.\n.OP \\-length length Length\nSpecifies the desired long dimension of the scale in screen units\n(i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR).\nFor vertical scales this is the scale's height; for horizontal scales\nit is the scale's width.\n.OP \\-resolution resolution Resolution\nA real value specifying the resolution for the scale.\nIf this value is greater than zero then the scale's value will always be\nrounded to an even multiple of this value, as will\nthe endpoints of the scale. If the value is negative then no\nrounding occurs. Defaults to 1 (i.e., the value will be integral).\n.OP \\-showvalue showValue ShowValue\nSpecifies a boolean value indicating whether or not the current\nvalue of the scale is to be displayed.\n.OP \\-sliderlength sliderLength SliderLength\nSpecifies the size of the slider, measured in screen units along the slider's\nlong dimension. The value may be specified in any of the forms acceptable\nto \\fBTk_GetPixels\\fR.\n.OP \\-sliderrelief sliderRelief SliderRelief\nSpecifies the relief to use when drawing the slider, such as \\fBraised\\fR\nor \\fBsunken\\fR.\n.OP \\-state state State\nSpecifies one of three states for the scale: \\fBnormal\\fR,\n\\fBactive\\fR, or \\fBdisabled\\fR.\nIf the scale is disabled then the value may not be changed and the scale\nwill not activate.\nIf the scale is active, the slider is displayed using the color\nspecified by the \\fB\\-activebackground\\fR option.\n.OP \\-tickinterval tickInterval TickInterval\nMust be a real value.\nDetermines the spacing between numerical\ntick marks displayed below or to the left of the slider. The values will all\nbe displayed with the same number of decimal places, which will be enough to\nensure they are all accurate to within 20% of a tick interval.\nIf 0, no tick marks will be displayed.\n.OP \\-to to To\nSpecifies a real value corresponding\nto the right or bottom end of the scale.\nThis value may be either less than or greater than the \\fB\\-from\\fR option.\n.OP \\-variable variable Variable\nSpecifies the name of a global variable to link to the scale. Whenever the\nvalue of the variable changes, the scale will update to reflect this\nvalue.\nWhenever the scale is manipulated interactively, the variable\nwill be modified to reflect the scale's new value.\n.OP \\-width width Width\nSpecifies the desired narrow dimension of the scale in screen units\n(i.e. any of the forms acceptable to \\fBTk_GetPixels\\fR).\nFor vertical scales this is the scale's width; for horizontal scales\nthis is the scale's height.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBscale\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a scale widget.\nAdditional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the scale such as its colors, orientation,\nand relief. The \\fBscale\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nA scale is a widget that displays a rectangular \\fItrough\\fR and a\nsmall \\fIslider\\fR. The trough corresponds to a range\nof real values (determined by the \\fB\\-from\\fR, \\fB\\-to\\fR, and\n\\fB\\-resolution\\fR options),\nand the position of the slider selects a particular real value.\nThe slider's position (and hence the scale's value) may be adjusted\nwith the mouse or keyboard as described in the \\fBBINDINGS\\fR\nsection below. Whenever the scale's value is changed, a Tcl\ncommand is invoked (using the \\fB\\-command\\fR option) to notify\nother interested widgets of the change.\nIn addition, the value\nof the scale can be linked to a Tcl variable (using the \\fB\\-variable\\fR\noption), so that changes in either are reflected in the other.\n.PP\nThree annotations may be displayed in a scale widget: a label\nappearing at the top right of the widget (top left for horizontal\nscales), a number displayed just to the left of the slider\n(just above the slider for horizontal scales), and a collection\nof numerical tick marks just to the left of the current value\n(just below the trough for horizontal scales). Each of these three\nannotations may be enabled or disabled using the\nconfiguration options.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBscale\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for scale widgets:\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBscale\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBscale\\fR\ncommand.\n.\\\" METHOD: coords\n.TP\n\\fIpathName \\fBcoords \\fR?\\fIvalue\\fR?\n.\nReturns a list whose elements are the x and y coordinates of\nthe point along the centerline of the trough that corresponds\nto \\fIvalue\\fR.\nIf \\fIvalue\\fR is omitted then the scale's current value is used.\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget\\fR ?\\fIx y\\fR?\n.\nIf \\fIx\\fR and \\fIy\\fR are omitted, returns the current value\nof the scale. If \\fIx\\fR and \\fIy\\fR are specified, they give\npixel coordinates within the widget; the command returns\nthe scale value corresponding to the given pixel.\nOnly one of \\fIx\\fR or \\fIy\\fR is used: for horizontal scales\n\\fIy\\fR is ignored, and for vertical scales \\fIx\\fR is ignored.\n.\\\" METHOD: identify\n.TP\n\\fIpathName \\fBidentify \\fIx y\\fR\n.\nReturns a string indicating what part of the scale lies under\nthe coordinates given by \\fIx\\fR and \\fIy\\fR.\nA return value of \\fBslider\\fR means that the point is over\nthe slider; \\fBtrough1\\fR means that the point is over the\nportion of the slider above or to the left of the slider;\nand \\fBtrough2\\fR means that the point is over the portion\nof the slider below or to the right of the slider.\nIf the point is not over one of these elements, an empty string\nis returned.\n.\\\" METHOD: set\n.TP\n\\fIpathName \\fBset \\fIvalue\\fR\n.\nThis command is invoked to change the current value of the scale,\nand hence the position at which the slider is displayed. \\fIValue\\fR\ngives the new value for the scale.\nThe command has no effect if the scale is disabled.\n.SH BINDINGS\n.PP\nTk automatically creates class bindings for scales that give them\nthe following default behavior.\nWhere the behavior is different for vertical and horizontal scales,\nthe horizontal behavior is described in parentheses.\n.IP [1]\nIf button 1 is pressed in the trough, the scale's value will\nbe incremented or decremented by the value of the \\fB\\-resolution\\fR\noption so that the slider moves in the direction of the cursor.\nIf the button is held down, the action auto-repeats.\n.IP [2]\nIf button 1 is pressed over the slider, the slider can be dragged\nwith the mouse.\n.IP [3]\nIf button 1 is pressed in the trough with the Control key down,\nthe slider moves all the way to the end of its range, in the\ndirection towards the mouse cursor.\n.IP [4]\nIf button 2 is pressed, the scale's value is set to the mouse\nposition. If the mouse is dragged with button 2 down, the scale's\nvalue changes with the drag.\n.IP [5]\nThe Up and Left keys move the slider up (left) by the value\nof the \\fB\\-resolution\\fR option.\n.IP [6]\nThe Down and Right keys move the slider down (right) by the value\nof the \\fB\\-resolution\\fR option.\n.IP [7]\nControl-Up and Control-Left move the slider up (left) by the\nvalue of the \\fB\\-bigincrement\\fR option.\n.IP [8]\nControl-Down and Control-Right move the slider down (right) by the\nvalue of the \\fB\\-bigincrement\\fR option.\n.IP [9]\nHome moves the slider to the top (left) end of its range.\n.IP [10]\nEnd moves the slider to the bottom (right) end of its range.\n.PP\nIf the scale is disabled using the \\fB\\-state\\fR option then\nnone of the above bindings have any effect.\n.PP\nThe behavior of scales can be changed by defining new bindings for\nindividual widgets or by redefining the class bindings.\n.SH \"SEE ALSO\"\nttk::scale(n)\n.SH KEYWORDS\nscale, slider, trough, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/scrollbar.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH scrollbar n 4.1 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nscrollbar \\- Create and manipulate 'scrollbar' scrolling control and indicator widgets\n.SH SYNOPSIS\n\\fBscrollbar\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-activebackground\t\\-highlightcolor\t\\-repeatdelay\n\\-background\t\\-highlightthickness\t\\-repeatinterval\n\\-borderwidth\t\\-jump\t\\-takefocus\n\\-cursor\t\\-orient\t\\-troughcolor\n\\-highlightbackground\t\\-relief\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-activerelief activeRelief ActiveRelief\nSpecifies the relief to use when displaying the element that is\nactive, if any.\nElements other than the active element are always displayed with\na raised relief.\n.OP \\-command command Command\nSpecifies the prefix of a Tcl command to invoke to change the view\nin the widget associated with the scrollbar. When a user requests\na view change by manipulating the scrollbar, a Tcl command is\ninvoked. The actual command consists of this option followed by\nadditional information as described later. This option almost always has\na value such as \\fB.t xview\\fR or \\fB.t yview\\fR, consisting of the\nname of a widget and either \\fBxview\\fR (if the scrollbar is for\nhorizontal scrolling) or \\fByview\\fR (for vertical scrolling).\nAll scrollable widgets have \\fBxview\\fR and \\fByview\\fR commands\nthat take exactly the additional arguments appended by the scrollbar\nas described in \\fBSCROLLING COMMANDS\\fR below.\n.OP \\-elementborderwidth elementBorderWidth BorderWidth\nSpecifies the width of borders drawn around the internal elements\nof the scrollbar (the two arrows and the slider). The value may\nhave any of the forms acceptable to \\fBTk_GetPixels\\fR.\nIf this value is the empty string (the default), the value of\nthe \\fB\\-borderwidth\\fR option is used in its place.\n.OP \\-width width Width\nSpecifies the desired narrow dimension of the scrollbar window,\nnot including 3-D border, if any. For vertical\nscrollbars this will be the width and for horizontal scrollbars\nthis will be the height.\nThe value may have any of the forms acceptable to \\fBTk_GetPixels\\fR.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBscrollbar\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a scrollbar widget.\nAdditional options, described above, may be specified on the command\nline or in the option database to configure aspects of the scrollbar\nsuch as its colors, orientation, and relief.\nThe \\fBscrollbar\\fR command returns its \\fIpathName\\fR argument.\nAt the time this command is invoked, there must not exist a window\nnamed \\fIpathName\\fR, but \\fIpathName\\fR's parent must exist.\n.PP\nA scrollbar is a widget that displays two arrows, one at each end of\nthe scrollbar, and a \\fIslider\\fR in the middle portion of the\nscrollbar.\nIt provides information about what is visible in an \\fIassociated window\\fR\nthat displays a document of some sort (such as a file being edited or\na drawing).\nThe position and size of the slider indicate which portion of the\ndocument is visible in the associated window. For example, if the\nslider in a vertical scrollbar covers the top third of the area\nbetween the two arrows, it means that the associated window displays\nthe top third of its document.\n.PP\nScrollbars can be used to adjust the view in the associated window\nby clicking or dragging with the mouse. See the \\fBBINDINGS\\fR section\nbelow for details.\n.SH \"ELEMENTS\"\n.PP\nA scrollbar displays five elements, which are referred to in the\nwidget commands for the scrollbar:\n.IP \\fBarrow1\\fR 10\nThe top or left arrow in the scrollbar.\n.IP \\fBtrough1\\fR 10\nThe region between the slider and \\fBarrow1\\fR.\n.IP \\fBslider\\fR 10\nThe rectangle that indicates what is visible in the associated widget.\n.IP \\fBtrough2\\fR 10\nThe region between the slider and \\fBarrow2\\fR.\n.IP \\fBarrow2\\fR 10\nThe bottom or right arrow in the scrollbar.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBscrollbar\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for scrollbar widgets:\n.\\\" METHOD: activate\n.TP\n\\fIpathName \\fBactivate \\fR?\\fIelement\\fR?\n.\nMarks the element indicated by \\fIelement\\fR as active, which\ncauses it to be displayed as specified by the \\fB\\-activebackground\\fR\nand \\fB\\-activerelief\\fR options.\nThe only element values understood by this command are \\fBarrow1\\fR,\n\\fBslider\\fR, or \\fBarrow2\\fR.\nIf any other value is specified then no element of the scrollbar\nwill be active.\nIf \\fIelement\\fR is not specified, the command returns\nthe name of the element that is currently active, or an empty string\nif no element is active.\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget \\fIoption\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBscrollbar\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBscrollbar\\fR\ncommand.\n.\\\" METHOD: delta\n.TP\n\\fIpathName \\fBdelta \\fIdeltaX deltaY\\fR\n.\nReturns a real number indicating the fractional change in\nthe scrollbar setting that corresponds to a given change\nin slider position. For example, if the scrollbar is horizontal,\nthe result indicates how much the scrollbar setting must change\nto move the slider \\fIdeltaX\\fR pixels to the right (\\fIdeltaY\\fR is\nignored in this case).\nIf the scrollbar is vertical, the result indicates how much the\nscrollbar setting must change to move the slider \\fIdeltaY\\fR pixels\ndown. The arguments and the result may be zero or negative.\n.\\\" METHOD: fraction\n.TP\n\\fIpathName \\fBfraction \\fIx y\\fR\n.\nReturns a real number between 0 and 1 indicating where the point\ngiven by \\fIx\\fR and \\fIy\\fR lies in the trough area of the scrollbar.\nThe value 0 corresponds to the top or left of the trough, the\nvalue 1 corresponds to the bottom or right, 0.5 corresponds to\nthe middle, and so on.\n\\fIX\\fR and \\fIy\\fR must be pixel coordinates relative to the scrollbar\nwidget.\nIf \\fIx\\fR and \\fIy\\fR refer to a point outside the trough, the closest\npoint in the trough is used.\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget\\fR\n.\nReturns the scrollbar settings in the form of a list whose\nelements are the arguments to the most recent \\fBset\\fR widget command.\n.\\\" METHOD: identify\n.TP\n\\fIpathName \\fBidentify \\fIx y\\fR\n.\nReturns the name of the element under the point given by \\fIx\\fR and\n\\fIy\\fR (such as \\fBarrow1\\fR), or an empty string if the point does\nnot lie in any element of the scrollbar.\n\\fIX\\fR and \\fIy\\fR must be pixel coordinates relative to the scrollbar\nwidget.\n.\\\" METHOD: set\n.TP\n\\fIpathName \\fBset \\fIfirst last\\fR\n.\nThis command is invoked by the scrollbar's associated widget to\ntell the scrollbar about the current view in the widget.\nThe command takes two arguments, each of which is a real fraction\nbetween 0 and 1.\nThe fractions describe the range of the document that is visible in\nthe associated widget.\nFor example, if \\fIfirst\\fR is 0.2 and \\fIlast\\fR is 0.4, it means\nthat the first part of the document visible in the window is 20%\nof the way through the document, and the last visible part is 40%\nof the way through.\n.SH \"SCROLLING COMMANDS\"\n.PP\nWhen the user interacts with the scrollbar, for example by dragging\nthe slider, the scrollbar notifies the associated widget that it\nmust change its view.\nThe scrollbar makes the notification by evaluating a Tcl command\ngenerated from the scrollbar's \\fB\\-command\\fR option.\nThe command may take any of the following forms.\nIn each case, \\fIprefix\\fR is the contents of the\n\\fB\\-command\\fR option, which usually has a form like\n.QW \"\\fB.t yview\\fR\" .\n.\\\" METHOD: moveto\n.TP\n\\fIprefix \\fBmoveto \\fIfraction\\fR\n.\n\\fIFraction\\fR is a real number between 0 and 1.\nThe widget should adjust its view so that the point given\nby \\fIfraction\\fR appears at the beginning of the widget.\nIf \\fIfraction\\fR is 0 it refers to the beginning of the\ndocument. 1.0 refers to the end of the document, 0.333\nrefers to a point one-third of the way through the document,\nand so on.\n.\\\" METHOD: scroll\n.TP\n\\fIprefix \\fBscroll \\fInumber \\fBpages\\fR\n.\nThe widget should adjust its view by \\fInumber\\fR pages.\nIt is up to the widget to define the meaning of a page; typically\nit is slightly less than what fits in the window, so that there\nis a slight overlap between the old and new views.\n\\fINumber\\fR is either 1, which means the next page should\nbecome visible, or \\-1, which means that the previous page should\nbecome visible. Fractional numbers are rounded away from 0, so\nscrolling 0.001 pages has the same effect as scrolling 1 page.\n.TP\n\\fIprefix \\fBscroll \\fInumber \\fBunits\\fR\n.\nThe widget should adjust its view by \\fInumber\\fR units.\nThe units are defined in whatever way makes sense for the widget,\nsuch as characters or lines in a text widget.\n\\fINumber\\fR is either 1, which means one unit should scroll off\nthe top or left of the window, or \\-1, which means that one unit\nshould scroll off the bottom or right of the window. Fractional\nnumbers are rounded away from 0, so scrolling 0.001 units has\nthe same effect as scrolling 1 unit.\n.SH BINDINGS\n.PP\nTk automatically creates class bindings for scrollbars that give them\nthe following default behavior.\nIf the behavior is different for vertical and horizontal scrollbars,\nthe horizontal behavior is described in parentheses.\n.IP [1]\nPressing button 1 over \\fBarrow1\\fR causes the view in the\nassociated widget to shift up (left) by one unit so that the\ndocument appears to move down (right) one unit.\nIf the button is held down, the action auto-repeats.\n.IP [2]\nPressing button 1 over \\fBtrough1\\fR causes the view in the\nassociated widget to shift up (left) by one screenful so that the\ndocument appears to move down (right) one screenful.\nIf the button is held down, the action auto-repeats.\n.IP [3]\nPressing button 1 over the slider and dragging causes the view\nto drag with the slider.\nIf the \\fBjump\\fR option is true, then the view does not drag along\nwith the slider; it changes only when the mouse button is released.\n.IP [4]\nPressing button 1 over \\fBtrough2\\fR causes the view in the\nassociated widget to shift down (right) by one screenful so that the\ndocument appears to move up (left) one screenful.\nIf the button is held down, the action auto-repeats.\n.IP [5]\nPressing button 1 over \\fBarrow2\\fR causes the view in the\nassociated widget to shift down (right) by one unit so that the\ndocument appears to move up (left) one unit.\nIf the button is held down, the action auto-repeats.\n.IP [6]\nIf button 2 is pressed over the trough or the slider, it sets\nthe view to correspond to the mouse position; dragging the\nmouse with button 2 down causes the view to drag with the mouse.\nIf button 2 is pressed over one of the arrows, it causes the\nsame behavior as pressing button 1.\n.IP [7]\nIf button 1 is pressed with the Control key down, then if the\nmouse is over \\fBarrow1\\fR or \\fBtrough1\\fR the view changes\nto the very top (left) of the document; if the mouse is over\n\\fBarrow2\\fR or \\fBtrough2\\fR the view changes\nto the very bottom (right) of the document; if the mouse is\nanywhere else then the button press has no effect.\n.IP [8]\nIn vertical scrollbars the Up and Down keys have the same behavior\nas mouse clicks over \\fBarrow1\\fR and \\fBarrow2\\fR, respectively.\nIn horizontal scrollbars these keys have no effect.\n.IP [9]\nIn vertical scrollbars Control-Up and Control-Down have the same\nbehavior as mouse clicks over \\fBtrough1\\fR and \\fBtrough2\\fR, respectively.\nIn horizontal scrollbars these keys have no effect.\n.IP [10]\nIn horizontal scrollbars the Up and Down keys have the same behavior\nas mouse clicks over \\fBarrow1\\fR and \\fBarrow2\\fR, respectively.\nIn vertical scrollbars these keys have no effect.\n.IP [11]\nIn horizontal scrollbars Control-Up and Control-Down have the same\nbehavior as mouse clicks over \\fBtrough1\\fR and \\fBtrough2\\fR, respectively.\nIn vertical scrollbars these keys have no effect.\n.IP [12]\nThe Prior and Next keys have the same behavior\nas mouse clicks over \\fBtrough1\\fR and \\fBtrough2\\fR, respectively.\n.IP [13]\nThe Home key adjusts the view to the top (left edge) of the document.\n.IP [14]\nThe End key adjusts the view to the bottom (right edge) of the document.\n.SH EXAMPLE\n.PP\nCreate a window with a scrollable \\fBtext\\fR widget:\n.CS\ntoplevel .tl\ntext .tl.t -yscrollcommand {.tl.s set}\n\\fBscrollbar\\fR .tl.s -command {.tl.t yview}\ngrid .tl.t .tl.s -sticky nsew\ngrid columnconfigure .tl 0 -weight 1\ngrid rowconfigure .tl 0 -weight 1\n.CE\n.SH \"SEE ALSO\"\nttk::scrollbar(n)\n.SH KEYWORDS\nscrollbar, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/selection.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH selection n 8.1 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nselection \\- Manipulate the X selection\n.SH SYNOPSIS\n\\fBselection \\fIoption\\fR ?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThis command provides a Tcl interface to the X selection mechanism and\nimplements the full selection functionality described in the\nX Inter-Client Communication Conventions Manual (ICCCM).\n.PP\nNote that for management of the \\fBCLIPBOARD\\fR selection (see below), the\n\\fBclipboard\\fR command may also be used.\n.PP\nThe first argument to \\fBselection\\fR determines the format of the\nrest of the arguments and the behavior of the command. The following\nforms are currently supported:\n.\\\" METHOD: clear\n.TP\n\\fBselection clear\\fR ?\\fB\\-displayof\\fI window\\fR? ?\\fB\\-selection\\fI selection\\fR?\n.\nIf \\fIselection\\fR exists anywhere on \\fIwindow\\fR's display, clear it\nso that no window owns the selection anymore. \\fISelection\\fR\nspecifies the X selection that should be cleared, and should be an\natom name such as \\fBPRIMARY\\fR or \\fBCLIPBOARD\\fR; see the Inter-Client\nCommunication Conventions Manual for complete details.\n\\fISelection\\fR defaults to \\fBPRIMARY\\fR and \\fIwindow\\fR defaults to\n.QW . .\nReturns an empty string.\n.\\\" METHOD: get\n.TP\n\\fBselection get\\fR ?\\fB\\-displayof\\fI window\\fR? ?\\fB\\-selection\\fI selection\\fR? ?\\fB\\-type\\fI type\\fR?\n.\nRetrieves the value of \\fIselection\\fR from \\fIwindow\\fR's display and\nreturns it as a result. \\fISelection\\fR defaults to \\fBPRIMARY\\fR and\n\\fIwindow\\fR defaults to\n.QW . .\n\\fIType\\fR specifies the form in which the selection is to be returned\n(the desired\n.QW target\nfor conversion, in ICCCM terminology), and\nshould be an atom name such as \\fBSTRING\\fR or \\fBFILE_NAME\\fR; see the\nInter-Client Communication Conventions Manual for complete details.\n\\fIType\\fR defaults to \\fBSTRING\\fR. The selection owner may choose to\nreturn the selection in any of several different representation\nformats, such as \\fBSTRING\\fR, \\fBUTF8_STRING\\fR, \\fBATOM\\fR,\n\\fBINTEGER\\fR, etc. (this format is different\nthan the selection type; see the ICCCM for all the confusing details).\nIf the selection is returned in a non-string format, such as \\fBINTEGER\\fR\nor \\fBATOM\\fR, the \\fBselection\\fR command converts it to string format as a\ncollection of fields separated by spaces: atoms are converted to their\ntextual names, and anything else is converted to hexadecimal integers.\nNote that \\fBselection get\\fR does not retrieve the selection in the\n\\fBUTF8_STRING\\fR format unless told to.\n.\\\" METHOD: handle\n.TP\n\\fBselection handle\\fR ?\\fB\\-selection\\fI s\\fR? ?\\fB\\-type\\fI t\\fR? ?\\fB\\-format\\fI f\\fR? \\fIwindow command\\fR\n.\nCreates a handler for selection requests, such that \\fIcommand\\fR will\nbe executed whenever selection \\fIs\\fR is owned by \\fIwindow\\fR and\nsomeone attempts to retrieve it in the form given by type \\fIt\\fR\n(e.g. \\fIt\\fR is specified in the \\fBselection get\\fR command).\n\\fIS\\fR defaults to \\fBPRIMARY\\fR, \\fIt\\fR defaults to \\fBSTRING\\fR, and\n\\fIf\\fR defaults to \\fBSTRING\\fR. If \\fIcommand\\fR is an empty string\nthen any existing handler for \\fIwindow\\fR, \\fIt\\fR, and\n\\fIs\\fR is removed.\nNote that when the selection is handled as type \\fBSTRING\\fR it is also\nautomatically handled as type \\fBUTF8_STRING\\fR as well.\n.RS\n.PP\nWhen \\fIselection\\fR is requested, \\fIwindow\\fR is the selection owner,\nand \\fItype\\fR is the requested type, \\fIcommand\\fR will be executed\nas a Tcl command with two additional numbers appended to it\n(with space separators).\nThe two additional numbers\nare \\fIoffset\\fR and \\fImaxChars\\fR: \\fIoffset\\fR specifies a starting\ncharacter position in the selection and \\fImaxChars\\fR gives the maximum\nnumber of characters to retrieve. The command should return a value consisting\nof at most \\fImaxChars\\fR of the selection, starting at position\n\\fIoffset\\fR. For very large selections (larger than \\fImaxChars\\fR)\nthe selection will be retrieved using several invocations of \\fIcommand\\fR\nwith increasing \\fIoffset\\fR values. If \\fIcommand\\fR returns a string\nwhose length is less than \\fImaxChars\\fR, the return value is assumed to\ninclude all of the remainder of the selection; if the length of\n\\fIcommand\\fR's result is equal to \\fImaxChars\\fR then\n\\fIcommand\\fR will be invoked again, until it eventually\nreturns a result shorter than \\fImaxChars\\fR. The value of \\fImaxChars\\fR\nwill always be relatively large (thousands of characters).\n.PP\nIf \\fIcommand\\fR returns an error then the selection retrieval is rejected\njust as if the selection did not exist at all.\n.PP\nThe \\fIformat\\fR argument specifies the representation that should be\nused to transmit the selection to the requester (the second column of\nTable 2 of the ICCCM), and defaults to \\fBSTRING\\fR. If \\fIformat\\fR is\n\\fBSTRING\\fR, the selection is transmitted as 8-bit ASCII characters (i.e.\njust in the form returned by \\fIcommand\\fR, in the system \\fBencoding\\fR;\nthe \\fBUTF8_STRING\\fR format always uses UTF-8 as its encoding).\nIf \\fIformat\\fR is\n\\fBATOM\\fR, then the return value from \\fIcommand\\fR is divided into fields\nseparated by white space; each field is converted to its atom value,\nand the 32-bit atom value is transmitted instead of the atom name.\nFor any other \\fIformat\\fR, the return value from \\fIcommand\\fR is\ndivided into fields separated by white space and each field is\nconverted to a 32-bit integer; an array of integers is transmitted\nto the selection requester.\n.PP\nThe \\fIformat\\fR argument is needed only for compatibility with\nselection requesters that do not use Tk. If Tk is being\nused to retrieve the selection then the value is converted back to\na string at the requesting end, so \\fIformat\\fR is\nirrelevant.\n.RE\n.\\\" METHOD: own\n.TP\n\\fBselection own\\fR ?\\fB\\-displayof\\fI window\\fR? ?\\fB\\-selection\\fI selection\\fR?\n.TP\n\\fBselection own\\fR ?\\fB\\-command\\fI command\\fR? ?\\fB\\-selection\\fI selection\\fR? \\fIwindow\\fR\n.\nThe first form of \\fBselection own\\fR returns the path name of the\nwindow in this application that owns \\fIselection\\fR on the display\ncontaining \\fIwindow\\fR, or an empty string if no window in this\napplication owns the selection. \\fISelection\\fR defaults to \\fBPRIMARY\\fR and\n\\fIwindow\\fR defaults to\n.QW . .\n.RS\n.PP\nThe second form of \\fBselection own\\fR causes \\fIwindow\\fR to become\nthe new owner of \\fIselection\\fR on \\fIwindow\\fR's display, returning\nan empty string as result. The existing owner, if any, is notified\nthat it has lost the selection.\nIf \\fIcommand\\fR is specified, it is a Tcl script to execute when\nsome other window claims ownership of the selection away from\n\\fIwindow\\fR. \\fISelection\\fR defaults to PRIMARY.\n.RE\n.SH WIDGET FACILITIES\n.PP\nThe \\fBtext\\fR, \\fBentry\\fR, \\fBttk::entry\\fR, \\fBlistbox\\fR, \\fBspinbox\\fR\nand \\fBttk::spinbox\\fR widgets have the option \\fB\\-exportselection\\fR. If a\nwidget has this option set to boolean \\fBtrue\\fR, then (in an unsafe\ninterpreter) a selection made in the widget is automatically written to the\n\\fBPRIMARY\\fR selection.\n.PP\nA GUI event, for example \\fB<>\\fR, can copy the \\fBPRIMARY\\fR\nselection to certain widgets. This copy is implemented by a widget binding to\nthe event. The binding script makes appropriate calls to the \\fBselection\\fR\ncommand.\n.PP\n.SH PORTABILITY ISSUES\n.PP\nOn X11, the \\fBPRIMARY\\fR selection is a system-wide feature of the X server,\nallowing communication between different processes that are X11 clients.\n.PP\nOn Windows, the \\fBPRIMARY\\fR selection is not provided by the system, but\nonly by Tk, and so it is shared only between windows of a parent interpreter\nand its child interpreters. It is not shared between interpreters in\ndifferent processes or different threads. Each parent interpreter has a\nseparate \\fBPRIMARY\\fR selection that is shared only with its child\ninterpreters which are not safe interpreters.\n.PP\n.SH SECURITY\n.PP\nA safe interpreter cannot read from the \\fBPRIMARY\\fR selection because its\n\\fBselection\\fR command is hidden. For this reason the \\fBPRIMARY\\fR\nselection cannot be written to the Tk widgets of a safe interpreter.\n.PP\nA Tk widget can have its option \\fB\\-exportselection\\fR set to boolean\n\\fBtrue\\fR, but in a safe interpreter this option has no effect: writing\nfrom the widget to the \\fBPRIMARY\\fR selection is disabled.\n.PP\nThese are security features. A safe interpreter may run untrusted code, and\nit is a security risk if this untrusted code can read or write the\n\\fBPRIMARY\\fR selection used by other interpreters.\n.PP\n.SH EXAMPLES\n.PP\nOn X11 platforms, one of the standard selections available is the\n\\fBSECONDARY\\fR selection. Hardly anything uses it, but here is how to read\nit using Tk:\n.PP\n.CS\nset selContents [\\fBselection get\\fR -selection SECONDARY]\n.CE\n.PP\nMany different types of data may be available for a selection; the\nspecial type \\fBTARGETS\\fR allows you to get a list of available types:\n.PP\n.CS\nforeach type [\\fBselection get\\fR -type TARGETS] {\n puts \"Selection PRIMARY supports type $type\"\n}\n.CE\n.PP\nTo claim the selection, you must first set up a handler to supply the\ndata for the selection. Then you have to claim the selection...\n.CS\n# Set up the data handler ready for incoming requests\nset foo \"This is a string with some data in it... blah blah\"\n\\fBselection handle\\fR -selection SECONDARY . getData\nproc getData {offset maxChars} {\n puts \"Retrieving selection starting at $offset\"\n return [string range $::foo $offset [expr {$offset+$maxChars-1}]]\n}\n\n# Now we grab the selection itself\nputs \"Claiming selection\"\n\\fBselection own\\fR -command lost -selection SECONDARY .\nproc lost {} {\n puts \"Lost selection\"\n}\n.CE\n.SH \"SEE ALSO\"\nclipboard(n)\n.SH KEYWORDS\nclear, format, handler, ICCCM, own, selection, target, type\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/send.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH send n 4.0 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nsend \\- Execute a command in a different application\n.SH SYNOPSIS\n\\fBsend ?\\fIoptions\\fR? \\fIapp cmd \\fR?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThis command arranges for \\fIcmd\\fR (and \\fIarg\\fRs) to be executed in the\napplication named by \\fIapp\\fR. It returns the result or\nerror from that command execution.\n\\fIApp\\fR may be the name of any application whose main window is\non the display containing the sender's main window; it need not\nbe within the same process.\nIf no \\fIarg\\fR arguments are present, then the command to be executed is\ncontained entirely within the \\fIcmd\\fR argument. If one or\nmore \\fIarg\\fRs are present, they are concatenated to form the\ncommand to be executed, just as for the \\fBeval\\fR command.\n.PP\nIf the initial arguments of the command begin with\n.QW \\-\nthey are treated as options. The following options are currently defined:\n.\\\" OPTION: -async\n.TP\n\\fB\\-async\\fR\n.\nRequests asynchronous invocation. In this case the \\fBsend\\fR\ncommand will complete immediately without waiting for \\fIcmd\\fR\nto complete in the target application; no result will be available\nand errors in the sent command will be ignored.\nIf the target application is in the same process as the sending\napplication then the \\fB\\-async\\fR option is ignored.\n.\\\" OPTION: -displayof\n.TP\n\\fB\\-displayof\\fI pathName\\fR\n.\nSpecifies that the target application's main window is on the display\nof the window given by \\fIpathName\\fR, instead of the display containing\nthe application's main window.\n.\\\" OPTION: --\n.TP\n\\fB\\-\\|\\-\\fR\n.\nServes no purpose except to terminate the list of options. This\noption is needed only if \\fIapp\\fR could contain a leading\n.QW \\-\ncharacter.\n.SH \"APPLICATION NAMES\"\n.PP\nThe name of an application is set initially from the name of the\nprogram or script that created the application.\nYou can query and change the name of an application with the\n\\fBtk appname\\fR command.\n.SH \"DISABLING SENDS\"\n.PP\nIf the \\fBsend\\fR command is removed from an application (e.g.\nwith the command \\fBrename\\fR \\fBsend {}\\fR) then the application\nwill not respond to incoming send requests anymore, nor will it\nbe able to issue outgoing requests.\nCommunication can be reenabled by invoking the \\fBtk appname\\fR\ncommand.\n.SH SECURITY\n.PP\nThe \\fBsend\\fR command is potentially a serious security loophole. On Unix,\nany application that can connect to your X server can send\nscripts to your applications.\nThese incoming scripts can use Tcl to read and\nwrite your files and invoke subprocesses under your name.\nHost-based access control such as that provided by \\fBxhost\\fR\nis particularly insecure, since it allows anyone with an account\non particular hosts to connect to your server, and if disabled it\nallows anyone anywhere to connect to your server.\nIn order to provide at least a small amount of\nsecurity, Tk checks the access control being used by the server\nand rejects incoming sends unless (a) \\fBxhost\\fR-style access control\nis enabled (i.e. only certain hosts can establish connections) and (b) the\nlist of enabled hosts is empty.\nThis means that applications cannot connect to your server unless\nthey use some other form of authorization\nsuch as that provide by \\fBxauth\\fR.\n.PP\nUnder macOS/aqua, the \\fBsend\\fR command can target an interpreter\nrunning in a different process, but only if the target process is\nowned by the same user and is running on the same host system as the\nsender's process. The \"winfo interps\" command shows exactly which\ninterpreters are valid targets for the \\fBsend\\fR command.\n.PP\nUnder Windows, \\fBsend\\fR is currently disabled. Most of the\nfunctionality is provided by the \\fBdde\\fR command instead.\n.SH EXAMPLE\n.PP\nThis script fragment can be used to make an application that only runs\nonce on a particular display.\n.CS\nif {[tk appname FoobarApp] ne \"FoobarApp\"} {\n \\fBsend\\fR -async FoobarApp RemoteStart $argv\n exit\n}\n# The command that will be called remotely, which raises\n# the application main window and opens the requested files\nproc RemoteStart args {\n raise .\n foreach filename $args {\n OpenFile $filename\n }\n}\n.CE\n.SH KEYWORDS\napplication, dde, name, remote execution, security, send\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/spinbox.n", "content": "'\\\"\n'\\\" Copyright (c) 2000 Jeffrey Hobbs.\n'\\\" Copyright (c) 2000 Ajuba Solutions.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH spinbox n 8.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\nspinbox \\- Create and manipulate 'spinbox' value spinner widgets\n.SH SYNOPSIS\n\\fBspinbox\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-activebackground\t\\-highlightthickness\t\\-repeatinterval\n\\-background\t\\-insertbackground\t\\-selectbackground\n\\-borderwidth\t\\-insertborderwidth\t\\-selectborderwidth\n\\-cursor\t\\-insertontime\t\\-selectforeground\n\\-exportselection\t\\-insertwidth\t\\-takefocus\n\\-font\t\\-insertofftime\t\\-textvariable\n\\-foreground\t\\-justify\t\\-xscrollcommand\n\\-highlightbackground\t\\-relief\n\\-highlightcolor\t\\-repeatdelay\n\\-placeholder\t\\-placeholderforeground\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-buttonbackground buttonBackground Background\nThe background color to be used for the spin buttons.\n.OP \\-buttoncursor buttonCursor Cursor\nThe cursor to be used when over the spin buttons. If this is empty\n(the default), a default cursor will be used.\n.OP \\-buttondownrelief buttonDownRelief Relief\nThe relief to be used for the upper spin button.\n.OP \\-buttonuprelief buttonUpRelief Relief\nThe relief to be used for the lower spin button.\n.OP \\-command command Command\nSpecifies a Tcl command to invoke whenever a spinbutton is invoked.\nThe command recognizes several percent substitutions: \\fB%W\\fR for\nthe widget path, \\fB%s\\fR for the current value of the widget, and\n\\fB%d\\fR for the direction of the button pressed (\\fBup\\fR or \\fBdown\\fR).\n.OP \\-disabledbackground disabledBackground DisabledBackground\nSpecifies the background color to use when the spinbox is disabled. If\nthis option is the empty string, the normal background color is used.\n.OP \\-disabledforeground disabledForeground DisabledForeground\nSpecifies the foreground color to use when the spinbox is disabled. If\nthis option is the empty string, the normal foreground color is used.\n.OP \\-format format Format\nSpecifies an alternate format to use when setting the string value\nwhen using the \\fB\\-from\\fR and \\fB\\-to\\fR range.\nThis must be a format specifier of the form \\fB%.f\\fR,\nas it will format a floating-point number.\n.OP \\-from from From\nA floating-point value corresponding to the lowest value for a spinbox, to\nbe used in conjunction with \\fB\\-to\\fR and \\fB\\-increment\\fR. When all\nare specified correctly, the spinbox will use these values to control its\ncontents. If this value is greater than the \\fB\\-to\\fR option, then\n\\fB\\-from\\fR and \\fB\\-to\\fR values are automatically swapped.\nIf \\fB\\-values\\fR is specified, it supersedes this option.\n.OP \"\\-invalidcommand or \\-invcmd\" invalidCommand InvalidCommand\nSpecifies a script to eval when \\fB\\-validatecommand\\fR returns 0. Setting\nit to an empty string disables this feature (the default). The best use of\nthis option is to set it to \\fIbell\\fR. See \\fBVALIDATION\\fR below for\nmore information.\n.OP \\-increment increment Increment\nA floating-point value specifying the increment. When used with\n\\fB\\-from\\fR and \\fB\\-to\\fR, the value in the widget will be adjusted by\n\\fB\\-increment\\fR when a spin button is pressed (up adds the value,\ndown subtracts the value).\n.OP \\-readonlybackground readonlyBackground ReadonlyBackground\nSpecifies the background color to use when the spinbox is readonly. If\nthis option is the empty string, the normal background color is used.\n.OP \\-state state State\nSpecifies one of three states for the spinbox: \\fBnormal\\fR,\n\\fBdisabled\\fR, or \\fBreadonly\\fR. If the spinbox is readonly, then the\nvalue may not be changed using widget commands and no insertion cursor\nwill be displayed, even if the input focus is in the widget; the\ncontents of the widget may still be selected. If the spinbox is\ndisabled, the value may not be changed, no insertion cursor will be\ndisplayed, the contents will not be selectable, and the spinbox may\nbe displayed in a different color, depending on the values of the\n\\fB\\-disabledforeground\\fR and \\fB\\-disabledbackground\\fR options.\n.OP \\-to to To\nA floating-point value corresponding to the highest value for the spinbox,\nto be used in conjunction with \\fB\\-from\\fR and \\fB\\-increment\\fR. When\nall are specified correctly, the spinbox will use these values to control\nits contents. If this value is less than the \\fB\\-from\\fR option, then\n\\fB\\-from\\fR and \\fB\\-to\\fR values are automatically swapped.\nIf \\fB\\-values\\fR is specified, it supersedes this option.\n.OP \\-validate validate Validate\nSpecifies the mode in which validation should operate: \\fBnone\\fR,\n\\fBfocus\\fR, \\fBfocusin\\fR, \\fBfocusout\\fR, \\fBkey\\fR, or \\fBall\\fR.\nIt defaults to \\fBnone\\fR. When you want validation, you must explicitly\nstate which mode you wish to use. See \\fBVALIDATION\\fR below for more.\n.OP \"\\-validatecommand or \\-vcmd\" validateCommand ValidateCommand\nSpecifies a script to evaluate when you want to validate the input in the\nwidget. Setting it to an empty string disables this feature (the default).\nValidation occurs according to the value of \\fB\\-validate\\fR.\nThis command must return a valid Tcl boolean value. If it returns 0 (or\nthe valid Tcl boolean equivalent) then the value of the widget will not\nchange and the \\fB\\-invalidcommand\\fR will be evaluated if it is set. If it\nreturns 1, then value will be changed.\nSee \\fBVALIDATION\\fR below for more information.\n.OP \\-values values Values\nMust be a proper list value. If specified, the spinbox will use these\nvalues as to control its contents, starting with the first value. This\noption has precedence over the \\fB\\-from\\fR and \\fB\\-to\\fR range.\n.OP \\-width width Width\nSpecifies an integer value indicating the desired width of the spinbox window,\nin average-size characters of the widget's font.\nIf the value is negative or zero, the widget picks a\nsize just large enough to hold its current text.\n.OP \\-wrap wrap wrap\nMust be a proper boolean value. If on, the spinbox will wrap around the\nvalues of data in the widget.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBspinbox\\fR command creates a new window (given by the\n\\fIpathName\\fR argument) and makes it into a spinbox widget.\nAdditional options, described above, may be specified on the\ncommand line or in the option database\nto configure aspects of the spinbox such as its colors, font,\nand relief. The \\fBspinbox\\fR command returns its\n\\fIpathName\\fR argument. At the time this command is invoked,\nthere must not exist a window named \\fIpathName\\fR, but\n\\fIpathName\\fR's parent must exist.\n.PP\nA \\fBspinbox\\fR is an extended \\fBentry\\fR widget that allows he user\nto move, or spin, through a fixed set of ascending or descending values\nsuch as times or dates in addition to editing the value as in an\n\\fBentry\\fR. When first created, a spinbox's string is empty.\nA portion of the spinbox may be selected as described below.\nIf a spinbox is exporting its selection (see the \\fB\\-exportselection\\fR\noption), then it will observe the standard protocols for handling the\nselection; spinbox selections are available as type \\fBSTRING\\fR.\nSpinboxes also observe the standard Tk rules for dealing with the\ninput focus. When a spinbox has the input focus it displays an\n\\fIinsertion cursor\\fR to indicate where new characters will be\ninserted.\n.PP\nSpinboxes are capable of displaying strings that are too long to\nfit entirely within the widget's window. In this case, only a\nportion of the string will be displayed; commands described below\nmay be used to change the view in the window. Spinboxes use\nthe standard \\fB\\-xscrollcommand\\fR mechanism for interacting with\nscrollbars (see the description of the \\fB\\-xscrollcommand\\fR option\nfor details). They also support scanning, as described below.\n.SH VALIDATION\n.PP\nValidation works by setting the \\fB\\-validatecommand\\fR\noption to a script which will be evaluated according to the \\fB\\-validate\\fR\noption as follows:\n.PP\n.IP \\fBnone\\fR 10\nDefault. This means no validation will occur.\n.IP \\fBfocus\\fR 10\nThe \\fB\\-validatecommand\\fR will be called when the spinbox receives or\nloses focus.\n.IP \\fBfocusin\\fR 10\nThe \\fB\\-validatecommand\\fR will be called when the spinbox receives focus.\n.IP \\fBfocusout\\fR 10\nThe \\fB\\-validatecommand\\fR will be called when the spinbox loses focus.\n.IP \\fBkey\\fR 10\nThe \\fB\\-validatecommand\\fR will be called when the spinbox is edited.\n.IP \\fBall\\fR 10\nThe \\fB\\-validatecommand\\fR will be called for all above conditions.\n.PP\nIt is possible to perform percent substitutions on the \\fB\\-validatecommand\\fR\nand \\fB\\-invalidcommand\\fR scripts, just as you would in a \\fBbind\\fR script.\nThe following substitutions are recognized:\n.PP\n.IP \\fB%d\\fR 5\nType of action: 1 for \\fBinsert\\fR, 0 for \\fBdelete\\fR,\nor \\-1 for focus, forced or textvariable validation.\n.IP \\fB%i\\fR 5\nIndex of char string to be inserted/deleted, if any, otherwise \\-1.\n.IP \\fB%P\\fR 5\nThe value of the spinbox should edition occur. If you are configuring the\nspinbox widget to have a new textvariable, this will be the value of that\ntextvariable.\n.IP \\fB%s\\fR 5\nThe current value of spinbox before edition.\n.IP \\fB%S\\fR 5\nThe text string being inserted/deleted, if any.\nOtherwise it is an empty string.\n.IP \\fB%v\\fR 5\nThe type of validation currently set.\n.IP \\fB%V\\fR 5\nThe type of validation that triggered the callback\n(key, focusin, focusout, forced).\n.IP \\fB%W\\fR 5\nThe name of the spinbox widget.\n.PP\nIn general, the \\fB\\-textvariable\\fR and \\fB\\-validatecommand\\fR can be\ndangerous to mix. Any problems have been overcome so that using the\n\\fB\\-validatecommand\\fR will not interfere with the traditional behavior of\nthe spinbox widget. Using the \\fB\\-textvariable\\fR for read-only purposes will\nnever cause problems. The danger comes when you try set the\n\\fB\\-textvariable\\fR to something that the \\fB\\-validatecommand\\fR would not\naccept, which causes \\fB\\-validate\\fR to become \\fBnone\\fR (the\n\\fB\\-invalidcommand\\fR will not be triggered). The same happens\nwhen an error occurs evaluating the \\fB\\-validatecommand\\fR.\n.PP\nPrimarily, an error will occur when the \\fB\\-validatecommand\\fR or\n\\fB\\-invalidcommand\\fR encounters an error in its script while evaluating or\n\\fB\\-validatecommand\\fR does not return a valid Tcl boolean value. The\n\\fB\\-validate\\fR option will also set itself to \\fBnone\\fR when you edit the\nspinbox widget from within either the \\fB\\-validatecommand\\fR or the\n\\fB\\-invalidcommand\\fR. Such editions will override the one that was being\nvalidated. If you wish to edit the value of the widget\nduring validation and still have the \\fB\\-validate\\fR option set, you should\ninclude the command\n.CS\n \\fI%W config -validate %v\\fR\n.CE\nin the \\fB\\-validatecommand\\fR or \\fB\\-invalidcommand\\fR (whichever one you\nwere editing the spinbox widget from). It is also recommended to not set an\nassociated \\fB\\-textvariable\\fR during validation, as that can cause the\nspinbox widget to become out of sync with the \\fB\\-textvariable\\fR.\n.PP\nAlso, the \\fB\\-validate\\fR option will set itself to \\fBnone\\fR when the\nspinbox value gets changed because of adjustment of \\fB\\-from\\fR or \\fB\\-to\\fR\nand the \\fB\\-validatecommand\\fR returns false. For instance\n.CS\n \\fIspinbox pathName -from 1 -to 10 -validate all -validatecommand {return 0}\\fR\n.CE\nwill in fact set the \\fB\\-validate\\fR option to \\fBnone\\fR because the default\nvalue for the spinbox gets changed (due to the \\fB\\-from\\fR and \\fB\\-to\\fR\noptions) to a value not accepted by the validation script.\n.PP\nMoreover, forced validation is performed when invoking any spinbutton of\nthe spinbox. If the validation script returns false in this situation,\nthen the \\fB\\-validate\\fR option will be automatically set to \\fBnone\\fR.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBspinbox\\fR command creates a new Tcl command whose\nname is \\fIpathName\\fR. This command may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command.\n.SS INDICES\n.PP\nMany of the widget commands for spinboxes take one or more indices as\narguments. An index specifies a particular character in the spinbox's\nstring, in any of the following ways:\n.TP 12\n\\fInumber\\fR\n.\nSpecifies the character as a numerical index, where 0 corresponds\nto the first character in the string.\n.TP 12\n\\fBanchor\\fR\n.\nIndicates the anchor point for the selection, which is set with the\n\\fBselect from\\fR and \\fBselect adjust\\fR widget commands.\n.TP 12\n\\fBend\\fR\n.\nIndicates the character just after the last one in the spinbox's string.\nThis is equivalent to specifying a numerical index equal to the length\nof the spinbox's string.\n.TP 12\n\\fBinsert\\fR\n.\nIndicates the character adjacent to and immediately following the\ninsertion cursor.\n.TP 12\n\\fBsel.first\\fR\n.\nIndicates the first character in the selection. It is an error to\nuse this form if the selection is not in the spinbox window.\n.TP 12\n\\fBsel.last\\fR\n.\nIndicates the character just after the last one in the selection.\nIt is an error to use this form if the selection is not in the\nspinbox window.\n.TP 12\n\\fB@\\fInumber\\fR\n.\nIn this form, \\fInumber\\fR is treated as an x-coordinate in the\nspinbox's window; the character spanning that x-coordinate is used.\nFor example,\n.QW \\fB@0\\fR\nindicates the left-most character in the window.\n.LP\nAbbreviations may be used for any of the forms above, e.g.\n.QW \\fBe\\fR\nor\n.QW \\fBsel.f\\fR .\nIn general, out-of-range indices are automatically rounded to the\nnearest legal value.\nIndexes support the same simple interpretation as\nfor the command \\fBstring index\\fR, with simple integer index\narithmetic and indexing relative to \\fBend\\fR.\n.SS SUBCOMMANDS\n.PP\nThe following commands are possible for spinbox widgets:\n.\\\" METHOD: bbox\n.TP\n\\fIpathName \\fBbbox \\fIindex\\fR\n.\nReturns a list of four numbers describing the bounding box of the\ncharacter given by \\fIindex\\fR.\nThe first two elements of the list give the x and y coordinates of\nthe upper-left corner of the screen area covered by the character\n(in pixels relative to the widget) and the last two elements give\nthe width and height of the character, in pixels.\nThe bounding box may refer to a region outside the visible area\nof the window.\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBspinbox\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBspinbox\\fR\ncommand.\n.\\\" METHOD: delete\n.TP\n\\fIpathName \\fBdelete \\fIfirst \\fR?\\fIlast\\fR?\n.\nDelete one or more elements of the spinbox.\n\\fIFirst\\fR is the index of the first character to delete, and\n\\fIlast\\fR is the index of the character just after the last\none to delete.\nIf \\fIlast\\fR is not specified it defaults to \\fIfirst\\fR+1,\ni.e. a single character is deleted.\nThis command returns an empty string.\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget\\fR\n.\nReturns the spinbox's string.\n.\\\" METHOD: icursor\n.TP\n\\fIpathName \\fBicursor \\fIindex\\fR\n.\nArrange for the insertion cursor to be displayed just before the character\ngiven by \\fIindex\\fR. Returns an empty string.\n.\\\" METHOD: identify\n.TP\n\\fIpathName \\fBidentify\\fI x y\\fR\n.\nReturns the name of the window element corresponding to coordinates\n\\fIx\\fR and \\fIy\\fR in the spinbox. Return value is one of:\n\\fBnone\\fR, \\fBbuttondown\\fR, \\fBbuttonup\\fR, \\fBentry\\fR.\n.\\\" METHOD: index\n.TP\n\\fIpathName \\fBindex\\fI index\\fR\n.\nReturns the numerical index corresponding to \\fIindex\\fR.\n.\\\" METHOD: insert\n.TP\n\\fIpathName \\fBinsert \\fIindex string\\fR\n.\nInsert the characters of \\fIstring\\fR just before the character\nindicated by \\fIindex\\fR. Returns an empty string.\n.\\\" METHOD: invoke\n.TP\n\\fIpathName \\fBinvoke\\fI element\\fR\n.\nCauses the specified element, either \\fBbuttondown\\fR or \\fBbuttonup\\fR,\nto be invoked, triggering the action associated with it.\n.\\\" METHOD: scan\n.TP\n\\fIpathName \\fBscan\\fI option args\\fR\n.\nThis command is used to implement scanning on spinboxes. It has\ntwo forms, depending on \\fIoption\\fR:\n.RS\n.TP\n\\fIpathName \\fBscan mark \\fIx\\fR\n.\nRecords \\fIx\\fR and the current view in the spinbox window; used in\nconjunction with later \\fBscan dragto\\fR commands. Typically this\ncommand is associated with a mouse button press in the widget. It\nreturns an empty string.\n.TP\n\\fIpathName \\fBscan dragto \\fIx\\fR\n.\nThis command computes the difference between its \\fIx\\fR argument\nand the \\fIx\\fR argument to the last \\fBscan mark\\fR command for\nthe widget. It then adjusts the view left or right by 10 times the\ndifference in x-coordinates. This command is typically associated\nwith mouse motion events in the widget, to produce the effect of\ndragging the spinbox at high speed through the window. The return\nvalue is an empty string.\n.RE\n.\\\" METHOD: selection\n.TP\n\\fIpathName \\fBselection \\fIoption arg\\fR\n.\nThis command is used to adjust the selection within a spinbox. It\nhas several forms, depending on \\fIoption\\fR:\n.RS\n.TP\n\\fIpathName \\fBselection adjust \\fIindex\\fR\n.\nLocate the end of the selection nearest to the character given by\n\\fIindex\\fR, and adjust that end of the selection to be at \\fIindex\\fR\n(i.e. including but not going beyond \\fIindex\\fR). The other\nend of the selection is made the anchor point for future\n\\fBselect to\\fR commands. If the selection\nis not currently in the spinbox, then a new selection is created to\ninclude the characters between \\fIindex\\fR and the most recent\nselection anchor point, inclusive.\nReturns an empty string.\n.TP\n\\fIpathName \\fBselection clear\\fR\n.\nClear the selection if it is currently in this widget. If the\nselection is not in this widget then the command has no effect.\nReturns an empty string.\n.TP\n\\fIpathName \\fBselection element\\fR ?\\fIelement\\fR?\n.\nSets or gets the currently selected element. If a spinbutton element\nis specified, it will be displayed depressed.\n.TP\n\\fIpathName \\fBselection from \\fIindex\\fR\n.\nSet the selection anchor point to just before the character\ngiven by \\fIindex\\fR. Does not change the selection.\nReturns an empty string.\n.TP\n\\fIpathName \\fBselection present\\fR\n.\nReturns 1 if there is are characters selected in the spinbox,\n0 if nothing is selected.\n.TP\n\\fIpathName \\fBselection range \\fIstart end\\fR\n.\nSets the selection to include the characters starting with\nthe one indexed by \\fIstart\\fR and ending with the one just\nbefore \\fIend\\fR.\nIf \\fIend\\fR refers to the same character as \\fIstart\\fR or an\nearlier one, then the spinbox's selection is cleared.\n.TP\n\\fIpathName \\fBselection to \\fIindex\\fR\n.\nIf \\fIindex\\fR is before the anchor point, set the selection\nto the characters from \\fIindex\\fR up to but not including\nthe anchor point.\nIf \\fIindex\\fR is the same as the anchor point, do nothing.\nIf \\fIindex\\fR is after the anchor point, set the selection\nto the characters from the anchor point up to but not including\n\\fIindex\\fR.\nThe anchor point is determined by the most recent \\fBselect from\\fR\nor \\fBselect adjust\\fR command in this widget.\nIf the selection is not in this widget then a new selection is\ncreated using the most recent anchor point specified for the widget.\nReturns an empty string.\n.RE\n.\\\" METHOD: set\n.TP\n\\fIpathName \\fBset\\fR ?\\fIstring\\fR?\n.\nIf \\fIstring\\fR is specified, the spinbox will try and set it to this\nvalue, otherwise it just returns the spinbox's string.\nIf validation is on, it will occur when setting the string.\n.\\\" METHOD: validate\n.TP\n\\fIpathName \\fBvalidate\\fR\n.\nThis command is used to force an evaluation of the \\fB\\-validatecommand\\fR\nindependent of the conditions specified by the \\fB\\-validate\\fR option.\nThis is done by temporarily setting the \\fB\\-validate\\fR option to \\fBall\\fR.\nIt returns 0 or 1.\n.\\\" METHOD: xview\n.TP\n\\fIpathName \\fBxview \\fIargs\\fR\n.\nThis command is used to query and change the horizontal position of the\ntext in the widget's window. It can take any of the following\nforms:\n.RS\n.TP\n\\fIpathName \\fBxview\\fR\n.\nReturns a list containing two elements.\nEach element is a real fraction between 0 and 1; together they describe\nthe horizontal span that is visible in the window.\nFor example, if the first element is .2 and the second element is .6,\n20% of the spinbox's text is off-screen to the left, the middle 40% is visible\nin the window, and 40% of the text is off-screen to the right.\nThese are the same values passed to scrollbars via the \\fB\\-xscrollcommand\\fR\noption.\n.TP\n\\fIpathName \\fBxview \\fIindex\\fR\n.\nAdjusts the view in the window so that the character given by \\fIindex\\fR\nis displayed at the left edge of the window.\n.TP\n\\fIpathName \\fBxview moveto\\fI fraction\\fR\n.\nAdjusts the view in the window so that the character \\fIfraction\\fR of the\nway through the text appears at the left edge of the window.\n\\fIFraction\\fR must be a fraction between 0 and 1.\n.TP\n\\fIpathName \\fBxview scroll \\fInumber what\\fR\n.\nThis command shifts the view in the window left or right according to\n\\fInumber\\fR and \\fIwhat\\fR.\n\\fINumber\\fR must be an integer or a float, but if it is a float then\nit is converted to an integer, rounded away from 0.\n\\fIWhat\\fR must be either \\fBpages\\fR or \\fBunits\\fR or an abbreviation\nof one of these.\nIf \\fIwhat\\fR is \\fBpages\\fR then the view adjusts by \\fInumber\\fR\nscreenfuls. If \\fInumber\\fR is negative then characters farther to the left\nbecome visible; if it is positive then characters farther to the right\nbecome visible.\nIf \\fIwhat\\fR is \\fBunits\\fR, the view adjusts left or right by\n\\fInumber\\fR average-width characters on the display.\n.RE\n.SH \"DEFAULT BINDINGS\"\n.PP\nTk automatically creates class bindings for spinboxes that give them\nthe following default behavior.\nIn the descriptions below,\n.QW word\nrefers to a contiguous group of letters, digits, or\n.QW _\ncharacters, or any single character other than these.\n.IP [1]\nClicking mouse button 1 positions the insertion cursor\njust before the character underneath the mouse cursor, sets the\ninput focus to this widget, and clears any selection in the widget.\nDragging with mouse button 1 strokes out a selection between\nthe insertion cursor and the character under the mouse.\n.IP [2]\nDouble-clicking with mouse button 1 selects the word under the mouse\nand positions the insertion cursor at the beginning of the word.\nDragging after a double click will stroke out a selection consisting\nof whole words.\n.IP [3]\nTriple-clicking with mouse button 1 selects all of the text in the\nspinbox and positions the insertion cursor before the first character.\n.IP [4]\nThe ends of the selection can be adjusted by dragging with mouse\nbutton 1 while the Shift key is down; this will adjust the end\nof the selection that was nearest to the mouse cursor when button\n1 was pressed.\nIf the button is double-clicked before dragging then the selection\nwill be adjusted in units of whole words.\n.IP [5]\nClicking mouse button 1 with the Control key down will position the\ninsertion cursor in the spinbox without affecting the selection.\n.IP [6]\nIf any normal printing characters are typed in a spinbox, they are\ninserted at the point of the insertion cursor.\n.IP [7]\nThe view in the spinbox can be adjusted by dragging with the middle\nmouse button (button 2, or button 3 in TkAqua). If the middle mouse\nbutton is clicked without moving the mouse, the selection is copied\ninto the spinbox at the position of the mouse cursor.\n.IP [8]\nIf the mouse is dragged out of the spinbox on the left or right sides\nwhile button 1 is pressed, the spinbox will automatically scroll to\nmake more text visible (if there is more text off-screen on the side\nwhere the mouse left the window).\n.IP [9]\nThe Left and Right keys move the insertion cursor one character to the\nleft or right; they also clear any selection in the spinbox and set\nthe selection anchor.\nIf Left or Right is typed with the Shift key down, then the insertion\ncursor moves and the selection is extended to include the new character.\nControl-Left and Control-Right move the insertion cursor by words, and\nControl-Shift-Left and Control-Shift-Right move the insertion cursor\nby words and also extend the selection.\nControl-b and Control-f behave the same as Left and Right, respectively.\nMeta-b and Meta-f behave the same as Control-Left and Control-Right,\nrespectively.\n.IP [10]\nThe Home key, or Control-a, will move the insertion cursor to the\nbeginning of the spinbox and clear any selection in the spinbox.\nShift-Home moves the insertion cursor to the beginning of the spinbox\nand also extends the selection to that point.\n.IP [11]\nThe End key, or Control-e, will move the insertion cursor to the\nend of the spinbox and clear any selection in the spinbox.\nShift-End moves the cursor to the end and extends the selection\nto that point.\n.IP [12]\nThe Select key and Control-Space set the selection anchor to the position\nof the insertion cursor. They do not affect the current selection.\nShift-Select and Control-Shift-Space adjust the selection to the\ncurrent position of the insertion cursor, selecting from the anchor\nto the insertion cursor if there was not any selection previously.\n.IP [13]\nControl-/ selects all the text in the spinbox.\n.IP [14]\nControl-\\e clears any selection in the spinbox.\n.IP [15]\nThe F16 key (labelled Copy on many Sun workstations) or Meta-w\ncopies the selection in the widget to the clipboard, if there is a selection.\n.IP [16]\nThe F20 key (labelled Cut on many Sun workstations) or Control-w\ncopies the selection in the widget to the clipboard and deletes\nthe selection.\nIf there is no selection in the widget then these keys have no effect.\n.IP [17]\nThe F18 key (labelled Paste on many Sun workstations) or Control-y\ninserts the contents of the clipboard at the position of the\ninsertion cursor.\n.IP [18]\nThe Delete key deletes the selection, if there is one in the spinbox.\nIf there is no selection, it deletes the character to the right of\nthe insertion cursor.\n.IP [19]\nThe BackSpace key and Control-h delete the selection, if there is one\nin the spinbox.\nIf there is no selection, it deletes the character to the left of\nthe insertion cursor.\n.IP [20]\nControl-d deletes the character to the right of the insertion cursor.\n.IP [21]\nMeta-d deletes the word to the right of the insertion cursor.\n.IP [22]\nControl-k deletes all the characters to the right of the insertion\ncursor.\n.IP [23]\nControl-t reverses the order of the two characters to the right of\nthe insertion cursor.\n.PP\nIf the spinbox is disabled using the \\fB\\-state\\fR option, then the spinbox's\nview can still be adjusted and text in the spinbox can still be selected,\nbut no insertion cursor will be displayed and no text modifications will\ntake place.\n.PP\nThe behavior of spinboxes can be changed by defining new bindings for\nindividual widgets or by redefining the class bindings.\n.SH \"SEE ALSO\"\nttk::spinbox(n)\n.SH KEYWORDS\nspinbox, entry, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/sysnotify.n", "content": ".\\\" Text automatically generated by txt2man\n'\\\"\n'\\\" Copyright (c) 2020 Kevin Walzer\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk sysnotify n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n.SH NAME\nsysnotify \\- Creates a notification window with a title and message.\n.SH SYNOPSIS\n\\fBtk sysnotify\\fI title message\\fR\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBtk sysnotify\\fR command creates a platform-specific system notification\nalert. Its intent is to provide a brief, unobtrusive notification to the user\nby popping up a window that briefly appears in a corner of the screen.\n.SH EXAMPLE\n.PP\nHere is an example of the \\fBtk sysnotify\\fR code:\n.PP\n.CS\ntk sysnotify \"Alert\" \\e\n \"This is just a test of the Tk System Notification Code.\"\n.CE\n.SH PLATFORM NOTES\n.PP\nThe macOS and Windows versions are native implementations using system\nAPI's. The X11 version has a conditional dependency on libnotify, and\nfalls back to a Tcl-only implementation if libnotify is not installed. On\nmacOS and Linux, the notification includes a platform-specific default image to\naccompany the text. On Windows, the notification displays the same image as the one\nin the system tray; Windows images will display best if they are 32x32 pixels.\n.TP\n\\fBmacOS\\fR\n.\nThe macOS version will request permission from the user to authorize\nnotifications. This must be activated in Apple's System Preferences\nNotifications section.\n.RS\n.PP\nIf deploying an application using the standalone version of Wish.app,\nsetting the bundle ID in the applications Info.plist file to begin with\n.QW \\fBcom\\fR\nseems necessary for notifications to work. Using a different prefix\nfor the bundle ID, such as something like\n.QW \\fBtk.tcl.tkchat\\fR ,\nwill cause notifications to silently fail.\n.RE\n.TP\n\\fBWindows\\fR\n.\nThe image is taken from the system tray, i.e., \\fBsysnotify\\fR can only be\ncalled when a \\fBsystray\\fR was installed.\n.\n.SH KEYWORDS\nnotify, alert\n" }, { "path": "doc/systray.n", "content": ".\\\" Text automatically generated by txt2man\n'\\\"\n'\\\" Copyright (c) 2020 Kevin Walzer\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk systray n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n.SH NAME\nsystray \\- Creates an icon display in the platform-specific system tray.\n.SH SYNOPSIS\n.nf\n\\fBtk systray create \\-image \\fIimage\\fR ?\\fB\\-text \\fItext\\fR? ?\\fB\\-button1 \\fIcallback\\fR? ?\\fB\\-button3 \\fIcallback\\fR?\n\\fBtk systray configure \\fI?option? ?value option value ...?\\fR\n\\fBtk systray exists\\fR\n\\fBtk systray destroy\\fR\n.fi\n.BE\n.SH DESCRIPTION\n.PP\n.\\\" METHOD: create\nThe \\fBtk systray create\\fR command creates an icon in the platform-specific\ntray. The widget is configured with a Tk image for the icon display, an\noptional string for display in a tooltip, and optional callbacks that are\nbound to and .\n.PP\n.\\\" METHOD: configure\nThe \\fBtk systray configure\\fR command sets one or more options of the systray\nicon. Configurable options are the same as for the \\fBcreate\\fR subcommand. When\na single option name is given, the command returns the current value of this\noption. When no option is given this command returns the list of all options and\ntheir current value.\n.PP\n.\\\" METHOD: exists\nThe \\fBtk systray exists\\fR command checks whether a systray icon was created.\nIt returns a boolean.\n.PP\n.\\\" METHOD: destroy\nThe \\fBtk systray destroy\\fR command removes the icon from display and\ndeallocates it.\n.PP\nFrom a user-interface standpoint, only one icon per interpreter is\nsupported; attempts to create additional icons will return an error. The\nexisting tray icon can be modified with different images and\nstrings to indicate app state. Loading additional interpreters into a\nrunning instance of Wish will allow additional icons to be displayed.\n.SH EXAMPLE\n.PP\nHere is an example of the \\fBtk systray\\fR code:\n.CS\nimage create photo book -data \\e\n R0lGODlhDwAPAKIAAP//////AP8AAMDAwICAgAAAAAAAAAAAACwAAAAADwAPAAADSQhA2u5ksPeKABKSCaya29d4WKgERFF0l1IMQCAKatvBJ0OTdzzXI1xMB3TBZAvATtB6NSLKleXi3OBoLqrVgc0yv+DVSEUuFxIAOw==\ntk systray create -image book -text \"tk systray sample\" \\e\n -button1 {puts \"Here is the tk systray output\"} \\e\n -button3 {puts \"here is alternate output\"}\n.CE\n.PP\nHere is an example of modifying the \\fBtk systray\\fR icon:\n.CS\nimage create photo book_page -data \\e\n R0lGODlhCwAPAKIAAP//////AMDAwICAgAAA/wAAAAAAAAAAACwAAAAACwAPAAADMzi6CzAugiAgDGE68aB0RXgRJBFVX0SNpQlUWfahQOvSsgrX7eZJMlQMWBEYj8iQchlKAAA7\ntk systray configure -image book_page -text \"Updated sample\" \\e\n -button1 {puts \"Different output from the tk systray\"} \\e\n -button3 {puts \"and more different output from the tk systray\"}\n.CE\n.SH PLATFORM NOTES\n.PP\nThe X11 implementation is supported on a \"best efforts\" basis because it is\ndependent on the window manager. The \"text\" flag, which is implemented as\na tooltip, does not always display if the WM does not support such features;\nthe systray icon itself may not even display with some window managers.\n.PP\nOn Windows, the Tk image provided in the \\fB\\-image\\fR option must be a\nphoto image. On other platforms either a bitmap image or a photo image\nmay be provided.\n.SH KEYWORDS\nimage, callback\n" }, { "path": "doc/text.n", "content": "'\\\"\n'\\\" Copyright (c) 1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH text n 8.5 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntext, tk_textCopy, tk_textCut, tk_textPaste \\- Create and manipulate 'text' hypertext editing widgets\n.SH SYNOPSIS\n.nf\n\\fBtext\\fI pathName \\fR?\\fIoptions\\fR?\n\\fBtk_textCopy\\fI pathName\\fR\n\\fBtk_textCut\\fI pathName\\fR\n\\fBtk_textPaste\\fI pathName\\fR\n.fi\n.SO\n\\-background\t\\-highlightthickness\t\\-relief\n\\-borderwidth\t\\-insertbackground\t\\-selectbackground\n\\-cursor\t\\-insertborderwidth\t\\-selectborderwidth\n\\-exportselection\t\\-insertofftime\t\\-selectforeground\n\\-font\t\\-insertontime\t\\-setgrid\n\\-foreground\t\\-insertwidth\t\\-takefocus\n\\-highlightbackground\t\\-padx\t\\-xscrollcommand\n\\-highlightcolor\t\\-pady\t\\-yscrollcommand\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-autoseparators autoSeparators AutoSeparators\nSpecifies a boolean that says whether separators are automatically inserted in\nthe undo stack. Only meaningful when the \\fB\\-undo\\fR option is true.\n.OP \\-blockcursor blockCursor BlockCursor\nSpecifies a boolean that says whether the blinking insertion cursor should be\ndrawn as a character-sized rectangular block. If false (the default) a thin\nvertical line is used for the insertion cursor.\n.OP \\-endline endLine EndLine\nSpecifies an integer line index representing the line of the underlying\ntextual data store that should be just after the last line contained in\nthe widget. This allows a text widget to reflect only a portion of a\nlarger piece of text. Instead of an integer, the empty string can be\nprovided to this configuration option, which will configure the widget\nto end at the very last line in the textual data store.\n.OP \\-height height Height\nSpecifies the desired height for the window, in units of characters in the\nfont given by the \\fB\\-font\\fR option. Must be at least one.\n.OP \\-inactiveselectbackground inactiveSelectBackground Foreground\nSpecifies the colour to use for the selection (the \\fBsel\\fR tag) when the\nwindow does not have the input focus. If empty, \\fB{}\\fR, then no selection is\nshown when the window does not have the focus.\n.OP \\-insertunfocussed insertUnfocussed InsertUnfocussed\n.VS 8.6\nSpecifies how to display the insertion cursor when the widget does not have\nthe focus. Must be \\fBnone\\fR (the default) which means to not display the\ncursor, \\fBhollow\\fR which means to display a hollow box, or \\fBsolid\\fR which\nmeans to display a solid box. Note that \\fBhollow\\fR and \\fBsolid\\fR will\nappear very similar when the \\fB\\-blockcursor\\fR option is false.\n.VE 8.6\n.OP \\-maxundo maxUndo MaxUndo\nSpecifies the maximum number of compound undo actions on the undo stack. A\nzero or a negative value imply an unlimited undo stack.\n.OP \\-spacing1 spacing1 Spacing1\nRequests additional space above each text line in the widget, using any of the\nstandard forms for screen distances. If a line wraps, this option only applies\nto the first line on the display. This option may be overridden with\n\\fB\\-spacing1\\fR options in tags.\n.OP \\-spacing2 spacing2 Spacing2\nFor lines that wrap (so that they cover more than one line on the display)\nthis option specifies additional space to provide between the display lines\nthat represent a single line of text. The value may have any of the standard\nforms for screen distances. This option may be overridden with\n\\fB\\-spacing2\\fR options in tags.\n.OP \\-spacing3 spacing3 Spacing3\nRequests additional space below each text line in the widget, using any of the\nstandard forms for screen distances. If a line wraps, this option only applies\nto the last line on the display. This option may be overridden with\n\\fB\\-spacing3\\fR options in tags.\n.OP \\-startline startLine StartLine\nSpecifies an integer line index representing the first line of the underlying\ntextual data store that should be contained in the widget. This allows a text\nwidget to reflect only a portion of a larger piece of text. Instead of an\ninteger, the empty string can be provided to this configuration option, which\nwill configure the widget to start at the very first line in the textual data\nstore.\n.OP \\-state state State\nSpecifies one of two states for the text: \\fBnormal\\fR or \\fBdisabled\\fR. If\nthe text is disabled then characters may not be inserted or deleted and no\ninsertion cursor will be displayed, even if the input focus is in the widget.\n.OP \\-tabs tabs Tabs\nSpecifies a set of tab stops for the window. The option's value consists of a\nlist of screen distances giving the positions of the tab stops, each of which\nis a distance relative to the left edge of the widget (excluding borders,\npadding, etc). Each position may optionally be followed in the next list\nelement by one of the keywords \\fBleft\\fR, \\fBright\\fR, \\fBcenter\\fR, or\n\\fBnumeric\\fR, which specifies how to justify text relative to the tab stop.\n\\fBLeft\\fR is the default; it causes the text following the tab character to\nbe positioned with its left edge at the tab position. \\fBRight\\fR means that\nthe right edge of the text following the tab character is positioned at the\ntab position, and \\fBcenter\\fR means that the text is centered at the tab\nposition. \\fBNumeric\\fR means that the decimal point in the text is positioned\nat the tab position; if there is no decimal point then the least significant\ndigit of the number is positioned just to the left of the tab position; if\nthere is no number in the text then the text is right-justified at the tab\nposition. For example,\n.QW \"\\fB\\-tabs {2c left 4c 6c center}\\fR\"\ncreates three tab stops at two-centimeter intervals; the first two use left\njustification and the third uses center justification.\n.RS\n.PP\nIf the list of tab stops does not have enough elements to cover all of the\ntabs in a text line, then Tk extrapolates new tab stops using the spacing and\nalignment from the last tab stop in the list. Tab distances must be strictly\npositive, and must always increase from one tab stop to the next (if not, an\nerror is thrown). The value of the \\fB\\-tabs\\fR option may be overridden by\n\\fB\\-tabs\\fR options in tags.\n.PP\nIf no \\fB\\-tabs\\fR option is specified, or if it is specified as an empty\nlist, then Tk uses default tabs spaced every eight (average size) characters.\nTo achieve a different standard spacing, for example every 4 characters,\nsimply configure the widget with\n.QW \"\\fB\\-tabs \\N'34'[expr {4 * [font measure $font 0]}] left\\N'34' \\-tabstyle wordprocessor\\fR\" .\n.RE\n.OP \\-tabstyle tabStyle TabStyle\nSpecifies how to interpret the relationship between tab stops on a line and\ntabs in the text of that line. The value must be \\fBtabular\\fR (the default)\nor \\fBwordprocessor\\fR. Note that tabs are interpreted as they are encountered\nin the text. If the tab style is \\fBtabular\\fR then the \\fIn\\fR'th tab\ncharacter in the line's text will be associated with the \\fIn\\fR'th tab stop\ndefined for that line. If the tab character's x coordinate falls to the right\nof the \\fIn\\fR'th tab stop, then a gap of a single space will be inserted as a\nfallback. If the tab style is \\fBwordprocessor\\fR then any tab character being\nlaid out will use (and be defined by) the first tab stop to the right of the\npreceding characters already laid out on that line. The value of the\n\\fB\\-tabstyle\\fR option may be overridden by \\fB\\-tabstyle\\fR options in tags.\n.OP \\-undo undo Undo\nSpecifies a boolean that says whether the undo mechanism is active or not.\n.OP \\-width width Width\nSpecifies the desired width for the window in units of characters in the font\ngiven by the \\fB\\-font\\fR option. If the font does not have a uniform width\nthen the width of the character\n.QW 0\nis used in translating from character units to screen units.\n.OP \\-wrap wrap Wrap\nSpecifies how to handle lines in the text that are too long to be displayed in\na single line of the text's window. The value must be \\fBnone\\fR or \\fBchar\\fR\nor \\fBword\\fR. A wrap mode of \\fBnone\\fR means that each line of text appears\nas exactly one line on the screen; extra characters that do not fit on the\nscreen are not displayed. In the other modes each line of text will be broken\nup into several screen lines if necessary to keep all the characters visible.\nIn \\fBchar\\fR mode a screen line break may occur after any character; in\n\\fBword\\fR mode a line break will only be made at word boundaries.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBtext\\fR command creates a new window (given by the \\fIpathName\\fR\nargument) and makes it into a text widget. Additional options, described\nabove, may be specified on the command line or in the option database to\nconfigure aspects of the text such as its default background color and relief.\nThe \\fBtext\\fR command returns the path name of the new window.\n.PP\nA text widget displays one or more lines of text and allows that text to be\nedited. Text widgets support four different kinds of annotations on the text,\ncalled tags, marks, embedded windows or embedded images. Tags allow different\nportions of the text to be displayed with different fonts and colors. In\naddition, Tcl commands can be associated with tags so that scripts are invoked\nwhen particular actions such as keystrokes and mouse button presses occur in\nparticular ranges of the text. See \\fBTAGS\\fR below for more details.\n.PP\nThe second form of annotation consists of floating markers in the text called\n.QW marks .\nMarks are used to keep track of various interesting positions in the text as\nit is edited. See \\fBMARKS\\fR below for more details.\n.PP\nThe third form of annotation allows arbitrary windows to be embedded in a text\nwidget. See \\fBEMBEDDED WINDOWS\\fR below for more details.\n.PP\nThe fourth form of annotation allows Tk images to be embedded in a text\nwidget. See \\fBEMBEDDED IMAGES\\fR below for more details.\n.PP\nThe text widget also has a built-in undo/redo mechanism. See\n\\fBTHE UNDO MECHANISM\\fR below for more details.\n.PP\nThe text widget allows for the creation of peer widgets. These are other text\nwidgets which share the same underlying data (text, marks, tags, images, etc).\nSee \\fBPEER WIDGETS\\fR below for more details.\n.SH INDICES\n.PP\nMany of the widget commands for texts take one or more indices as arguments.\nAn index is a string used to indicate a particular place within a text, such\nas a place to insert characters or one endpoint of a range of characters to\ndelete. Indices have the syntax\n.CS\n\\fIbase modifier modifier modifier ...\\fR\n.CE\nWhere \\fIbase\\fR gives a starting point and the \\fImodifier\\fRs adjust the\nindex from the starting point (e.g. move forward or backward one character).\nEvery index must contain a \\fIbase\\fR, but the \\fImodifier\\fRs are optional.\nMost modifiers (as documented below) allow an optional submodifier. Valid\nsubmodifiers are \\fBany\\fR and \\fBdisplay\\fR. If the submodifier is\nabbreviated, then it must be followed by whitespace, but otherwise there need\nbe no space between the submodifier and the following \\fImodifier\\fR.\nTypically the \\fBdisplay\\fR submodifier adjusts the meaning of the following\n\\fImodifier\\fR to make it refer to visual or non-elided units rather than\nlogical units, but this is explained for each relevant case below. Lastly,\nwhere \\fIcount\\fR is used as part of a modifier, it can be positive or\nnegative, so\n.QW \"\\fIbase\\fR \\- \\-3 lines\"\nis perfectly valid (and equivalent to\n.QW \"\\fIbase\\fR +3lines\" ).\n.PP\nThe \\fIbase\\fR for an index must have one of the following forms:\n.TP 12\n\\fIline\\fB.\\fIchar\\fR\n.\nIndicates \\fIchar\\fR'th character on line \\fIline\\fR. Lines are numbered from\n1 for consistency with other UNIX programs that use this numbering scheme.\nWithin a line, characters are numbered from 0. If \\fIchar\\fR is \\fBend\\fR then\nit refers to the newline character that ends the line.\n.TP 12\n\\fB@\\fIx\\fB,\\fIy\\fR\n.\nIndicates the character that covers the pixel whose x and y coordinates within\nthe text's window are \\fIx\\fR and \\fIy\\fR.\n.TP 12\n\\fBend\\fR\n.\nIndicates the end of the text (the character just after the last newline).\n.TP 12\n\\fImark\\fR\n.\nIndicates the character just after the mark whose name is \\fImark\\fR (see\n\\fBMARKS\\fR for details).\n.TP 12\n\\fItag\\fB.first\\fR\n.\nIndicates the first character in the text that has been tagged with \\fItag\\fR.\nThis form generates an error if no characters are currently tagged with\n\\fItag\\fR.\n.TP 12\n\\fItag\\fB.last\\fR\n.\nIndicates the character just after the last one in the text that has been\ntagged with \\fItag\\fR. This form generates an error if no characters are\ncurrently tagged with \\fItag\\fR.\n.TP 12\n\\fIpathName\\fR\n.\nIndicates the position of the embedded window whose name is \\fIpathName\\fR.\nThis form generates an error if there is no embedded window by the given name.\n.TP 12\n\\fIimageName\\fR\n.\nIndicates the position of the embedded image whose name is \\fIimageName\\fR.\nThis form generates an error if there is no embedded image by the given name.\n.PP\nIf the \\fIbase\\fR could match more than one of the above forms, such as a\n\\fImark\\fR and \\fIimageName\\fR both having the same value, then the form\nearlier in the above list takes precedence. If modifiers follow the base\nindex, each one of them must have one of the forms listed below. Keywords such\nas \\fBchars\\fR and \\fBwordend\\fR may be abbreviated as long as the\nabbreviation is unambiguous.\n.TP\n\\fB+ \\fIcount\\fR ?\\fIsubmodifier\\fR? \\fBchars\\fR\n.\nAdjust the index forward by \\fIcount\\fR characters, moving to later lines in\nthe text if necessary. If there are fewer than \\fIcount\\fR characters in the\ntext after the current index, then set the index to the last index in the\ntext. Spaces on either side of \\fIcount\\fR are optional. If the \\fBdisplay\\fR\nsubmodifier is given, elided characters are skipped over without being\ncounted. If \\fBany\\fR is given, then all characters are counted. For\nhistorical reasons, if neither modifier is given then the count actually takes\nplace in units of index positions (see \\fBINDICES\\fR for details). This\nbehaviour may be changed in a future major release, so if you need an index\ncount, you are encouraged to use \\fBindices\\fR instead wherever possible.\n.TP\n\\fB\\- \\fIcount\\fR ?\\fIsubmodifier\\fR? \\fBchars\\fR\n.\nAdjust the index backward by \\fIcount\\fR characters, moving to earlier lines\nin the text if necessary. If there are fewer than \\fIcount\\fR characters in\nthe text before the current index, then set the index to the first index in\nthe text (1.0). Spaces on either side of \\fIcount\\fR are optional. If the\n\\fBdisplay\\fR submodifier is given, elided characters are skipped over without\nbeing counted. If \\fBany\\fR is given, then all characters are counted. For\nhistorical reasons, if neither modifier is given then the count actually takes\nplace in units of index positions (see \\fBINDICES\\fR for details). This\nbehavior may be changed in a future major release, so if you need an index\ncount, you are encouraged to use \\fBindices\\fR instead wherever possible.\n.TP\n\\fB+ \\fIcount\\fR ?\\fIsubmodifier\\fR? \\fBindices\\fR\n.\nAdjust the index forward by \\fIcount\\fR index positions, moving to later lines\nin the text if necessary. If there are fewer than \\fIcount\\fR index positions\nin the text after the current index, then set the index to the last index\nposition in the text. Spaces on either side of \\fIcount\\fR are optional. Note\nthat an index position is either a single character or a single embedded image\nor embedded window. If the \\fBdisplay\\fR submodifier is given, elided indices\nare skipped over without being counted. If \\fBany\\fR is given, then all\nindices are counted; this is also the default behaviour if no modifier is\ngiven.\n.TP\n\\fB\\- \\fIcount\\fR ?\\fIsubmodifier\\fR? \\fBindices\\fR\n.\nAdjust the index backward by \\fIcount\\fR index positions, moving to earlier\nlines in the text if necessary. If there are fewer than \\fIcount\\fR index\npositions in the text before the current index, then set the index to the\nfirst index position (1.0) in the text. Spaces on either side of \\fIcount\\fR\nare optional. If the \\fBdisplay\\fR submodifier is given, elided indices are\nskipped over without being counted. If \\fBany\\fR is given, then all indices\nare counted; this is also the default behaviour if no modifier is given.\n.TP\n\\fB+ \\fIcount\\fR ?\\fIsubmodifier\\fR? \\fBlines\\fR\n.\nAdjust the index forward by \\fIcount\\fR lines, retaining the same character\nposition within the line. If there are fewer than \\fIcount\\fR lines after the\nline containing the current index, then set the index to refer to the same\ncharacter position on the last line of the text. Then, if the line is not long\nenough to contain a character at the indicated character position, adjust the\ncharacter position to refer to the last character of the line (the newline).\nSpaces on either side of \\fIcount\\fR are optional. If the \\fBdisplay\\fR\nsubmodifier is given, then each visual display line is counted separately.\nOtherwise, if \\fBany\\fR (or no modifier) is given, then each logical line (no\nmatter how many times it is visually wrapped) counts just once. If the\nrelevant lines are not wrapped, then these two methods of counting are\nequivalent.\n.TP\n\\fB\\- \\fIcount\\fR ?\\fIsubmodifier\\fR? \\fBlines\\fR\n.\nAdjust the index backward by \\fIcount\\fR logical lines, retaining the same\ncharacter position within the line. If there are fewer than \\fIcount\\fR lines\nbefore the line containing the current index, then set the index to refer to\nthe same character position on the first line of the text. Then, if the line\nis not long enough to contain a character at the indicated character position,\nadjust the character position to refer to the last character of the line (the\nnewline). Spaces on either side of \\fIcount\\fR are optional. If the\n\\fBdisplay\\fR submodifier is given, then each visual display line is counted\nseparately. Otherwise, if \\fBany\\fR (or no modifier) is given, then each\nlogical line (no matter how many times it is visually wrapped) counts just\nonce. If the relevant lines are not wrapped, then these two methods of\ncounting are equivalent.\n.TP\n?\\fIsubmodifier\\fR? \\fBlinestart\\fR\n.\nAdjust the index to refer to the first index on the line. If the \\fBdisplay\\fR\nsubmodifier is given, this is the first index on the display line, otherwise\non the logical line.\n.TP\n?\\fIsubmodifier\\fR? \\fBlineend\\fR\n.\nAdjust the index to refer to the last index on the line (the newline). If the\n\\fBdisplay\\fR submodifier is given, this is the last index on the display\nline, otherwise on the logical line.\n.TP\n?\\fIsubmodifier\\fR? \\fBwordstart\\fR\n.\nAdjust the index to refer to the first character of the word containing the\ncurrent index. A word consists of any number of adjacent characters that are\nletters, digits, or underscores, or a single character that is not one of\nthese. If the \\fBdisplay\\fR submodifier is given, this only examines\nnon-elided characters, otherwise all characters (elided or not) are examined.\n.TP\n?\\fIsubmodifier\\fR? \\fBwordend\\fR\n.\nAdjust the index to refer to the character just after the last one of the word\ncontaining the current index. If the current index refers to the last\ncharacter of the text then it is not modified. If the \\fBdisplay\\fR\nsubmodifier is given, this only examines non-elided characters, otherwise all\ncharacters (elided or not) are examined.\n.PP\nIf more than one modifier is present then they are applied in left-to-right\norder. For example, the index\n.QW \"\\fBend \\- 1 chars\\fR\"\nrefers to the next-to-last character in the text and\n.QW \"\\fBinsert wordstart \\- 1 c\\fR\"\nrefers to the character just before the first one in the word containing the\ninsertion cursor. Modifiers are applied one by one in this left to right\norder, and after each step the resulting index is constrained to be a valid\nindex in the text widget. So, for example, the index\n.QW \"\\fB1.0 \\-1c +1c\\fR\"\nrefers to the index\n.QW \\fB2.0\\fR .\n.PP\nWhere modifiers result in index changes by display lines, display chars or\ndisplay indices, and the \\fIbase\\fR refers to an index inside an elided tag,\nthat base index is considered to be equivalent to the first following\nnon-elided index.\n.SH TAGS\n.PP\nThe first form of annotation in text widgets is a tag. A tag is a textual\nstring that is associated with some of the characters in a text. Tags may\ncontain arbitrary characters, but it is probably best to avoid using the\ncharacters\n.QW \" \"\n(space), \\fB+\\fR, or \\fB\\-\\fR: these characters have special meaning in\nindices, so tags containing them cannot be used as indices. There may be any\nnumber of tags associated with characters in a text. Each tag may refer to a\nsingle character, a range of characters, or several ranges of characters. An\nindividual character may have any number of tags associated with it.\n.PP\nA priority order is defined among tags, and this order is used in implementing\nsome of the tag-related functions described below. When a tag is defined (by\nassociating it with characters or setting its display options or binding\ncommands to it), it is given a priority higher than any existing tag. The\npriority order of tags may be redefined using the\n.QW \"\\fIpathName \\fBtag raise\\fR\"\nand\n.QW \"\\fIpathName \\fBtag lower\\fR\"\nwidget commands.\n.PP\nTags serve three purposes in text widgets. First, they control the way\ninformation is displayed on the screen. By default, characters are displayed\nas determined by the \\fB\\-background\\fR, \\fB\\-font\\fR, and \\fB\\-foreground\\fR\noptions for the text widget. However, display options may be associated with\nindividual tags using the\n.QW \"\\fIpathName \\fBtag configure\\fR\"\nwidget command. If a character has been tagged, then the display options\nassociated with the tag override the default display style. The following\noptions are currently supported for tags:\n.\\\" OPTION: -background\n.TP\n\\fB\\-background \\fIcolor\\fR\n.\n\\fIColor\\fR specifies the background color to use for characters associated\nwith the tag. It may have any of the forms accepted by \\fBTk_GetColor\\fR.\n.\\\" OPTION: -bgstipple\n.TP\n\\fB\\-bgstipple \\fIbitmap\\fR\n.\n\\fIBitmap\\fR specifies a bitmap that is used as a stipple pattern for the\nbackground. It may have any of the forms accepted by \\fBTk_GetBitmap\\fR. If\n\\fIbitmap\\fR has not been specified, or if it is specified as an empty string,\nthen a solid fill will be used for the background.\n.\\\" OPTION: -borderwidth\n.TP\n\\fB\\-borderwidth \\fIpixels\\fR\n.\n\\fIPixels\\fR specifies the width of a border to draw around the tag using any\nof the forms accepted by \\fBTk_GetPixels\\fR. This option should be used in\nconjunction with the \\fB\\-relief\\fR option to provide the desired border.\n.\\\" OPTION: -elide\n.TP\n\\fB\\-elide \\fIboolean\\fR\n.\n\\fIElide\\fR specifies whether the data should be elided. Elided data\n(characters, images, embedded windows, etc.) is not displayed and takes no\nspace on screen, but further on behaves just as normal data.\n.\\\" OPTION: -fgstipple\n.TP\n\\fB\\-fgstipple \\fIbitmap\\fR\n.\n\\fIBitmap\\fR specifies a bitmap that is used as a stipple pattern when drawing\ntext and other foreground information such as underlines. It may have any of\nthe forms accepted by \\fBTk_GetBitmap\\fR. If \\fIbitmap\\fR has not been\nspecified, or if it is specified as an empty string, then a solid fill will be\nused.\n.\\\" OPTION: -font\n.TP\n\\fB\\-font \\fIfontName\\fR\n.\n\\fIFontName\\fR is the name of a font to use for drawing characters. It may\nhave any of the forms accepted by \\fBTk_GetFont\\fR.\n.\\\" OPTION: -foreground\n.TP\n\\fB\\-foreground \\fIcolor\\fR\n.\n\\fIColor\\fR specifies the color to use when drawing text and other foreground\ninformation such as underlines. It may have any of the forms accepted by\n\\fBTk_GetColor\\fR.\n.\\\" OPTION: -justify\n.TP\n\\fB\\-justify \\fIjustify\\fR\n.\nIf the first non-elided character of a display line has a tag for which this\noption has been specified, then \\fIjustify\\fR determines how to justify the\nline. It must be one of \\fBleft\\fR, \\fBright\\fR, or \\fBcenter\\fR. If a line\nwraps, then the justification for each line on the display is determined by\nthe first non-elided character of that display line.\n.\\\" OPTION: -lmargin1\n.TP\n\\fB\\-lmargin1 \\fIpixels\\fR\n.\nIf the first non-elided character of a text line has a tag for which this\noption has been specified, then \\fIpixels\\fR specifies how much the line\nshould be indented from the left edge of the window. \\fIPixels\\fR may have any\nof the standard forms for screen distances. If a line of text wraps, this\noption only applies to the first line on the display; the \\fB\\-lmargin2\\fR\noption controls the indentation for subsequent lines.\n.\\\" OPTION: -lmargin2\n.TP\n\\fB\\-lmargin2 \\fIpixels\\fR\n.\nIf the first non-elided character of a display line has a tag for which this\noption has been specified, and if the display line is not the first for its\ntext line (i.e., the text line has wrapped), then \\fIpixels\\fR specifies how\nmuch the line should be indented from the left edge of the window.\n\\fIPixels\\fR may have any of the standard forms for screen distances. This\noption is only used when wrapping is enabled, and it only applies to the\nsecond and later display lines for a text line.\n.\\\" OPTION: -lmargincolor\n.TP\n\\fB\\-lmargincolor \\fIcolor\\fR\n.\n\\fIColor\\fR specifies the background color to use in regions that do not\ncontain characters because they are indented by \\fB\\-lmargin1\\fR or\n\\fB\\-lmargin2\\fR. It may have any of the forms accepted by\n\\fBTk_GetColor\\fR. If \\fIcolor\\fR has not been specified, or if it is\nspecified as an empty string, then the color used is specified by the\n\\fB\\-background\\fR tag option (or, if this is also unspecified, by the\n\\fB\\-background\\fR widget option).\n.\\\" OPTION: -offset\n.TP\n\\fB\\-offset \\fIpixels\\fR\n.\n\\fIPixels\\fR specifies an amount by which the text's baseline should be offset\nvertically from the baseline of the overall line, in pixels. For example, a\npositive offset can be used for superscripts and a negative offset can be used\nfor subscripts. \\fIPixels\\fR may have any of the standard forms for screen\ndistances.\n.\\\" OPTION: -overstrike\n.TP\n\\fB\\-overstrike \\fIboolean\\fR\n.\nSpecifies whether or not to draw a horizontal rule through the middle of\ncharacters. \\fIBoolean\\fR may have any of the forms accepted by\n\\fBTcl_GetBoolean\\fR.\n.\\\" OPTION: -overstrikefg\n.TP\n\\fB\\-overstrikefg \\fIcolor\\fR\n.\n\\fIColor\\fR specifies the color to use when displaying the overstrike. It may\nhave any of the forms accepted by \\fBTk_GetColor\\fR. If \\fIcolor\\fR has not\nbeen specified, or if it is specified as an empty string, then the color\nspecified by the \\fB\\-foreground\\fR tag option is used.\n.\\\" OPTION: -relief\n.TP\n\\fB\\-relief \\fIrelief\\fR\n.\n\\fIRelief\\fR specifies the relief style to use for drawing the border, in any\nof the forms accepted by \\fBTk_GetRelief\\fR. This option is used in\nconjunction with the \\fB\\-borderwidth\\fR option to enable to the desired\nborder appearance.\n.\\\" OPTION: -rmargin\n.TP\n\\fB\\-rmargin \\fIpixels\\fR\n.\nIf the first non-elided character of a display line has a tag for which this\noption has been specified, then \\fIpixels\\fR specifies how wide a margin to\nleave between the end of the line and the right edge of the window.\n\\fIPixels\\fR may have any of the standard forms for screen distances. This\noption is only used when wrapping is enabled. If a text line wraps, the right\nmargin for each line on the display is determined by the first non-elided\ncharacter of that display line.\n.\\\" OPTION: -rmargincolor\n.TP\n\\fB\\-rmargincolor \\fIcolor\\fR\n.\n\\fIColor\\fR specifies the background color to use in regions that do not\ncontain characters because they are indented by \\fB\\-rmargin\\fR. It may\nhave any of the forms accepted by \\fBTk_GetColor\\fR. If \\fIcolor\\fR has not\nbeen specified, or if it is specified as an empty string, then the color\nused is specified by the \\fB\\-background\\fR tag option (or, if this is also\nunspecified, by the \\fB\\-background\\fR widget option).\n.\\\" OPTION: -selectbackground\n.TP\n\\fB\\-selectbackground \\fIcolor\\fR\n.\n\\fIColor\\fR specifies the background color to use when displaying selected\nitems. It may have any of the forms accepted by \\fBTk_GetColor\\fR. If\n\\fIcolor\\fR has not been specified, or if it is specified as an empty\nstring, then the color specified by the \\fB\\-background\\fR tag option is\nused.\n.\\\" OPTION: -selectforeground\n.TP\n\\fB\\-selectforeground \\fIcolor\\fR\n.\n\\fIColor\\fR specifies the foreground color to use when displaying selected\nitems. It may have any of the forms accepted by \\fBTk_GetColor\\fR. If\n\\fIcolor\\fR has not been specified, or if it is specified as an empty\nstring, then the color specified by the \\fB\\-foreground\\fR tag option is\nused.\n.\\\" OPTION: -spacing1\n.TP\n\\fB\\-spacing1 \\fIpixels\\fR\n.\n\\fIPixels\\fR specifies how much additional space should be left above each\ntext line, using any of the standard forms for screen distances. If a line\nwraps, this option only applies to the first line on the display.\n.\\\" OPTION: -spacing2\n.TP\n\\fB\\-spacing2 \\fIpixels\\fR\n.\nFor lines that wrap, this option specifies how much additional space to leave\nbetween the display lines for a single text line. \\fIPixels\\fR may have any of\nthe standard forms for screen distances.\n.\\\" OPTION: -spacing3\n.TP\n\\fB\\-spacing3 \\fIpixels\\fR\n.\n\\fIPixels\\fR specifies how much additional space should be left below each\ntext line, using any of the standard forms for screen distances. If a line\nwraps, this option only applies to the last line on the display.\n.\\\" OPTION: -tabs\n.TP\n\\fB\\-tabs \\fItabList\\fR\n.\n\\fITabList\\fR specifies a set of tab stops in the same form as for the\n\\fB\\-tabs\\fR option for the text widget. This option only applies to a display\nline if it applies to the first non-elided character on that display line. If\nthis option is specified as an empty string, it cancels the option, leaving it\nunspecified for the tag (the default). If the option is specified as a\nnon-empty string that is an empty list, such as \\fB\\-tags\\0{\\0}\\fR, then it\nrequests default 8-character tabs as described for the \\fB\\-tags\\fR widget\noption.\n.\\\" OPTION: -tabstyle\n.TP\n\\fB\\-tabstyle \\fIstyle\\fR\n.\n\\fIStyle\\fR specifies either the \\fItabular\\fR or \\fIwordprocessor\\fR style of\ntabbing to use for the text widget. This option only applies to a display line\nif it applies to the first non-elided character on that display line. If this\noption is specified as an empty string, it cancels the option, leaving it\nunspecified for the tag (the default).\n.\\\" OPTION: -underline\n.TP\n\\fB\\-underline \\fIboolean\\fR\n.\n\\fIBoolean\\fR specifies whether or not to draw an underline underneath\ncharacters. It may have any of the forms accepted by \\fBTcl_GetBoolean\\fR.\n.\\\" OPTION: -underlinefg\n.TP\n\\fB\\-underlinefg \\fIcolor\\fR\n.\n\\fIColor\\fR specifies the color to use when displaying the underline. It may\nhave any of the forms accepted by \\fBTk_GetColor\\fR. If \\fIcolor\\fR has not\nbeen specified, or if it is specified as an empty string, then the color\nspecified by the \\fB\\-foreground\\fR tag option is used.\n.\\\" OPTION: -wrap\n.TP\n\\fB\\-wrap \\fImode\\fR\n.\n\\fIMode\\fR specifies how to handle lines that are wider than the text's\nwindow. This option only applies to a display line if it applies to the\nfirst non-elided character on that display line. It has the same legal\nvalues as the \\fB\\-wrap\\fR option for the text widget: \\fBnone\\fR,\n\\fBchar\\fR, or \\fBword\\fR. If this tag option is specified, it\noverrides the \\fB\\-wrap\\fR option for the text widget.\n.PP\nIf a character has several tags associated with it, and if their display\noptions conflict, then the options of the highest priority tag are used. If a\nparticular display option has not been specified for a particular tag, or if\nit is specified as an empty string, then that option will never be used; the\nnext-highest-priority tag's option will used instead. If no tag specifies a\nparticular display option, then the default style for the widget will be used.\n.PP\nThe second purpose for tags is event bindings. You can associate bindings with\na tag in much the same way you can associate bindings with a widget class:\nwhenever particular X events occur on characters with the given tag, a given\nTcl command will be executed. Tag bindings can be used to give behaviors to\nranges of characters; among other things, this allows hypertext-like features\nto be implemented. For details, see the description of the\n.QW \"\\fIpathName \\fBtag bind\\fR\"\nwidget command below. Tag bindings are shared between all peer widgets\n(including any bindings for the special \\fBsel\\fR tag).\n.PP\nThe third use for tags is in managing the selection. See \\fBTHE SELECTION\\fR\nbelow. With the exception of the special \\fBsel\\fR tag, all tags are shared\nbetween peer text widgets, and may be manipulated on an equal basis from any\nsuch widget. The \\fBsel\\fR tag exists separately and independently in each\npeer text widget (but any tag bindings to \\fBsel\\fR are shared).\n.SH MARKS\n.PP\nThe second form of annotation in text widgets is a mark. Marks are used for\nremembering particular places in a text. They are something like tags, in that\nthey have names and they refer to places in the file, but a mark is not\nassociated with particular characters. Instead, a mark is associated with the\ngap between two characters. Only a single position may be associated with a\nmark at any given time. If the characters around a mark are deleted the mark\nwill still remain; it will just have new neighbor characters. In contrast, if\nthe characters containing a tag are deleted then the tag will no longer have\nan association with characters in the file. Marks may be manipulated with the\n.QW \"\\fIpathName \\fBmark\\fR\"\nwidget command, and their current locations may be determined by using the\nmark name as an index in widget commands.\n.PP\nEach mark also has a\n.QW gravity ,\nwhich is either \\fBleft\\fR or \\fBright\\fR. The gravity for a mark specifies\nwhat happens to the mark when text is inserted at the point of the mark. If a\nmark has left gravity, then the mark is treated as if it were attached to the\ncharacter on its left, so the mark will remain to the left of any text\ninserted at the mark position. If the mark has right gravity, new text\ninserted at the mark position will appear to the left of the mark (so that the\nmark remains rightmost). The gravity for a mark defaults to \\fBright\\fR.\n.PP\nThe name space for marks is different from that for tags: the same name may be\nused for both a mark and a tag, but they will refer to different things.\n.PP\nTwo marks have special significance. First, the mark \\fBinsert\\fR is\nassociated with the insertion cursor, as described under\n\\fBTHE INSERTION CURSOR\\fR\nbelow. Second, the mark \\fBcurrent\\fR is associated with the\ncharacter closest to the mouse and is adjusted automatically to track the\nmouse position and any changes to the text in the widget (one exception:\n\\fBcurrent\\fR is not updated in response to mouse motions if a mouse button is\ndown; the update will be deferred until all mouse buttons have been released).\nNeither of these special marks may be deleted. With the exception of these two\nspecial marks, all marks are shared between peer text widgets, and may be\nmanipulated on an equal basis from any peer.\n.SH \"EMBEDDED WINDOWS\"\n.PP\nThe third form of annotation in text widgets is an embedded window. Each\nembedded window annotation causes a window to be displayed at a particular\npoint in the text. There may be any number of embedded windows in a text\nwidget, and any widget may be used as an embedded window (subject to the usual\nrules for geometry management, which require the text window to be the parent\nof the embedded window or a descendant of its parent).\n.PP\nThe embedded window's position on the screen will be updated as the text is\nmodified or scrolled, and it will be mapped and unmapped as it moves into and\nout of the visible area of the text widget. Each embedded window occupies one\nunit's worth of index space in the text widget, and it may be referred to\neither by the name of its embedded window or by its position in the widget's\nindex space. If the range of text containing the embedded window is deleted\nthen the window is destroyed. Similarly if the text widget as a whole is\ndeleted, then the window is destroyed.\n.PP\nEliding an embedded window immediately after scheduling it for creation via\n\\fIpathName \\fBwindow create \\fIindex \\fB\\-create\\fR will prevent it from being\neffectively created. Uneliding an elided embedded window scheduled for creation\nvia \\fIpathName \\fBwindow create \\fIindex \\fB\\-create\\fR will automatically\ntrigger the associated creation script. After destroying an elided embedded\nwindow, the latter won't get automatically recreated.\n.PP\nWhen an embedded window is added to a text widget with the \\fIpathName\n\\fBwindow create\\fR widget command, several configuration options may be\nassociated with it. These options may be modified later with the \\fIpathName\n\\fBwindow configure\\fR widget command. The following options are currently\nsupported:\n.\\\" OPTION: -align\n.TP\n\\fB\\-align \\fIwhere\\fR\n.\nIf the window is not as tall as the line in which it is displayed, this option\ndetermines where the window is displayed in the line. \\fIWhere\\fR must have\none of the values \\fBtop\\fR (align the top of the window with the top of the\nline), \\fBcenter\\fR (center the window within the range of the line),\n\\fBbottom\\fR (align the bottom of the window with the bottom of the line's\narea), or \\fBbaseline\\fR (align the bottom of the window with the baseline of\nthe line).\n.\\\" OPTION: -create\n.TP\n\\fB\\-create \\fIscript\\fR\n.\nSpecifies a Tcl script that may be evaluated to create the window for the\nannotation. If no \\fB\\-window\\fR option has been specified for the annotation\nthis script will be evaluated when the annotation is about to be displayed on\nthe screen. \\fIScript\\fR must create a window for the annotation and return\nthe name of that window as its result. Two substitutions will be performed in\n\\fIscript\\fR before evaluation. \\fI%W\\fR will be substituted by the name of\nthe parent text widget, and \\fI%%\\fR will be substituted by a single \\fI%\\fR.\nIf the annotation's window should ever be deleted, \\fIscript\\fR will be\nevaluated again the next time the annotation is displayed.\n.\\\" OPTION: -padx\n.TP\n\\fB\\-padx \\fIpixels\\fR\n.\n\\fIPixels\\fR specifies the amount of extra space to leave on each side of the\nembedded window. It may have any of the usual forms defined for a screen\ndistance.\n.\\\" OPTION: -pady\n.TP\n\\fB\\-pady \\fIpixels\\fR\n.\n\\fIPixels\\fR specifies the amount of extra space to leave on the top and on\nthe bottom of the embedded window. It may have any of the usual forms defined\nfor a screen distance.\n.\\\" OPTION: -stretch\n.TP\n\\fB\\-stretch \\fIboolean\\fR\n.\nIf the requested height of the embedded window is less than the height of the\nline in which it is displayed, this option can be used to specify whether the\nwindow should be stretched vertically to fill its line. If the \\fB\\-pady\\fR\noption has been specified as well, then the requested padding will be retained\neven if the window is stretched.\n.\\\" OPTION: -window\n.TP\n\\fB\\-window \\fIpathName\\fR\n.\nSpecifies the name of a window to display in the annotation. Note that if a\n\\fIpathName\\fR has been set, then later configuring a window to the empty\nstring will not delete the widget corresponding to the old \\fIpathName\\fR.\nRather it will remove the association between the old \\fIpathName\\fR and the\ntext widget. If multiple peer widgets are in use, it is usually simpler to use\nthe \\fB\\-create\\fR option if embedded windows are desired in each peer.\n.SH \"EMBEDDED IMAGES\"\n.PP\nThe final form of annotation in text widgets is an embedded image. Each\nembedded image annotation causes an image to be displayed at a particular\npoint in the text. There may be any number of embedded images in a text\nwidget, and a particular image may be embedded in multiple places in the same\ntext widget.\n.PP\nThe embedded image's position on the screen will be updated as the text is\nmodified or scrolled. Each embedded image occupies one unit's worth of index\nspace in the text widget, and it may be referred to either by its position in\nthe widget's index space, or the name it is assigned when the image is inserted\ninto the text widget with \\fIpathName \\fBimage create\\fR. If the range of text\ncontaining the embedded image is deleted then that copy of the image is removed\nfrom the screen.\n.PP\nEliding an embedded image immediately after scheduling it for creation via\n\\fIpathName \\fBimage create \\fIindex \\fB\\-create\\fR will prevent it from being\neffectively created. Uneliding an elided embedded image scheduled for creation\nvia \\fIpathName \\fBimage create \\fIindex \\fB\\-create\\fR will automatically\ntrigger the associated creation script. After destroying an elided embedded\nimage, the latter won't get automatically recreated.\n.PP\nWhen an embedded image is added to a text widget with the \\fIpathName \\fBimage\ncreate\\fR widget command, a name unique to this instance of the image is\nreturned. This name may then be used to refer to this image instance. The name\nis taken to be the value of the \\fB\\-name\\fR option (described below). If the\n\\fB\\-name\\fR option is not provided, the \\fB\\-image\\fR name is used instead.\nIf the \\fIimageName\\fR is already in use in the text widget, then \\fB#\\fInn\\fR\nis added to the end of the \\fIimageName\\fR, where \\fInn\\fR is an arbitrary\ninteger. This insures the \\fIimageName\\fR is unique. Once this name is\nassigned to this instance of the image, it does not change, even though the\n\\fB\\-image\\fR or \\fB\\-name\\fR values can be changed with \\fIpathName \\fBimage\nconfigure\\fR.\n.PP\nWhen an embedded image is added to a text widget with the \\fIpathName \\fBimage\ncreate\\fR widget command, several configuration options may be associated with\nit. These options may be modified later with the \\fIpathName \\fBimage\nconfigure\\fR widget command. The following options are currently supported:\n.\\\" OPTION: -align\n.TP\n\\fB\\-align \\fIwhere\\fR\n.\nIf the image is not as tall as the line in which it is displayed, this option\ndetermines where the image is displayed in the line. \\fIWhere\\fR must have one\nof the values \\fBtop\\fR (align the top of the image with the top of the line),\n\\fBcenter\\fR (center the image within the range of the line), \\fBbottom\\fR\n(align the bottom of the image with the bottom of the line's area), or\n\\fBbaseline\\fR (align the bottom of the image with the baseline of the line).\n.\\\" OPTION: -image\n.TP\n\\fB\\-image \\fIimage\\fR\n.\nSpecifies the name of the Tk image to display in the annotation. If\n\\fIimage\\fR is not a valid Tk image, then an error is returned.\n.\\\" OPTION: -name\n.TP\n\\fB\\-name \\fIImageName\\fR\n.\nSpecifies the name by which this image instance may be referenced in the text\nwidget. If \\fIImageName\\fR is not supplied, then the name of the Tk image is\nused instead. If the \\fIimageName\\fR is already in use, \\fI#nn\\fR is appended\nto the end of the name as described above.\n.\\\" OPTION: -padx\n.TP\n\\fB\\-padx \\fIpixels\\fR\n.\n\\fIPixels\\fR specifies the amount of extra space to leave on each side of the\nembedded image. It may have any of the usual forms defined for a screen\ndistance.\n.\\\" OPTION: -pady\n.TP\n\\fB\\-pady \\fIpixels\\fR\n.\n\\fIPixels\\fR specifies the amount of extra space to leave on the top and on\nthe bottom of the embedded image. It may have any of the usual forms defined\nfor a screen distance.\n.SH \"THE SELECTION\"\n.PP\nSelection support is implemented via tags. If the \\fB\\-exportselection\\fR option\nfor the text widget is true then the \\fBsel\\fR tag will be associated with the\nselection:\n.IP [1]\nWhenever characters are tagged with \\fBsel\\fR the text widget will claim\nownership of the selection.\n.IP [2]\nAttempts to retrieve the selection will be serviced by the text widget,\nreturning all the characters with the \\fBsel\\fR tag.\n.IP [3]\nIf the selection is claimed away by another application or by another window\nwithin this application, then the \\fBsel\\fR tag will be removed from all\ncharacters in the text.\n.IP [4]\nWhenever the \\fBsel\\fR tag range changes a virtual event \\fB<>\\fR\nis generated.\nIt might also be generated when selection is affected but not actually changed.\nFurther, multiple selection changes could happen before events can be processed\nleading to multiple events with the same visible selection.\n.PP\nThe \\fBsel\\fR tag is automatically defined when a text widget is created, and\nit may not be deleted with the\n.QW \"\\fIpathName \\fBtag delete\\fR\"\nwidget command. Furthermore, the \\fB\\-selectbackground\\fR,\n\\fB\\-selectborderwidth\\fR, and \\fB\\-selectforeground\\fR options for the text\nwidget are tied to the \\fB\\-background\\fR, \\fB\\-borderwidth\\fR, and\n\\fB\\-foreground\\fR options for the \\fBsel\\fR tag: changes in either will\nautomatically be reflected in the other. Also the\n\\fB\\-inactiveselectbackground\\fR option for the text widget is used instead of\n\\fB\\-selectbackground\\fR when the text widget does not have the focus. This\nallows programmatic control over the visualization of the \\fBsel\\fR tag for\nforeground and background windows, or to have \\fBsel\\fR not shown at all (when\n\\fB\\-inactiveselectbackground\\fR is empty) for background windows. Each peer\ntext widget has its own \\fBsel\\fR tag which can be separately configured and\nset.\n.SH \"THE INSERTION CURSOR\"\n.PP\nThe mark named \\fBinsert\\fR has special significance in text widgets. It is\ndefined automatically when a text widget is created and it may not be unset\nwith the\n.QW \"\\fIpathName \\fBmark unset\\fR\"\nwidget command. The \\fBinsert\\fR mark represents the position of the insertion\ncursor, and the insertion cursor will automatically be drawn at this point\nwhenever the text widget has the input focus.\n.SH \"THE MODIFIED FLAG\"\n.PP\nThe text widget can keep track of changes to the content of the widget by\nmeans of the modified flag. Inserting or deleting text will set this flag. The\nflag can be queried, set and cleared programmatically as well. Whenever the\nflag changes state a \\fB<>\\fR virtual event is generated. See the\n\\fIpathName \\fBedit modified\\fR widget command for more details.\n.SH \"THE UNDO MECHANISM\"\n.PP\nThe text widget has an unlimited undo and redo mechanism (when the\n\\fB\\-undo\\fR widget option is true) which records every insert and delete\naction on a stack.\n.PP\nBoundaries (called\n.QW separators )\nare inserted between edit actions. The purpose of these separators is to group\ninserts, deletes and replaces into one compound edit action. When undoing a\nchange everything between two separators will be undone. The undone changes\nare then moved to the redo stack, so that an undone edit can be redone again.\nThe redo stack is cleared whenever new edit actions are recorded on the undo\nstack. The undo and redo stacks can be cleared to keep their depth under\ncontrol.\n.PP\nSeparators are inserted automatically when the \\fB\\-autoseparators\\fR widget\noption is true. You can insert separators programmatically as well. If a\nseparator is already present at the top of the undo stack no other will be\ninserted. That means that two separators on the undo stack are always\nseparated by at least one insert or delete action.\n.PP\nThe \\fB<>\\fR virtual event is generated every time the undo stack\nor the redo stack becomes empty or unempty.\n.PP\nThe undo mechanism is also linked to the modified flag. This means that\nundoing or redoing changes can take a modified text widget back to the\nunmodified state or vice versa. The modified flag will be set automatically to\nthe appropriate state. This automatic coupling does not work when the modified\nflag has been set by the user, until the flag has been reset again.\n.PP\nSee below for the \\fIpathName \\fBedit\\fR widget command that controls the undo\nmechanism.\n.SH \"PEER WIDGETS\"\n.PP\nThe text widget has a separate store of all its data concerning each line's\ntextual contents, marks, tags, images and windows, and the undo stack.\n.PP\nWhile this data store cannot be accessed directly (i.e. without a text widget\nas an intermediary), multiple text widgets can be created, each of which\npresent different views on the same underlying data. Such text widgets are\nknown as peer text widgets.\n.PP\nAs text is added, deleted, edited and coloured in any one widget, and as\nimages, marks, tags are adjusted, all such changes will be reflected in all\npeers.\n.PP\nAll data and markup is shared, except for a few small details. First, the\n\\fBsel\\fR tag may be set and configured (in its display style) differently for\neach peer. Second, each peer has its own \\fBinsert\\fR and \\fBcurrent\\fR mark\npositions (but all other marks are shared). Third, embedded windows, which are\narbitrary other widgets, cannot be shared between peers. This means the\n\\fB\\-window\\fR option of embedded windows is independently set for each peer\n(it is advisable to use the \\fB\\-create\\fR script capabilities to allow each\npeer to create its own embedded windows as needed). Fourth, all of the\nconfiguration options of each peer (e.g. \\fB\\-font\\fR, etc) can be set\nindependently, with the exception of \\fB\\-undo\\fR, \\fB\\-maxundo\\fR,\n\\fB\\-autoseparators\\fR (i.e. all undo, redo and modified state issues are\nshared).\n.PP\nFinally any single peer need not contain all lines from the underlying data\nstore. When creating a peer, a contiguous range of lines (e.g. only lines 52\nthrough 125) may be specified. This allows a peer to contain just a small\nportion of the overall text. The range of lines will expand and contract as\ntext is inserted or deleted. The peer will only ever display complete lines of\ntext (one cannot share just part of a line). If the peer's contents contracts\nto nothing (i.e. all complete lines in the peer widget have been deleted from\nanother widget), then it is impossible for new lines to be inserted. The peer\nwill simply become an empty shell on which the background can be configured,\nbut which will never show any content (without manual reconfiguration of the\nstart and end lines). Note that a peer which does not contain all of the\nunderlying data store still has indices numbered from\n.QW 1.0\nto\n.QW end .\nIt is simply that those indices reflect a subset of the total data, and data\noutside the contained range is not accessible to the peer. This means that the\ncommand \\fIpeerName \\fBindex end\\fR may return quite different values in\ndifferent peers. Similarly, commands like \\fIpeerName \\fBtag ranges\\fR will\nnot return index ranges outside that which is meaningful to the peer. The\nconfiguration options \\fB\\-startline\\fR and \\fB\\-endline\\fR may be used to\ncontrol how much of the underlying data is contained in any given text widget.\n.PP\nNote that peers are really peers. Deleting the\n.QW original\ntext widget will not cause any other peers to be deleted, or otherwise\naffected.\n.PP\nSee below for the \\fIpathName \\fBpeer\\fR widget command that controls the\ncreation of peer widgets.\n.SH \"ASYNCHRONOUS UPDATE OF LINE HEIGHTS\"\n.PP\nIn order to maintain a responsive user-experience, the text widget calculates\nlines metrics (line heights in pixels) asynchronously. Because of this, some\ncommands of the text widget may return wrong results if the asynchronous\ncalculations are not finished at the time of calling. This applies to\n\\fIpathName \\fBcount \\-ypixels\\fR and \\fIpathName \\fByview\\fR.\n.PP\nAgain for performance reasons, it would not be appropriate to let these\ncommands always wait for the end of the update calculation each time they are\ncalled. In most use cases of these commands a more or less inaccurate result\ndoes not really matter compared to execution speed.\n.PP\nIn case accurate result is needed (and if the text widget is managed by a\ngeometry manager), one can resort to \\fIpathName \\fBsync\\fR and \\fIpathName\n\\fBpendingsync\\fR to control the synchronization of the view of text widgets.\n.PP\nThe \\fB<>\\fR virtual event fires when the line heights of the\ntext widget become obsolete (due to some editing command or configuration\nchange), and again when the internal data of the text widget are back in sync\nwith the widget view. The detail field (%d substitution) is either true (when\nthe widget is in sync) or false (when it is not).\n.PP\n\\fIpathName \\fBsync\\fR, \\fIpathName \\fBpendingsync\\fR and\n\\fB<>\\fR apply to each text widget independently of its peers.\n.PP\nExamples of use:\n.CS\n## Example 1:\n# immediately complete line metrics at any cost (GUI unresponsive)\n$w sync\n$w yview moveto $fraction\n\n## Example 2:\n# synchronously wait for up-to-date line metrics (GUI responsive)\n# before executing the scheduled command, but don't block execution flow\n$w sync -command [list $w yview moveto $fraction]\n\n## Example 3:\n# init\nset yud($w) 0\nproc updateaction w {\n\\&set ::yud($w) 1\n\\&# any other update action here...\n}\n# runtime, synchronously wait for up-to-date line metrics (GUI responsive)\n$w sync -command [list updateaction $w]\nvwait yud($w)\n$w yview moveto $fraction\n\n## Example 4:\n# init\nset todo($w) {}\nproc updateaction w {\n\\&foreach cmd $::todo($w) {uplevel #0 $cmd}\n\\&set todo($w) {}\n}\n# runtime\nlappend todo($w) [list $w yview moveto $fraction]\n$w sync -command [list updateaction $w]\n\n## Example 5:\n# init\nset todo($w) {}\nbind $w <> {\n\\&if {%d} {\n\\&\\&foreach cmd $todo(%W) {eval $cmd}\n\\&\\&set todo(%W) {}\n\\&}\n}\n# runtime\nif {![$w pendingsync]} {\n\\&$w yview moveto $fraction\n} else {\n\\&lappend todo($w) [list $w yview moveto $fraction]\n}\n.CE\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBtext\\fR command creates a new Tcl command whose name is the same as the\npath name of the text's window. This command may be used to invoke various\noperations on the widget. It has the following general form:\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n\\fIPathName\\fR is the name of the command, which is the same as the text\nwidget's path name. \\fIOption\\fR and the \\fIarg\\fRs determine the exact\nbehavior of the command. The following commands are possible for text widgets:\n.\\\" METHOD: bbox\n.TP\n\\fIpathName \\fBbbox \\fIindex\\fR\n.\nReturns a list of four elements describing the screen area of the character\ngiven by \\fIindex\\fR. The first two elements of the list give the x and y\ncoordinates of the upper-left corner of the area occupied by the character,\nand the last two elements give the width and height of the area. If the\ncharacter is only partially visible on the screen, then the return value\nreflects just the visible part. If the character is not visible on the screen\nthen the return value is an empty list.\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget\\fI option\\fR\n.\nReturns the current value of the configuration option given by \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBtext\\fR command.\n.\\\" METHOD: compare\n.TP\n\\fIpathName \\fBcompare\\fI index1 op index2\\fR\n.\nCompares the indices given by \\fIindex1\\fR and \\fIindex2\\fR according to the\nrelational operator given by \\fIop\\fR, and returns 1 if the relationship is\nsatisfied and 0 if it is not. \\fIOp\\fR must be one of the operators <, <=, ==,\n>=, >, or !=. If \\fIop\\fR is == then 1 is returned if the two indices refer to\nthe same character, if \\fIop\\fR is < then 1 is returned if \\fIindex1\\fR refers\nto an earlier character in the text than \\fIindex2\\fR, and so on.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget. If no \\fIoption\\fR is\nspecified, returns a list describing all of the available options for\n\\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for information on the format of\nthis list). If \\fIoption\\fR is specified with no \\fIvalue\\fR, then the command\nreturns a list describing the one named option (this list will be identical to\nthe corresponding sublist of the value returned if no \\fIoption\\fR is\nspecified). If one or more \\fIoption\\-value\\fR pairs are specified, then the\ncommand modifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string. \\fIOption\\fR may have any of\nthe values accepted by the \\fBtext\\fR command.\n.\\\" METHOD: count\n.TP\n\\fIpathName \\fBcount\\fR ?\\fIoptions\\fR? \\fIindex1 index2\\fR\n.\nCounts the number of relevant things between the two indices. If \\fIindex1\\fR\nis after \\fIindex2\\fR, the result will be a negative number (and this holds\nfor each of the possible options). The actual items which are counted depend\non the options given. The result is a list of integers, one for the result of\neach counting option given. Valid counting options are \\fB\\-chars\\fR,\n\\fB\\-displaychars\\fR, \\fB\\-displayindices\\fR, \\fB\\-displaylines\\fR,\n\\fB\\-indices\\fR, \\fB\\-lines\\fR, \\fB\\-xpixels\\fR and \\fB\\-ypixels\\fR. The\ndefault value, if no option is specified, is \\fB\\-indices\\fR. There is an\nadditional possible option \\fB\\-update\\fR which is a modifier. If given (and\nif the text widget is managed by a geometry manager), then all subsequent\noptions ensure that any possible out of date information is recalculated.\nThis currently only has any effect for the \\fB\\-ypixels\\fR count (which, if\n\\fB\\-update\\fR is not given, will use the text widget's current cached value\nfor each line). This \\fB\\-update\\fR option is obsoleted by \\fIpathName\n\\fBsync\\fR, \\fIpathName \\fBpendingsync\\fR and \\fB<>\\fR. The\ncount options are interpreted as follows:\n.RS\n.IP \\fB\\-chars\\fR\ncount all characters, whether elided or not. Do not count embedded windows or\nimages.\n.IP \\fB\\-displaychars\\fR\ncount all non-elided characters.\n.IP \\fB\\-displayindices\\fR\ncount all non-elided characters, windows and images.\n.IP \\fB\\-displaylines\\fR\ncount all display lines (i.e. counting one for each time a line wraps) from\nthe line of the first index up to, but not including the display line of the\nsecond index. Therefore if they are both on the same display line, zero will\nbe returned. By definition displaylines are visible and therefore this only\ncounts portions of actual visible lines.\n.IP \\fB\\-indices\\fR\ncount all characters and embedded windows or images (i.e. everything which\ncounts in text-widget index space), whether they are elided or not.\n.IP \\fB\\-lines\\fR\ncount all logical lines (irrespective of wrapping) from the line of the first\nindex up to, but not including the line of the second index. Therefore if they\nare both on the same line, zero will be returned. Logical lines are counted\nwhether they are currently visible (non-elided) or not.\n.IP \\fB\\-xpixels\\fR\ncount the number of horizontal pixels from the first pixel of the first index\nto (but not including) the first pixel of the second index. To count the total\ndesired width of the text widget (assuming wrapping is not enabled), first\nfind the longest line and then use\n.QW \".text count \\-xpixels \\N'34'${line}.0\\N'34' \\N'34'${line}.0 lineend\\N'34'\" .\n.IP \\fB\\-ypixels\\fR\ncount the number of vertical pixels from the first pixel of the first index to\n(but not including) the first pixel of the second index. If both indices are\non the same display line, zero will be returned. To count the total number of\nvertical pixels in the text widget, use\n.QW \".text count \\-ypixels 1.0 end\" ,\nand to ensure this is up to date, use\n.QW \".text count \\-update \\-ypixels 1.0 end\" .\n.PP\nThe command returns a positive or negative integer corresponding to the number\nof items counted between the two indices. One such integer is returned for\neach counting option given, so a list is returned if more than one option was\nsupplied. For example\n.QW \".text count \\-xpixels \\-ypixels 1.3 4.5\"\nis perfectly valid and will return a list of two elements.\n.RE\n.\\\" METHOD: debug\n.TP\n\\fIpathName \\fBdebug \\fR?\\fIboolean\\fR?\n.\nIf \\fIboolean\\fR is specified, then it must have one of the true or false\nvalues accepted by Tcl_GetBoolean. If the value is a true one then internal\nconsistency checks will be turned on in the B-tree code associated with text\nwidgets. If \\fIboolean\\fR has a false value then the debugging checks will be\nturned off. In either case the command returns an empty string. If\n\\fIboolean\\fR is not specified then the command returns \\fBon\\fR or \\fBoff\\fR\nto indicate whether or not debugging is turned on. There is a single debugging\nswitch shared by all text widgets: turning debugging on or off in any widget\nturns it on or off for all widgets. For widgets with large amounts of text,\nthe consistency checks may cause a noticeable slow-down.\n.RS\n.PP\nWhen debugging is turned on, the drawing routines of the text widget set the\nglobal variables \\fBtk_textRedraw\\fR and \\fBtk_textRelayout\\fR to the lists of\nindices that are redrawn. The values of these variables are tested by Tk's\ntest suite.\n.RE\n.\\\" METHOD: delete\n.TP\n\\fIpathName \\fBdelete \\fIindex1 \\fR?\\fIindex2 ...\\fR?\n.\nDelete a range of characters from the text.\nIf both \\fIindex1\\fR and \\fIindex2\\fR are specified, then delete\nall the characters starting with the one given by \\fIindex1\\fR\nand stopping just before \\fIindex2\\fR (i.e. the character at\n\\fIindex2\\fR is not deleted).\nIf \\fIindex2\\fR does not specify a position later in the text\nthan \\fIindex1\\fR then no characters are deleted.\nIf \\fIindex2\\fR is not specified then the single character at\n\\fIindex1\\fR is deleted.\nAttempts to delete characters in a way that would leave\nthe text without a newline as the last character will be tweaked by the\ntext widget to avoid this. In particular, deletion of complete lines of\ntext up to the end of the text will also delete the newline character just\nbefore the deleted block so that it is replaced by the new final newline\nof the text widget.\nThe command returns an empty string.\nIf more indices are given, multiple ranges of text will be deleted.\nAll indices are first checked for validity before any deletions are made.\nThey are sorted and the text is removed from the last range to the\nfirst range so deleted text does not cause an undesired index shifting\nside-effects. If multiple ranges with the same start index are given,\nthen the longest range is used. If overlapping ranges are given, then\nthey will be merged into spans that do not cause deletion of text\noutside the given ranges due to text shifted during deletion.\n.\\\" METHOD: dlineinfo\n.TP\n\\fIpathName \\fBdlineinfo \\fIindex\\fR\n.\nReturns a list with five elements describing the area occupied by the display\nline containing \\fIindex\\fR. The first two elements of the list give the x and\ny coordinates of the upper-left corner of the area occupied by the line, the\nthird and fourth elements give the width and height of the area, and the fifth\nelement gives the position of the baseline for the line, measured down from\nthe top of the area. All of this information is measured in pixels. If the\ncurrent wrap mode is \\fBnone\\fR and the line extends beyond the boundaries of\nthe window, the area returned reflects the entire area of the line, including\nthe portions that are out of the window. If the line is shorter than the full\nwidth of the window then the area returned reflects just the portion of the\nline that is occupied by characters and embedded windows. If the display line\ncontaining \\fIindex\\fR is not visible on the screen then the return value is\nan empty list.\n.\\\" METHOD: dump\n.TP\n\\fIpathName \\fBdump \\fR?\\fIswitches\\fR? \\fIindex1 \\fR?\\fIindex2\\fR?\n.\nReturn the contents of the text widget from \\fIindex1\\fR up to, but not\nincluding \\fIindex2\\fR, including the text and information about marks, tags,\nand embedded windows. If \\fIindex2\\fR is not specified, then it defaults to\none character past \\fIindex1\\fR. The information is returned in the following\nformat:\n.RS\n.LP\n\\fIkey1 value1 index1 key2 value2 index2\\fR ...\n.LP\nThe possible \\fIkey\\fR values are \\fBtext\\fR, \\fBmark\\fR, \\fBtagon\\fR,\n\\fBtagoff\\fR, \\fBimage\\fR, and \\fBwindow\\fR. The corresponding \\fIvalue\\fR is\nthe text, mark name, tag name, image name, or window name. The \\fIindex\\fR\ninformation is the index of the start of the text, mark, tag transition, image\nor window. One or more of the following switches (or abbreviations thereof)\nmay be specified to control the dump:\n.\\\" OPTION: -all\n.TP\n\\fB\\-all\\fR\n.\nReturn information about all elements: text, marks, tags, images and windows.\nThis is the default.\n.\\\" OPTION: -command\n.TP\n\\fB\\-command \\fIcommand\\fR\n.\nInstead of returning the information as the result of the dump operation,\ninvoke the \\fIcommand\\fR on each element of the text widget within the range.\nThe command has three arguments appended to it before it is evaluated: the\n\\fIkey\\fR, \\fIvalue\\fR, and \\fIindex\\fR.\n.\\\" OPTION: -image\n.TP\n\\fB\\-image\\fR\n.\nInclude information about images in the dump results.\n.\\\" OPTION: -mark\n.TP\n\\fB\\-mark\\fR\n.\nInclude information about marks in the dump results.\n.\\\" OPTION: -tag\n.TP\n\\fB\\-tag\\fR\n.\nInclude information about tag transitions in the dump results. Tag information\nis returned as \\fBtagon\\fR and \\fBtagoff\\fR elements that indicate the begin\nand end of each range of each tag, respectively.\n.\\\" OPTION: -text\n.TP\n\\fB\\-text\\fR\n.\nInclude information about text in the dump results. The value is the text up\nto the next element or the end of range indicated by \\fIindex2\\fR. A text\nelement does not span newlines. A multi-line block of text that contains no\nmarks or tag transitions will still be dumped as a set of text segments that\neach end with a newline. The newline is part of the value.\n.\\\" OPTION: -window\n.TP\n\\fB\\-window\\fR\n.\nInclude information about embedded windows in the dump results. The value of a\nwindow is its Tk pathname, unless the window has not been created yet. (It\nmust have a create script.) In this case an empty string is returned, and you\nmust query the window by its index position to get more information.\n.RE\n.\\\" METHOD: edit\n.TP\n\\fIpathName \\fBedit \\fIoption \\fR?\\fIarg ...\\fR?\n.\nThis command controls the undo mechanism and the modified flag. The exact\nbehavior of the command depends on the \\fIoption\\fR argument that follows the\n\\fBedit\\fR argument. The following forms of the command are currently\nsupported:\n.RS\n.TP\n\\fIpathName \\fBedit canredo\\fR\n.\nReturns a boolean true if redo is possible, i.e. when the redo stack is not\nempty. Otherwise returns false.\n.TP\n\\fIpathName \\fBedit canundo\\fR\n.\nReturns a boolean true if undo is possible, i.e. when the undo stack is not\nempty. Otherwise returns false.\n.TP\n\\fIpathName \\fBedit modified \\fR?\\fIboolean\\fR?\n.\nIf \\fIboolean\\fR is not specified, returns the modified flag of the widget.\nThe insert, delete, edit undo and edit redo commands or the user can set or\nclear the modified flag. If \\fIboolean\\fR is specified, sets the modified flag\nof the widget to \\fIboolean\\fR.\n.TP\n\\fIpathName \\fBedit redo\\fR\n.\nWhen the \\fB\\-undo\\fR option is true, reapplies the last undone edits provided\nno other edits were done since then, and returns a list of indices indicating\nwhat ranges were changed by the redo operation. Generates an error when the\nredo stack is empty. Does nothing when the \\fB\\-undo\\fR option is false.\n.TP\n\\fIpathName \\fBedit reset\\fR\n.\nClears the undo and redo stacks.\n.TP\n\\fIpathName \\fBedit separator\\fR\n.\nInserts a separator (boundary) on the undo stack. Does nothing when the\n\\fB\\-undo\\fR option is false.\n.TP\n\\fIpathName \\fBedit undo\\fR\n.\nUndoes the last edit action when the \\fB\\-undo\\fR option is true, and returns a\nlist of indices indicating what ranges were changed by the undo operation. An\nedit action is defined as all the insert and delete commands that are recorded\non the undo stack in between two separators. Generates an error when the undo\nstack is empty. Does nothing when the \\fB\\-undo\\fR option is false.\n.RE\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget\\fR ?\\fB\\-displaychars\\fR? ?\\fB\\-\\-\\fR? \\fIindex1\\fR ?\\fIindex2 ...\\fR?\n.\nReturn a range of characters from the text. The return value will be all the\ncharacters in the text starting with the one whose index is \\fIindex1\\fR and\nending just before the one whose index is \\fIindex2\\fR (the character at\n\\fIindex2\\fR will not be returned). If \\fIindex2\\fR is omitted then the single\ncharacter at \\fIindex1\\fR is returned. If there are no characters in the\nspecified range (e.g. \\fIindex1\\fR is past the end of the file or \\fIindex2\\fR\nis less than or equal to \\fIindex1\\fR) then an empty string is returned. If\nthe specified range contains embedded windows, no information about them is\nincluded in the returned string. If multiple index pairs are given, multiple\nranges of text will be returned in a list. Invalid ranges will not be\nrepresented with empty strings in the list. The ranges are returned in the\norder passed to \\fIpathName \\fBget\\fR. If the \\fB\\-displaychars\\fR option is\ngiven, then, within each range, only those characters which are not elided\nwill be returned. This may have the effect that some of the returned ranges\nare empty strings.\n.\\\" METHOD: image\n.TP\n\\fIpathName \\fBimage \\fIoption \\fR?\\fIarg ...\\fR?\n.\nThis command is used to manipulate embedded images. The behavior of the\ncommand depends on the \\fIoption\\fR argument that follows the \\fBimage\\fR\nargument. The following forms of the command are currently supported:\n.RS\n.TP\n\\fIpathName \\fBimage cget \\fIindex option\\fR\n.\nReturns the value of a configuration option for an embedded image. \\fIIndex\\fR\nidentifies the embedded image, and \\fIoption\\fR specifies a particular\nconfiguration option, which must be one of the ones listed in the section\n\\fBEMBEDDED IMAGES\\fR.\n.TP\n\\fIpathName \\fBimage configure \\fIindex\\fR ?\\fIoption value ...\\fR?\n.\nQuery or modify the configuration options for an embedded image. If no\n\\fIoption\\fR is specified, returns a list describing all of the available\noptions for the embedded image at \\fIindex\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified with no\n\\fIvalue\\fR, then the command returns a list describing the one named option\n(this list will be identical to the corresponding sublist of the value\nreturned if no \\fIoption\\fR is specified). If one or more \\fIoption\\-value\\fR\npairs are specified, then the command modifies the given option(s) to have the\ngiven value(s); in this case the command returns an empty string. See\n\\fBEMBEDDED IMAGES\\fR for information on the options that are supported.\n.TP\n\\fIpathName \\fBimage create \\fIindex\\fR ?\\fIoption value ...\\fR?\n.\nThis command creates a new image annotation, which will appear in the text at\nthe position given by \\fIindex\\fR. Any number of \\fIoption\\-value\\fR pairs may\nbe specified to configure the annotation. Returns a unique identifier that may\nbe used as an index to refer to this image. See \\fBEMBEDDED IMAGES\\fR for\ninformation on the options that are supported, and a description of the\nidentifier returned.\n.TP\n\\fIpathName \\fBimage names\\fR\n.\nReturns a list whose elements are the names of all image instances currently\nembedded in \\fIwindow\\fR.\n.RE\n.\\\" METHOD: index\n.TP\n\\fIpathName \\fBindex \\fIindex\\fR\n.\nReturns the position corresponding to \\fIindex\\fR in the form \\fIline.char\\fR\nwhere \\fIline\\fR is the line number and \\fIchar\\fR is the character number.\n\\fIIndex\\fR may have any of the forms described under \\fBINDICES\\fR above.\n.\\\" METHOD: insert\n.TP\n\\fIpathName \\fBinsert \\fIindex chars \\fR?\\fItagList chars tagList ...\\fR?\n.\nInserts all of the \\fIchars\\fR arguments just before the character at\n\\fIindex\\fR. If \\fIindex\\fR refers to the end of the text (the character after\nthe last newline) then the new text is inserted just before the last newline\ninstead. If there is a single \\fIchars\\fR argument and no \\fItagList\\fR, then\nthe new text will receive any tags that are present on both the character\nbefore and the character after the insertion point; if a tag is present on\nonly one of these characters then it will not be applied to the new text. If\n\\fItagList\\fR is specified then it consists of a list of tag names; the new\ncharacters will receive all of the tags in this list and no others, regardless\nof the tags present around the insertion point. If multiple\n\\fIchars\\fR\\-\\fItagList\\fR argument pairs are present, they produce the same\neffect as if a separate \\fIpathName \\fBinsert\\fR widget command had been\nissued for each pair, in order. The last \\fItagList\\fR argument may be\nomitted.\n.\\\" METHOD: mark\n.TP\n\\fIpathName \\fBmark \\fIoption \\fR?\\fIarg ...\\fR?\n.\nThis command is used to manipulate marks. The exact behavior of the command\ndepends on the \\fIoption\\fR argument that follows the \\fBmark\\fR argument. The\nfollowing forms of the command are currently supported:\n.RS\n.TP\n\\fIpathName \\fBmark gravity \\fImarkName\\fR ?\\fIdirection\\fR?\n.\nIf \\fIdirection\\fR is not specified, returns \\fBleft\\fR or \\fBright\\fR to\nindicate which of its adjacent characters \\fImarkName\\fR is attached to. If\n\\fIdirection\\fR is specified, it must be \\fBleft\\fR or \\fBright\\fR; the\ngravity of \\fImarkName\\fR is set to the given value.\n.TP\n\\fIpathName \\fBmark names\\fR\n.\nReturns a list whose elements are the names of all the marks that are\ncurrently set.\n.TP\n\\fIpathName \\fBmark next \\fIindex\\fR\n.\nReturns the name of the next mark at or after \\fIindex\\fR. If \\fIindex\\fR is\nspecified in numerical form, then the search for the next mark begins at that\nindex. If \\fIindex\\fR is the name of a mark, then the search for the next mark\nbegins immediately after that mark. This can still return a mark at the same\nposition if there are multiple marks at the same index. These semantics mean\nthat the \\fBmark next\\fR operation can be used to step through all the marks\nin a text widget in the same order as the mark information returned by the\n\\fIpathName \\fBdump\\fR operation. If a mark has been set to the special\n\\fBend\\fR index, then it appears to be \\fIafter \\fBend\\fR with respect to\nthe \\fIpathName \\fBmark next\\fR operation. An empty string is returned if\nthere are no marks after \\fIindex\\fR.\n.TP\n\\fIpathName \\fBmark previous \\fIindex\\fR\n.\nReturns the name of the mark at or before \\fIindex\\fR. If \\fIindex\\fR is\nspecified in numerical form, then the search for the previous mark begins with\nthe character just before that index. If \\fIindex\\fR is the name of a mark,\nthen the search for the next mark begins immediately before that mark. This\ncan still return a mark at the same position if there are multiple marks at\nthe same index. These semantics mean that the \\fIpathName \\fBmark previous\\fR\noperation can be used to step through all the marks in a text widget in the\nreverse order as the mark information returned by the \\fIpathName \\fBdump\\fR\noperation. An empty string is returned if there are no marks before\n\\fIindex\\fR.\n.TP\n\\fIpathName \\fBmark set \\fImarkName index\\fR\n.\nSets the mark named \\fImarkName\\fR to a position just before the character at\n\\fIindex\\fR. If \\fImarkName\\fR already exists, it is moved from its old\nposition; if it does not exist, a new mark is created. This command returns an\nempty string.\n.TP\n\\fIpathName \\fBmark unset \\fImarkName \\fR?\\fImarkName markName ...\\fR?\n.\nRemove the mark corresponding to each of the \\fImarkName\\fR arguments. The\nremoved marks will not be usable in indices and will not be returned by future\ncalls to\n.QW \"\\fIpathName \\fBmark names\\fR\" .\nThis command returns an empty string.\n.RE\n.\\\" METHOD: peer\n.TP\n\\fIpathName \\fBpeer \\fIoption args\\fR\n.\nThis command is used to create and query widget peers. It has two forms,\ndepending on \\fIoption\\fR:\n.RS\n.TP\n\\fIpathName \\fBpeer create \\fInewPathName\\fR ?\\fIoptions\\fR?\n.\nCreates a peer text widget with the given \\fInewPathName\\fR, and any optional\nstandard configuration options (as for the \\fItext\\fR command). By default the\npeer will have the same start and end line as the parent widget, but these can\nbe overridden with the standard configuration options.\n.TP\n\\fIpathName \\fBpeer names\\fR\n.\nReturns a list of peers of this widget (this does not include the widget\nitself). The order within this list is undefined.\n.RE\n.\\\" METHOD: pendingsync\n.TP\n\\fIpathName \\fBpendingsync\\fR\n.\nReturns 1 if the line heights calculations are not up-to-date, 0 otherwise.\n.\\\" METHOD: replace\n.TP\n\\fIpathName \\fBreplace\\fI index1 index2 chars\\fR ?\\fItagList chars tagList ...\\fR?\n.\nReplaces the range of characters between \\fIindex1\\fR and \\fIindex2\\fR\nwith the given characters and tags. See the section on \\fIpathName\n\\fBinsert\\fR for an explanation of the handling of the \\fItagList...\\fR\narguments, and the section on \\fIpathName\n\\fBdelete\\fR for an explanation of the handling of the indices. If\n\\fIindex2\\fR corresponds to an index earlier in the text than\n\\fIindex1\\fR, an error will be generated.\n.RS\n.PP\nThe deletion and insertion are arranged so that no unnecessary scrolling of\nthe window or movement of insertion cursor occurs. In addition the undo/redo\nstack are correctly modified, if undo operations are active in the text\nwidget. The command returns an empty string.\n.RE\n.\\\" METHOD: scan\n.TP\n\\fIpathName \\fBscan \\fIoption args\\fR\n.\nThis command is used to implement scanning on texts. It has two forms,\ndepending on \\fIoption\\fR:\n.RS\n.TP\n\\fIpathName \\fBscan mark \\fIx y\\fR\n.\nRecords \\fIx\\fR and \\fIy\\fR and the current view in the text window, for use\nin conjunction with later \\fIpathName \\fBscan dragto\\fR commands. Typically\nthis command is associated with a mouse button press in the widget. It returns\nan empty string.\n.TP\n\\fIpathName \\fBscan dragto \\fIx y\\fR\n.\nThis command computes the difference between its \\fIx\\fR and \\fIy\\fR arguments\nand the \\fIx\\fR and \\fIy\\fR arguments to the last \\fIpathName \\fBscan mark\\fR\ncommand for the widget. It then adjusts the view by 10 times the difference in\ncoordinates. This command is typically associated with mouse motion events in\nthe widget, to produce the effect of dragging the text at high speed through\nthe window. The return value is an empty string.\n.RE\n.\\\" METHOD: search\n.TP\n\\fIpathName \\fBsearch \\fR?\\fIswitches\\fR? \\fIpattern index \\fR?\\fIstopIndex\\fR?\n.\nSearches the text in \\fIpathName\\fR starting at \\fIindex\\fR for a range of\ncharacters that matches \\fIpattern\\fR. If a match is found, the index of the\nfirst character in the match is returned as result; otherwise an empty string\nis returned. One or more of the following switches (or abbreviations thereof)\nmay be specified to control the search:\n.RS\n.\\\" OPTION: -forwards\n.TP\n\\fB\\-forwards\\fR\n.\nThe search will proceed forward through the text, finding the first matching\nrange starting at or after the position given by \\fIindex\\fR. This is the\ndefault.\n.\\\" OPTION: -backwards\n.TP\n\\fB\\-backwards\\fR\n.\nThe search will proceed backward through the text, finding the matching range\nclosest to \\fIindex\\fR whose first character is before \\fIindex\\fR (it is not\nallowed to be at \\fIindex\\fR). Note that, for a variety of reasons, backwards\nsearches can be substantially slower than forwards searches (particularly when\nusing \\fB\\-regexp\\fR), so it is recommended that performance-critical code use\nforward searches.\n.\\\" OPTION: -exact\n.TP\n\\fB\\-exact\\fR\n.\nUse exact matching: the characters in the matching range must be identical to\nthose in \\fIpattern\\fR. This is the default.\n.\\\" OPTION: -regexp\n.TP\n\\fB\\-regexp\\fR\n.\nTreat \\fIpattern\\fR as a regular expression and match it against the text\nusing the rules for regular expressions (see the \\fBregexp\\fR command\nand the \\fBre_syntax\\fR page for\ndetails). The default matching automatically passes both the\n\\fB\\-lineanchor\\fR and \\fB\\-linestop\\fR options to the regexp engine (unless\n\\fB\\-nolinestop\\fR is used), so that \\fI^$\\fR match beginning and end of line,\nand \\fI.\\fR, \\fI[^\\fR sequences will never match the newline character\n\\fI\\en\\fR.\n.\\\" OPTION: -nolinestop\n.TP\n\\fB\\-nolinestop\\fR\n.\nThis allows \\fI.\\fR and \\fI[^\\fR sequences to match the newline character\n\\fI\\en\\fR, which they will otherwise not do (see the \\fBregexp\\fR command for\ndetails). This option is only meaningful if \\fB\\-regexp\\fR is also given, and\nan error will be thrown otherwise. For example, to match the entire text, use\n.QW \"\\fIpathName \\fBsearch \\-nolinestop \\-regexp\\fR \\N'34'.*\\N'34' 1.0\" .\n.\\\" OPTION: -nocase\n.TP\n\\fB\\-nocase\\fR\n.\nIgnore case differences between the pattern and the text.\n.\\\" OPTION: -count\n.TP\n\\fB\\-count\\fI varName\\fR\n.\nThe argument following \\fB\\-count\\fR gives the name of a variable; if a match\nis found, the number of index positions between beginning and end of the\nmatching range will be stored in the variable. If there are no embedded images\nor windows in the matching range (and there are no elided characters if\n\\fB\\-elide\\fR is not given), this is equivalent to the number of characters\nmatched. In either case, the range \\fImatchIdx\\fR to \\fImatchIdx + $count\nchars\\fR will return the entire matched text.\n.\\\" OPTION: -all\n.TP\n\\fB\\-all\\fR\n.\nFind all matches in the given range and return a list of the indices of the\nfirst character of each match. If a \\fB\\-count\\fI varName\\fR switch is given,\nthen \\fIvarName\\fR is also set to a list containing one element for each\nsuccessful match. Note that, even for exact searches, the elements of this\nlist may be different, if there are embedded images, windows or hidden text.\nSearches with \\fB\\-all\\fR behave very similarly to the Tcl command \\fBregexp\n\\-all\\fR, in that overlapping matches are not normally returned. For example,\napplying an \\fB\\-all\\fR search of the pattern\n.QW \\ew+\nagainst\n.QW \"hello there\"\nwill just match twice, once for each word, and matching\n.QW \"Z[a\\-z]+Z\"\nagainst\n.QW ZooZooZoo\nwill just match once.\n.\\\" OPTION: -overlap\n.TP\n\\fB\\-overlap\\fR\n.\nWhen performing \\fB\\-all\\fR searches, the normal behaviour is that matches\nwhich overlap an already-found match will not be returned. This switch changes\nthat behaviour so that all matches which are not totally enclosed within\nanother match are returned. For example, applying an \\fB\\-overlap\\fR search of\nthe pattern\n.QW \\ew+\nagainst\n.QW \"hello there\"\nwill just match twice (i.e. no different to just \\fB\\-all\\fR), but matching\n.QW Z[a\\-z]+Z\nagainst\n.QW ZooZooZoo\nwill now match twice. An error will be thrown if this switch is used without\n\\fB\\-all\\fR.\n.\\\" OPTION: -strictlimits\n.TP\n\\fB\\-strictlimits\\fR\n.\nWhen performing any search, the normal behaviour is that the start and stop\nlimits are checked with respect to the start of the matching text. With the\n\\fB\\-strictlimits\\fR flag, the entire matching range must lie inside the start\nand stop limits specified for the match to be valid.\n.\\\" OPTION: -elide\n.TP\n\\fB\\-elide\\fR\n.\nFind elided (hidden) text as well. By default only displayed text is searched.\n.\\\" OPTION: --\n.TP\n\\fB\\-\\|\\-\\fR\n.\nThis switch has no effect except to terminate the list of switches: the next\nargument will be treated as \\fIpattern\\fR even if it starts with \\fB\\-\\fR.\n.PP\nThe matching range may be within a single line of text, or run across multiple\nlines (if parts of the pattern can match a new-line). For regular expression\nmatching one can use the various newline-matching features such as \\fB$\\fR to\nmatch the end of a line, \\fB^\\fR to match the beginning of a line, and to\ncontrol whether \\fB.\\fR is allowed to match a new-line. If \\fIstopIndex\\fR is\nspecified, the search stops at that index: for forward searches, no match at\nor after \\fIstopIndex\\fR will be considered; for backward searches, no match\nearlier in the text than \\fIstopIndex\\fR will be considered. If\n\\fIstopIndex\\fR is omitted, the entire text will be searched: when the\nbeginning or end of the text is reached, the search continues at the other end\nuntil the starting location is reached again; if \\fIstopIndex\\fR is specified,\nno wrap-around will occur. This means that, for example, if the search is\n\\fB\\-forwards\\fR but \\fIstopIndex\\fR is earlier in the text than\n\\fIstartIndex\\fR, nothing will ever be found. See \\fBKNOWN BUGS\\fR below for a\nnumber of minor limitations of the \\fIpathName \\fBsearch\\fR command.\n.RE\n.\\\" METHOD: see\n.TP\n\\fIpathName \\fBsee \\fIindex\\fR\n.\nAdjusts the view in the window so that the character given by \\fIindex\\fR is\ncompletely visible. If \\fIindex\\fR is already visible then the command does\nnothing. If \\fIindex\\fR is a short distance out of view, the command adjusts\nthe view just enough to make \\fIindex\\fR visible at the edge of the window.\nIf \\fIindex\\fR is far out of view, then the command centers \\fIindex\\fR in the\nwindow.\n.\\\" METHOD: sync\n.TP\n\\fIpathName \\fBsync\\fR ?\\fB\\-command \\fIcommand\\fR?\n.\nControls the synchronization of the view of the text widget.\n.RS\n.TP\n\\fIpathName \\fBsync\\fR\n.\nImmediately brings the line metrics up-to-date by forcing computation of any\noutdated line heights. The command returns immediately if there is no such\noutdated line heights, otherwise it returns only at the end of the computation.\nThe command returns an empty string.\n.TP\n\\fIpathName \\fBsync \\-command \\fIcommand\\fR\n.\nSchedules \\fIcommand\\fR to be executed (by the event loop) exactly once as soon\nas all line heights are up-to-date. If there are no pending line metrics\ncalculations, the scheduling is immediate. The command returns the empty\nstring. \\fBbgerror\\fR is called on \\fIcommand\\fR failure.\n.RE\n.\\\" METHOD: tag\n.TP\n\\fIpathName \\fBtag \\fIoption \\fR?\\fIarg ...\\fR?\n.\nThis command is used to manipulate tags. The exact behavior of the command\ndepends on the \\fIoption\\fR argument that follows the \\fBtag\\fR argument. The\nfollowing forms of the command are currently supported:\n.RS\n.TP\n\\fIpathName \\fBtag add \\fItagName index1 \\fR?\\fIindex2 index1 index2 ...\\fR?\n.\nAssociate the tag \\fItagName\\fR with all of the characters starting with\n\\fIindex1\\fR and ending just before \\fIindex2\\fR (the character at\n\\fIindex2\\fR is not tagged). A single command may contain any number of\n\\fIindex1\\fR\\-\\fIindex2\\fR pairs. If the last \\fIindex2\\fR is omitted then the\nsingle character at \\fIindex1\\fR is tagged. If there are no characters in the\nspecified range (e.g. \\fIindex1\\fR is past the end of the file or \\fIindex2\\fR\nis less than or equal to \\fIindex1\\fR) then the command has no effect.\n.TP\n\\fIpathName \\fBtag bind \\fItagName\\fR ?\\fIsequence\\fR? ?\\fIscript\\fR?\n.\nThis command associates \\fIscript\\fR with the tag given by \\fItagName\\fR.\nWhenever the event sequence given by \\fIsequence\\fR occurs for a character\nthat has been tagged with \\fItagName\\fR, the script will be invoked. This\nwidget command is similar to the \\fBbind\\fR command except that it operates on\ncharacters in a text rather than entire widgets. See the \\fBbind\\fR manual\nentry for complete details on the syntax of \\fIsequence\\fR and the\nsubstitutions performed on \\fIscript\\fR before invoking it. If all arguments\nare specified then a new binding is created, replacing any existing binding\nfor the same \\fIsequence\\fR and \\fItagName\\fR (if the first character of\n\\fIscript\\fR is\n.QW +\nthen \\fIscript\\fR augments an existing binding rather than replacing it). In\nthis case the return value is an empty string. If \\fIscript\\fR is omitted then\nthe command returns the \\fIscript\\fR associated with \\fItagName\\fR and\n\\fIsequence\\fR (an error occurs if there is no such binding). If both\n\\fIscript\\fR and \\fIsequence\\fR are omitted then the command returns a list of\nall the sequences for which bindings have been defined for \\fItagName\\fR.\n.RS\n.PP\nThe only events for which bindings may be specified are those related to the\nmouse and keyboard (such as \\fBEnter\\fR, \\fBLeave\\fR, \\fBButton\\fR,\n\\fBMotion\\fR, and \\fBKey\\fR) or virtual events. Mouse and keyboard event\nbindings for a text widget respectively use the \\fBcurrent\\fR and \\fBinsert\\fR\nmarks described under \\fBMARKS\\fR above. An\n\\fBEnter\\fR event triggers for a tag when the tag first becomes present on the\ncurrent character, and a \\fBLeave\\fR event triggers for a tag when it ceases\nto be present on the current character. \\fBEnter\\fR and \\fBLeave\\fR events can\nhappen either because the \\fBcurrent\\fR mark moved or because the character at\nthat position changed. Note that these events are different than \\fBEnter\\fR\nand \\fBLeave\\fR events for windows. Mouse events are directed to the current\ncharacter, while keyboard events are directed to the insert character.\nIf a virtual event is used in a binding, that binding\ncan trigger only if the virtual event is defined by an underlying\nmouse-related or keyboard-related event.\n.PP\nIt is possible for the current character to have multiple tags, and for each\nof them to have a binding for a particular event sequence. When this occurs,\none binding is invoked for each tag, in order from lowest-priority to highest\npriority. If there are multiple matching bindings for a single tag, then the\nmost specific binding is chosen (see the manual entry for the \\fBbind\\fR\ncommand for details). \\fBcontinue\\fR and \\fBbreak\\fR commands within binding\nscripts are processed in the same way as for bindings created with the\n\\fBbind\\fR command.\n.PP\nIf bindings are created for the widget as a whole using the \\fBbind\\fR\ncommand, then those bindings will supplement the tag bindings. The tag\nbindings will be invoked first, followed by bindings for the window as a\nwhole.\n.RE\n.TP\n\\fIpathName \\fBtag cget \\fItagName option\\fR\n.\nThis command returns the current value of the option named \\fIoption\\fR\nassociated with the tag given by \\fItagName\\fR. \\fIOption\\fR may have any of\nthe values accepted by the \\fIpathName \\fBtag configure\\fR widget command.\n.TP\n\\fIpathName \\fBtag configure \\fItagName\\fR ?\\fIoption\\fR? ?\\fIvalue\\fR? ?\\fIoption value ...\\fR?\n.\nThis command is similar to the \\fIpathName \\fBconfigure\\fR widget command\nexcept that it modifies options associated with the tag given by \\fItagName\\fR\ninstead of modifying options for the overall text widget. If no \\fIoption\\fR\nis specified, the command returns a list describing all of the available\noptions for \\fItagName\\fR (see \\fBTk_ConfigureInfo\\fR for information on the\nformat of this list). If \\fIoption\\fR is specified with no \\fIvalue\\fR, then\nthe command returns a list describing the one named option (this list will be\nidentical to the corresponding sublist of the value returned if no\n\\fIoption\\fR is specified). If one or more \\fIoption\\-value\\fR pairs are\nspecified, then the command modifies the given option(s) to have the given\nvalue(s) in \\fItagName\\fR; in this case the command returns an empty string.\nSee \\fBTAGS\\fR above for details on the options available for tags.\n.TP\n\\fIpathName \\fBtag delete \\fItagName \\fR?\\fItagName ...\\fR?\n.\nDeletes all tag information for each of the \\fItagName\\fR arguments. The\ncommand removes the tags from all characters in the file and also deletes any\nother information associated with the tags, such as bindings and display\ninformation. The command returns an empty string.\n.TP\n\\fIpathName\\fB tag lower \\fItagName \\fR?\\fIbelowThis\\fR?\n.\nChanges the priority of tag \\fItagName\\fR so that it is just lower in priority\nthan the tag whose name is \\fIbelowThis\\fR. If \\fIbelowThis\\fR is omitted,\nthen \\fItagName\\fR's priority is changed to make it lowest priority of all\ntags.\n.TP\n\\fIpathName \\fBtag names \\fR?\\fIindex\\fR?\n.\nReturns a list whose elements are the names of all the tags that are active at\nthe character position given by \\fIindex\\fR. If \\fIindex\\fR is omitted, then\nthe return value will describe all of the tags that exist for the text (this\nincludes all tags that have been named in a\n.QW \"\\fIpathName \\fBtag\\fR\"\nwidget command but have not been deleted by a\n.QW \"\\fIpathName \\fBtag delete\\fR\"\nwidget command, even if no characters are currently marked with the tag). The\nlist will be sorted in order from lowest priority to highest priority.\n.TP\n\\fIpathName \\fBtag nextrange \\fItagName index1 \\fR?\\fIindex2\\fR?\n.\nThis command searches the text for a range of characters tagged with\n\\fItagName\\fR where the first character of the range is no earlier than the\ncharacter at \\fIindex1\\fR and no later than the character just before\n\\fIindex2\\fR (a range starting at \\fIindex2\\fR will not be considered). If\nseveral matching ranges exist, the first one is chosen. The command's return\nvalue is a list containing two elements, which are the index of the first\ncharacter of the range and the index of the character just after the last one\nin the range. If no matching range is found then the return value is an empty\nstring. If \\fIindex2\\fR is not given then it defaults to the end of the text.\n.TP\n\\fIpathName \\fBtag prevrange \\fItagName index1 \\fR?\\fIindex2\\fR?\n.\nThis command searches the text for a range of characters tagged with\n\\fItagName\\fR where the first character of the range is before the character\nat \\fIindex1\\fR and no earlier than the character at \\fIindex2\\fR (a range\nstarting at \\fIindex2\\fR will be considered). If several matching ranges\nexist, the one closest to \\fIindex1\\fR is chosen. The command's return value\nis a list containing two elements, which are the index of the first character\nof the range and the index of the character just after the last one in the\nrange. If no matching range is found then the return value is an empty string.\nIf \\fIindex2\\fR is not given then it defaults to the beginning of the text.\n.TP\n\\fIpathName \\fBtag raise \\fItagName \\fR?\\fIaboveThis\\fR?\n.\nChanges the priority of tag \\fItagName\\fR so that it is just higher in\npriority than the tag whose name is \\fIaboveThis\\fR. If \\fIaboveThis\\fR is\nomitted, then \\fItagName\\fR's priority is changed to make it highest priority\nof all tags.\n.TP\n\\fIpathName \\fBtag ranges \\fItagName\\fR\n.\nReturns a list describing all of the ranges of text that have been tagged with\n\\fItagName\\fR. The first two elements of the list describe the first tagged\nrange in the text, the next two elements describe the second range, and so on.\nThe first element of each pair contains the index of the first character of\nthe range, and the second element of the pair contains the index of the\ncharacter just after the last one in the range. If there are no characters\ntagged with \\fItag\\fR then an empty string is returned.\n.TP\n\\fIpathName \\fBtag remove \\fItagName index1 \\fR?\\fIindex2 index1 index2 ...\\fR?\n.\nRemove the tag \\fItagName\\fR from all of the characters starting at\n\\fIindex1\\fR and ending just before \\fIindex2\\fR (the character at\n\\fIindex2\\fR is not affected). A single command may contain any number of\n\\fIindex1\\fR\\-\\fIindex2\\fR pairs. If the last \\fIindex2\\fR is omitted then the\ntag is removed from the single character at \\fIindex1\\fR. If there are no\ncharacters in the specified range (e.g. \\fIindex1\\fR is past the end of the\nfile or \\fIindex2\\fR is less than or equal to \\fIindex1\\fR) then the command\nhas no effect. This command returns an empty string.\n.RE\n.\\\" METHOD: window\n.TP\n\\fIpathName \\fBwindow \\fIoption \\fR?\\fIarg ...\\fR?\n.\nThis command is used to manipulate embedded windows. The behavior of the\ncommand depends on the \\fIoption\\fR argument that follows the \\fBwindow\\fR\nargument. The following forms of the command are currently supported:\n.RS\n.TP\n\\fIpathName \\fBwindow cget \\fIindex option\\fR\n.\nReturns the value of a configuration option for an embedded window.\n\\fIIndex\\fR identifies the embedded window, and \\fIoption\\fR specifies a\nparticular configuration option, which must be one of the ones listed in the\nsection \\fBEMBEDDED WINDOWS\\fR.\n.TP\n\\fIpathName \\fBwindow configure \\fIindex\\fR ?\\fIoption value ...\\fR?\n.\nQuery or modify the configuration options for an embedded window. If no\n\\fIoption\\fR is specified, returns a list describing all of the available\noptions for the embedded window at \\fIindex\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified with no\n\\fIvalue\\fR, then the command returns a list describing the one named option\n(this list will be identical to the corresponding sublist of the value\nreturned if no \\fIoption\\fR is specified). If one or more \\fIoption\\-value\\fR\npairs are specified, then the command modifies the given option(s) to have the\ngiven value(s); in this case the command returns an empty string. See\n\\fBEMBEDDED WINDOWS\\fR for information on the options that are supported.\n.TP\n\\fIpathName \\fBwindow create \\fIindex\\fR ?\\fIoption value ...\\fR?\n.\nThis command creates a new window annotation, which will appear in the text at\nthe position given by \\fIindex\\fR. Any number of \\fIoption\\-value\\fR pairs may\nbe specified to configure the annotation. See \\fBEMBEDDED WINDOWS\\fR for\ninformation on the options that are supported. Returns an empty string.\n.TP\n\\fIpathName \\fBwindow names\\fR\n.\nReturns a list whose elements are the names of all windows currently embedded\nin \\fIwindow\\fR.\n.RE\n.\\\" METHOD: xview\n.TP\n\\fIpathName \\fBxview \\fIoption args\\fR\n.\nThis command is used to query and change the horizontal position of the text\nin the widget's window. It can take any of the following forms:\n.RS\n.TP\n\\fIpathName \\fBxview\\fR\n.\nReturns a list containing two elements. Each element is a real fraction\nbetween 0 and 1; together they describe the portion of the document's\nhorizontal span that is visible in the window. For example, if the first\nelement is .2 and the second element is .6, 20% of the text is off-screen to\nthe left, the middle 40% is visible in the window, and 40% of the text is\noff-screen to the right. The fractions refer only to the lines that are\nactually visible in the window: if the lines in the window are all very short,\nso that they are entirely visible, the returned fractions will be 0 and 1,\neven if there are other lines in the text that are much wider than the window.\nThese are the same values passed to scrollbars via the \\fB\\-xscrollcommand\\fR\noption.\n.TP\n\\fIpathName \\fBxview moveto\\fI fraction\\fR\n.\nAdjusts the view in the window so that \\fIfraction\\fR of the horizontal span\nof the text is off-screen to the left. \\fIFraction\\fR is a fraction between 0\nand 1.\n.TP\n\\fIpathName \\fBxview scroll \\fInumber what\\fR\n.\nThis command shifts the view in the window left or right according to\n\\fInumber\\fR and \\fIwhat\\fR. \\fIWhat\\fR must be \\fBpages\\fR,\n\\fBpixels\\fR, or \\fBunits\\fR. If \\fIwhat\\fR is \\fBpages\\fR or\n\\fBunits\\fR then \\fInumber\\fR must be an integer, otherwise number may be\nspecified in any of the forms acceptable to \\fBTk_GetPixels\\fR, such as\n.QW 2.0c\nor\n.QW 1i\n(the result is rounded to the nearest integer value. If no units are given,\npixels are assumed). If \\fIwhat\\fR is \\fBpages\\fR then the view adjusts by\n\\fInumber\\fR screenfuls; if it is \\fBpixels\\fR then the view adjusts by\n\\fInumber\\fR pixels; if it is \\fBunits\\fR, the view adjusts left or\nright by \\fInumber\\fR average-width characters on the display. If \\fInumber\\fR is\nnegative then characters farther to the left become visible; if it is positive\nthen characters farther to the right become visible.\n.RE\n.\\\" METHOD: yview\n.TP\n\\fIpathName \\fByview \\fR?\\fIargs\\fR?\n.\nThis command is used to query and change the vertical position of the text in\nthe widget's window. It can take any of the following forms:\n.RS\n.TP\n\\fIpathName \\fByview\\fR\n.\nReturns a list containing two elements, both of which are real fractions\nbetween 0 and 1. The first element gives the position of the first visible\npixel of the first character (or image, etc) in the top line in the window,\nrelative to the text as a whole (0.5 means it is halfway through the text, for\nexample). The second element gives the position of the first pixel just after\nthe last visible one in the bottom line of the window, relative to the text as\na whole. These are the same values passed to scrollbars via the\n\\fB\\-yscrollcommand\\fR option.\n.TP\n\\fIpathName \\fByview moveto\\fI fraction\\fR\n.\nAdjusts the view in the window so that the pixel given by \\fIfraction\\fR\nappears at the top of the top line of the window. \\fIFraction\\fR is a fraction\nbetween 0 and 1; 0 indicates the first pixel of the first character in the\ntext, 0.33 indicates the pixel that is one-third the way through the text; and\nso on. Values close to 1 will indicate values close to the last pixel in the\ntext (1 actually refers to one pixel beyond the last pixel), but in such cases\nthe widget will never scroll beyond the last pixel, and so a value of 1 will\neffectively be rounded back to whatever fraction ensures the last pixel is at\nthe bottom of the window, and some other pixel is at the top.\n.TP\n\\fIpathName \\fByview scroll \\fInumber what\\fR\n.\nThis command adjust the view in the window up or down according to\n\\fInumber\\fR and \\fIwhat\\fR. \\fIWhat\\fR must be \\fBpages\\fR,\n\\fBpixels\\fR, or \\fBunits\\fR. If \\fIwhat\\fR is \\fBunits\\fR or \\fBpages\\fR then\n\\fInumber\\fR must be an integer, otherwise number may be specified in any of\nthe forms acceptable to \\fBTk_GetPixels\\fR, such as\n.QW 2.0c\nor\n.QW 1i\n(the result is rounded to the nearest integer value. If no units are given,\npixels are assumed). If \\fIwhat\\fR is \\fBunits\\fR, the view adjusts up or down\nby \\fInumber\\fR lines on the display; if it is \\fBpages\\fR then the view\nadjusts by \\fInumber\\fR screenfuls; if it is \\fBpixels\\fR then the view\nadjusts by \\fInumber\\fR pixels. If \\fInumber\\fR is negative then earlier\npositions in the text become visible; if it is positive then later positions\nin the text become visible.\n.TP\n\\fIpathName \\fByview \\fR?\\fB\\-pickplace\\fR? \\fIindex\\fR\n.\nChanges the view in the widget's window to make \\fIindex\\fR visible. If the\n\\fB\\-pickplace\\fR option is not specified then \\fIindex\\fR will appear at the\ntop of the window. If \\fB\\-pickplace\\fR is specified then the widget chooses\nwhere \\fIindex\\fR appears in the window:\n.RS\n.IP [1]\nIf \\fIindex\\fR is already visible somewhere in the window then the command\ndoes nothing.\n.IP [2]\nIf \\fIindex\\fR is only a few lines off-screen above the window then it will be\npositioned at the top of the window.\n.IP [3]\nIf \\fIindex\\fR is only a few lines off-screen below the window then it will be\npositioned at the bottom of the window.\n.IP [4]\nOtherwise, \\fIindex\\fR will be centered in the window.\n.PP\nThe \\fB\\-pickplace\\fR option has been obsoleted by the \\fIpathName \\fBsee\\fR\nwidget command (\\fIpathName \\fBsee\\fR handles both x- and y-motion to make a\nlocation visible, whereas the \\fB\\-pickplace\\fR mode only handles motion in\ny).\n.RE\n.TP\n\\fIpathName \\fByview \\fInumber\\fR\n.\nThis command makes the first character on the line after the one given by\n\\fInumber\\fR visible at the top of the window. \\fINumber\\fR must be an\ninteger. This command used to be used for scrolling, but now it is obsolete.\n.RE\n.SH BINDINGS\n.PP\nTk automatically creates class bindings for texts that give them the following\ndefault behavior.\nIn the descriptions below,\n.QW word\nis dependent on the value of\nthe \\fBtcl_wordchars\\fR variable. See \\fBtclvars\\fR(n).\n.IP [1]\nClicking mouse button 1 positions the insertion cursor at the closest edge of the\ncharacter underneath the mouse cursor, sets the input focus to this widget,\nand clears any selection in the widget. Dragging with mouse button 1 strokes\nout a selection between the insertion cursor and the character under the\nmouse.\n.IP [2]\nDouble-clicking with mouse button 1 selects the word under the mouse and\npositions the insertion cursor at the start of the word. Dragging after a\ndouble click will stroke out a selection consisting of whole words.\n.IP [3]\nTriple-clicking with mouse button 1 selects the line under the mouse and\npositions the insertion cursor at the start of the line. Dragging after a\ntriple click will stroke out a selection consisting of whole lines.\n.IP [4]\nThe ends of the selection can be adjusted by dragging with mouse button 1\nwhile the Shift key is down; this will adjust the end of the selection that\nwas nearest to the mouse cursor when button 1 was pressed. If the button is\ndouble-clicked before dragging then the selection will be adjusted in units of\nwhole words; if it is triple-clicked then the selection will be adjusted in\nunits of whole lines.\n.IP [5]\nClicking mouse button 1 with the Control key down will reposition the\ninsertion cursor without affecting the selection.\n.IP [6]\nIf any normal printing characters are typed, they are inserted at the point of\nthe insertion cursor.\n.IP [7]\nThe view in the widget can be adjusted by dragging with the middle mouse\nbutton (button 2, or button 3 in TkAqua). If the middle mouse button is\nclicked without moving the mouse, the selection is copied into the text at the\nposition of the mouse cursor. The Insert key also inserts the selection,\nbut at the position of the insertion cursor.\n.IP [8]\nIf the mouse is dragged out of the widget while button 1 is pressed, the entry\nwill automatically scroll to make more text visible (if there is more text\noff-screen on the side where the mouse left the window).\n.IP [9]\nThe Left and Right keys move the insertion cursor one character to the left or\nright; they also clear any selection in the text. If Left or Right is typed\nwith the Shift key down, then the insertion cursor moves and the selection is\nextended to include the new character. Control-Left and Control-Right move the\ninsertion cursor by words, and Control-Shift-Left and Control-Shift-Right move\nthe insertion cursor by words and also extend the selection. Control-b and\nControl-f behave the same as Left and Right, respectively. Meta-b and Meta-f\nbehave the same as Control-Left and Control-Right, respectively.\n.IP [10]\nThe Up and Down keys move the insertion cursor one line up or down and clear\nany selection in the text. If Up or Right is typed with the Shift key down,\nthen the insertion cursor moves and the selection is extended to include the\nnew character. Control-Up and Control-Down move the insertion cursor by\nparagraphs (groups of lines separated by blank lines), and Control-Shift-Up\nand Control-Shift-Down move the insertion cursor by paragraphs and also extend\nthe selection. Control-p and Control-n behave the same as Up and Down,\nrespectively.\n.IP [11]\nThe Next and Prior keys move the insertion cursor forward or backwards by one\nscreenful and clear any selection in the text. If the Shift key is held down\nwhile Next or Prior is typed, then the selection is extended to include the\nnew character.\n.IP [12]\nControl-Next and Control-Prior scroll the view right or left by one page\nwithout moving the insertion cursor or affecting the selection.\n.IP [13]\nHome and Control-a move the insertion cursor to the beginning of its display\nline and clear any selection in the widget. Shift-Home moves the insertion\ncursor to the beginning of the display line and also extends the selection to\nthat point.\n.IP [14]\nEnd and Control-e move the insertion cursor to the end of the display line and\nclear any selection in the widget. Shift-End moves the cursor to the end of\nthe display line and extends the selection to that point.\n.IP [15]\nControl-Home and Meta-< move the insertion cursor to the beginning of the text\nand clear any selection in the widget. Control-Shift-Home moves the insertion\ncursor to the beginning of the text and also extends the selection to that\npoint.\n.IP [16]\nControl-End and Meta-> move the insertion cursor to the end of the text and\nclear any selection in the widget. Control-Shift-End moves the cursor to the\nend of the text and extends the selection to that point.\n.IP [17]\nThe Select key and Control-Space set the selection anchor to the position of\nthe insertion cursor. They do not affect the current selection. Shift-Select\nand Control-Shift-Space adjust the selection to the current position of the\ninsertion cursor, selecting from the anchor to the insertion cursor if there\nwas not any selection previously.\n.IP [18]\nControl-/ selects the entire contents of the widget.\n.IP [19]\nControl-\\e clears any selection in the widget.\n.IP [20]\nThe F16 key (labelled Copy on many Sun workstations) or Meta-w copies the\nselection in the widget to the clipboard, if there is a selection. This\naction is carried out by the command \\fBtk_textCopy\\fR.\n.IP [21]\nThe F20 key (labelled Cut on many Sun workstations) or Control-w copies the\nselection in the widget to the clipboard and deletes the selection. This\naction is carried out by the command \\fBtk_textCut\\fR. If there is no\nselection in the widget then these keys have no effect.\n.IP [22]\nThe F18 key (labelled Paste on many Sun workstations) or Control-y inserts the\ncontents of the clipboard at the position of the insertion cursor. This action\nis carried out by the command \\fBtk_textPaste\\fR.\n.IP [23]\nThe Delete key deletes the selection, if there is one in the widget. If there\nis no selection, it deletes the character to the right of the insertion\ncursor.\n.IP [24]\nBackspace and Control-h delete the selection, if there is one in the widget.\nIf there is no selection, they delete the character to the left of the\ninsertion cursor.\n.IP [25]\nControl-d deletes the character to the right of the insertion cursor.\n.IP [26]\nMeta-d deletes the word to the right of the insertion cursor.\n.IP [27]\nControl-k deletes from the insertion cursor to the end of its line; if the\ninsertion cursor is already at the end of a line, then Control-k deletes the\nnewline character.\n.IP [28]\nControl-o opens a new line by inserting a newline character in front of the\ninsertion cursor without moving the insertion cursor.\n.IP [29]\nMeta-backspace and Meta-Delete delete the word to the left of the insertion\ncursor.\n.IP [30]\nControl-t reverses the order of the two characters to the right of the\ninsertion cursor.\n.IP [31]\nControl-x deletes whatever is selected in the text widget after copying it to\nthe clipboard.\n.IP [32]\nControl-z undoes the last edit action if the \\fB\\-undo\\fR option is true.\nDoes nothing otherwise.\n.IP [33]\nControl-Z (or Control-y on Windows) reapplies the last undone edit action if\nthe \\fB\\-undo\\fR option is true. Does nothing otherwise.\n.PP\nIf the widget is disabled using the \\fB\\-state\\fR option, then its view can\nstill be adjusted and text can still be selected, but no insertion cursor will\nbe displayed and no text modifications will take place.\n.PP\nThe behavior of texts can be changed by defining new bindings for individual\nwidgets or by redefining the class bindings.\n.SH \"KNOWN ISSUES\"\n.SS \"ISSUES CONCERNING CHARS AND INDICES\"\n.PP\nBefore Tk 8.5, the widget used the string\n.QW chars\nto refer to index positions (which included characters, embedded windows and\nembedded images). As of Tk 8.5 the text widget deals separately and correctly\nwith\n.QW chars\nand\n.QW indices .\nFor backwards compatibility, however, the index modifiers\n.QW \"+N chars\"\nand\n.QW \"\\-N chars\"\ncontinue to refer to indices. One must use any of the full forms\n.QW \"+N any chars\"\nor\n.QW \"\\-N any chars\"\netc. to refer to actual character indices. This confusion may be fixed in a\nfuture release by making the widget correctly interpret\n.QW \"+N chars\"\nas a synonym for\n.QW \"+N any chars\" .\n.SS \"PERFORMANCE ISSUES\"\n.PP\nText widgets should run efficiently under a variety of conditions. The text\nwidget uses about 2-3 bytes of main memory for each byte of text, so texts\ncontaining a megabyte or more should be practical on most workstations. Text\nis represented internally with a modified B-tree structure that makes\noperations relatively efficient even with large texts. Tags are included in\nthe B-tree structure in a way that allows tags to span large ranges or have\nmany disjoint smaller ranges without loss of efficiency. Marks are also\nimplemented in a way that allows large numbers of marks. In most cases it is\nfine to have large numbers of unique tags, or a tag that has many distinct\nranges.\n.PP\nOne performance problem can arise if you have hundreds or thousands of\ndifferent tags that all have the following characteristics: the first and last\nranges of each tag are near the beginning and end of the text, respectively,\nor a single tag range covers most of the text widget. The cost of adding and\ndeleting tags like this is proportional to the number of other tags with the\nsame properties. In contrast, there is no problem with having thousands of\ndistinct tags if their overall ranges are localized and spread uniformly\nthroughout the text.\n.PP\nVery long text lines can be expensive, especially if they have many marks and\ntags within them.\n.PP\nThe display line with the insert cursor is redrawn each time the cursor\nblinks, which causes a steady stream of graphics traffic. Set the\n\\fB\\-insertofftime\\fR attribute to 0 avoid this.\n.SS \"KNOWN BUGS\"\n.PP\nThe \\fIpathName \\fBsearch \\-regexp\\fR sub-command attempts to perform\nsophisticated regexp matching across multiple lines in an efficient fashion\n(since Tk 8.5), examining each line individually, and then in small groups of\nlines, whether searching forwards or backwards. Under certain conditions the\nsearch result might differ from that obtained by applying the same regexp to\nthe entire text from the widget in one go. For example, when searching with a\ngreedy regexp, the widget will continue to attempt to add extra lines to the\nmatch as long as one of two conditions are true: either Tcl's regexp library\nreturns a code to indicate a longer match is possible (but there are known\nbugs in Tcl which mean this code is not always correctly returned); or if each\nextra line added results in at least a partial match with the pattern. This\nmeans in the case where the first extra line added results in no match and\nTcl's regexp system returns the incorrect code and adding a second extra line\nwould actually match, the text widget will return the wrong result. In\npractice this is a rare problem, but it can occur, for example:\n.CS\npack [\\fBtext\\fR .t]\n\\&.t insert 1.0 \"aaaa\\enbbbb\\encccc\\enbbbb\\enaaaa\\en\"\n\\&.t search -regexp -- {(a+|b+\\enc+\\enb+)+\\ena+} 1.0\n.CE\nwill not find a match when one exists of 19 characters starting from the first\n.QW b .\n.PP\nWhenever one possible match is fully enclosed in another, the search command\nwill attempt to ensure only the larger match is returned. When performing\nbackwards regexp searches it is possible that Tcl will not always achieve\nthis, in the case where a match is preceded by one or more short,\nnon-overlapping matches, all of which are preceded by a large match which\nactually encompasses all of them. The search algorithm used by the widget does\nnot look back arbitrarily far for a possible match which might cover large\nportions of the widget. For example:\n.CS\npack [\\fBtext\\fR .t]\n\\&.t insert 1.0 \"aaaa\\enbbbb\\enbbbb\\enbbbb\\enbbbb\\\\n\"\n\\&.t search -regexp -backward -- {b+\\en|a+\\en(b+\\en)+} end\n.CE\nmatches at\n.QW 5.0\nwhen a true greedy match would match at\n.QW 1.0 .\nSimilarly if we add \\fB\\-all\\fR to this case, it matches at all of\n.QW 5.0 ,\n.QW 4.0 ,\n.QW 3.0\nand\n.QW 1.0 ,\nwhen really it should only match at\n.QW 1.0\nsince that match encloses all the others.\n.SH \"SEE ALSO\"\nentry(n), scrollbar(n)\n.SH KEYWORDS\ntext, widget, tkvars\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/tk.n", "content": "'\\\"\n'\\\" Copyright (c) 1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk n 8.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk \\- Manipulate Tk internal state\n.SH SYNOPSIS\n\\fBtk\\fI option \\fR?\\fIarg ...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBtk\\fR command provides access to miscellaneous\nelements of Tk's internal state.\nMost of the information manipulated by this command pertains to the\napplication as a whole, or to a screen or display, rather than to a\nparticular window.\nThe command can take any of a number of different forms\ndepending on the \\fIoption\\fR argument. The legal forms are:\n.\\\" METHOD: accessible\n.TP\n\\fBtk accessible \\fIsubcommand\\fR ...\n.\nThis command makes Tk widgets accessible to screen readers.\nFor\nmore details see the \\fBaccessible\\fR manual page.\n.\\\" METHOD: appname\n.TP\n\\fBtk appname \\fR?\\fInewName\\fR?\n.\nIf \\fInewName\\fR is not specified, this command returns the name\nof the application (the name that may be used in \\fBsend\\fR\ncommands to communicate with the application).\nIf \\fInewName\\fR is specified, then the name of the application\nis changed to \\fInewName\\fR.\nIf the given name is already in use, then a suffix of the form\n.QW \"\\fB #2\\fR\"\nor\n.QW \"\\fB #3\\fR\"\nis appended in order to make the name unique.\nThe command's result is the name actually chosen.\n\\fInewName\\fR should not start with a capital letter.\nThis will interfere with option processing, since names starting with\ncapitals are assumed to be classes; as a result, Tk may not\nbe able to find some options for the application.\nIf sends have been disabled by deleting the \\fBsend\\fR command,\nthis command will reenable them and recreate the \\fBsend\\fR\ncommand.\n.\\\" METHOD: attribtable\n.TP\n\\fBtk attribtable \\fItableName\\fR\n.\nThis command creates an attribute table of the name \\fItableName\\fR as a\ncommand in the namespace of the calling context if not fully qualified. An\nattribute table is used to query and modify arbitrary data attached to any\nwidget. For more details see the \\fBattribtable\\fR manual page.\n.\\\" METHOD: busy\n.TP\n\\fBtk busy \\fIsubcommand\\fR ...\n.\nThis command controls the marking of window hierarchies as\n.QW busy ,\nrendering them non-interactive while some other operation is proceeding. For\nmore details see the \\fBbusy\\fR manual page.\n.\\\" METHOD: caret\n.TP\n\\fBtk caret \\fIwindow \\fR?\\fB\\-x \\fIx\\fR? ?\\fB\\-y \\fIy\\fR? ?\\fB\\-height \\fIheight\\fR?\n.\nSets and queries the caret location for the display of the specified\nTk window \\fIwindow\\fR. The caret is the per-display cursor location\nused for indicating global focus (e.g. to comply with Microsoft\nAccessibility guidelines), as well as for location of the over-the-spot\nXIM (X Input Methods) or Windows IME windows. If no options are specified,\nthe last values used for setting the caret are return in option-value pair\nformat. \\fB\\-x\\fR and \\fB\\-y\\fR represent window-relative coordinates, and\n\\fB\\-height\\fR is the height of the current cursor location, or the height\nof the specified \\fIwindow\\fR if none is given.\n.\\\" METHOD: inactive\n.TP\n\\fBtk inactive \\fR?\\fB\\-displayof \\fIwindow\\fR? ?\\fBreset\\fR?\n.\nReturns a positive integer, the number of milliseconds since the last\ntime the user interacted with the system. If the \\fB\\-displayof\\fR\noption is given then the return value refers to the display of\n\\fIwindow\\fR; otherwise it refers to the display of the application's\nmain window.\n.RS\n.PP\n\\fBtk inactive\\fR will return \\-1, if querying the user inactive time\nis not supported by the system, and in safe interpreters.\n.PP\nIf the literal string \\fBreset\\fR is given as an additional argument,\nthe timer is reset and an empty string is returned. Resetting the\ninactivity time is forbidden in safe interpreters and will throw an\nerror if tried.\n.RE\n.\\\" METHOD: fileicon\n.TP\n\\fBtk fileicon \\fIfile size\\fR\n.\nDisplays a system-native file icon. For more details see the\n\\fBfileicon\\fR manual page.\n.\\\" METHOD: fontchooser\n.TP\n\\fBtk fontchooser \\fIsubcommand\\fR ...\n.\nControls the Tk font selection dialog. For more details see the\n\\fBfontchooser\\fR manual page.\n.\\\" METHOD: print\n.TP\n\\fBtk print \\fIwindow\\fR\n.\nThe \\fBtk print\\fR command posts a dialog that allows users to print output\nfrom the \\fBcanvas\\fR and \\fBtext\\fR widgets. The printing will be done using\nplatform-native APIs and dialogs where available. For more details see the\n\\fBprint\\fR manual page.\n.\\\" METHOD: scaling\n.TP\n\\fBtk scaling \\fR?\\fB\\-displayof \\fIwindow\\fR? ?\\fInumber\\fR?\n.\nSets and queries the current scaling factor used by Tk to convert between\nphysical units (for example, points, inches, or millimeters) and pixels. The\n\\fInumber\\fR argument is a floating point number that specifies the number of\npixels per point on \\fIwindow\\fR's display. If the \\fIwindow\\fR argument is\nomitted, it defaults to the main window. If the \\fInumber\\fR argument is\nomitted, the current value of the scaling factor is returned.\n.RS\n.PP\nA\n.QW point\nis a unit of measurement equal to 1/72 inch. A scaling factor\nof 1.0 corresponds to 1 pixel per point, which is equivalent to a standard\n72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point,\nwhich is the setting for a 90 dpi monitor; setting the scaling factor to\n1.25 on a 72 dpi monitor would cause everything in the application to be\ndisplayed 1.25 times as large as normal. The initial value for the scaling\nfactor is set when the application starts, based on properties of the\ninstalled monitor, but it can be changed at any time. Measurements made\nafter the scaling factor is changed will use the new scaling factor, but it\nis undefined whether existing widgets will resize themselves dynamically to\naccommodate the new scaling factor.\n.RE\n.\\\" METHOD: sysnotify\n.TP\n\\fBtk sysnotify \\fItitle message\\fR\n.\nThe \\fBtk sysnotify\\fP command creates a platform-specific system\nnotification alert. Its intent is to provide a brief, unobtrusive\nnotification to the user by popping up a window that briefly appears in a\ncorner of the screen. For more details see the \\fBsysnotify\\fR manual page.\n.\\\" METHOD: systray\n.TP\n\\fBtk systray \\fIsubcommand\\fR ...\n.\nThe \\fBtk systray\\fP command creates an icon in the platform-specific\ntray. For more details see the \\fBsystray\\fR manual page.\n.\\\" METHOD: useinputmethods\n.TP\n\\fBtk useinputmethods \\fR?\\fB\\-displayof \\fIwindow\\fR? ?\\fIboolean\\fR?\n.\nSets and queries the state of whether Tk should use XIM (X Input Methods)\nfor filtering events. The resulting state is returned. XIM is used in\nsome locales (i.e., Japanese, Korean), to handle special input devices. This\nfeature is only significant on X. If XIM support is not available, this\nwill always return 0. If the \\fIwindow\\fR argument is omitted, it defaults\nto the main window. If the \\fIboolean\\fR argument is omitted, the current\nstate is returned. This is turned on by default for the main display.\n.\\\" METHOD: windowingsystem\n.TP\n\\fBtk windowingsystem\\fR\n.\nReturns the current Tk windowing system, one of\n\\fBx11\\fR (X11-based), \\fBwin32\\fR (MS Windows),\nor \\fBaqua\\fR (macOS Aqua).\n.SH \"SEE ALSO\"\nattribtable(n), busy(n), fontchooser(n), print(n), send(n), sysnotify(n),\nsystray(n), winfo(n)\n.SH KEYWORDS\napplication name, attribute, print, send, sysnotify, systray\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/tk_mac.n", "content": "'\\\"\n'\\\" Copyright (c) 2011 Kevin Walzer\n'\\\" Copyright (c) 2011 Donal K. Fellows\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tk::mac n 8.6 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntk::mac \\- Access Mac-Specific Functionality on macOS from Tk\n.SH SYNOPSIS\n.nf\n\\fB::tk::mac::DoScriptFile\\fR\n\\fB::tk::mac::DoScriptText\\fR\n\\fB::tk::mac::ShowPreferences\\fR\n\\fB::tk::mac::OpenApplication\\fR\n\\fB::tk::mac::ReopenApplication\\fR\n\\fB::tk::mac::OpenDocument \\fIfile...\\fR\n\\fB::tk::mac::PrintDocument \\fIfile...\\fR\n\\fB::tk::mac::Quit\\fR\n\\fB::tk::mac::OnHide\\fR\n\\fB::tk::mac::OnShow\\fR\n\\fB::tk::mac::ShowHelp\\fR\n\\fB::tk::mac::PerformService\\fR\n\\fB::tk::mac::LaunchURL \\fIURL...\\fR\n\\fB::tk::mac::GetAppPath\\fR\n\\fB::tk::mac::GetInfoAsJSON\\fR\n\n\\fB::tk::mac::standardAboutPanel\\fR\n\n\\fB::tk::mac::useCompatibilityMetrics \\fIboolean\\fR\n\\fB::tk::mac::CGAntialiasLimit \\fIlimit\\fR\n\\fB::tk::mac::antialiasedtext \\fInumber\\fR\n\\fB::tk::mac::useThemedToplevel \\fIboolean\\fR\n\n\\fB::tk::mac::iconBitmap \\fIname width height \\-kind value\\fR\n\n.fi\n.BE\n.SH \"EVENT HANDLER CALLBACKS\"\n.PP\nThe Aqua/macOS application environment defines a number of additional\nevents that applications should respond to. These events are mapped by Tk to\ncalls to commands in the \\fB::tk::mac\\fR namespace; unless otherwise noted, if\nthe command is absent, no action will be taken.\n.\\\" COMMAND: DoScriptFile\n.TP\n\\fB::tk::mac::DoScriptFile\\fR\n.\nThe default Apple Event handler for AEDoScriptHandler. This command\nexecutes a Tcl file when an AppleScript sends a\n.QW \"do script\"\ncommand to Wish with a file path as a parameter.\n.\\\" COMMAND: DoScriptText\n.TP\n\\fB::tk::mac::DoScriptText\\fR\n.\nThe default Apple Event handler for AEDoScriptHandler. This command\nexecutes Tcl code when an AppleScript sends a\n.QW \"do script\"\ncommand to Wish with Tcl code or a Tcl procedure as a parameter.\n.\\\" COMMAND: ShowPreferences\n.TP\n\\fB::tk::mac::ShowPreferences\\fR\n.\nThe default Apple Event handler for kAEShowPreferences,\n.QW pref .\nThe application menu\n.QW \"Preferences\"\nmenu item is only enabled when this proc is defined. Typically this command is\nused to wrap a specific own preferences command, which pops up a preferences\nwindow. Something like:\n.RS\n.PP\n.CS\nproc ::tk::mac::ShowPreferences {} {\n setPref\n}\n.CE\n.RE\n.\\\" COMMAND: OpenApplication\n.TP\n\\fB::tk::mac::OpenApplication\\fR\n.\nIf a proc of this name is defined, this proc fill fire when your application\nis initially opened. It is the default Apple Event handler for\nkAEOpenApplication,\n.QW oapp .\n.\\\" COMMAND: ReopenApplication\n.TP\n\\fB::tk::mac::ReopenApplication\\fR\n.\nIf a proc of this name is defined it is the default Apple Event handler for\nkAEReopenApplication,\n.QW rapp ,\nthe Apple Event sent when your application is opened when it is already\nrunning (e.g. by clicking its icon in the Dock). Here is a sample that raises\na minimized window when the Dock icon is clicked:\n.RS\n.PP\n.CS\nproc ::tk::mac::ReopenApplication {} {\n if {[wm state .] eq \"withdrawn\"} {\n wm state . normal\n } else {\n wm deiconify .\n }\n raise .\n}\n.CE\n.RE\n.\\\" COMMAND: OpenDocument\n.TP\n\\fB::tk::mac::OpenDocument \\fIfile...\\fR\n.\nIf a proc of this name is defined it is the default Apple Event handler for\nkAEOpenDocuments,\n.QW odoc ,\nthe Apple Event sent when your application is asked to open one or more\ndocuments (e.g., by drag & drop onto the app or by opening a document of a\ntype associated to the app). The proc should take as arguments paths to the\nfiles to be opened, like so:\n.RS\n.PP\n.CS\nproc ::tk::mac::OpenDocument {args} {\n foreach f $args {my_open_document $f}\n}\n.CE\n.RE\n.\\\" COMMAND: PrintDocument\n.TP\n\\fB::tk::mac::PrintDocument \\fIfile...\\fR\n.\nIf a proc of this name is defined it is the default Apple Event handler for\nkAEPrintDocuments,\n.QW pdoc ,\nthe Apple Event sent when your application is asked to print a\ndocument. It takes a single absolute file path as an argument.\n.\\\" COMMAND: Quit\n.TP\n\\fB::tk::mac::Quit\\fR\n.\nIf a proc of this name is defined it is the default Apple Event handler for\nkAEQuitApplication,\n.QW quit ,\nthe Apple Event sent when your application is asked to be quit, e.g. via the\nquit menu item in the application menu, the quit menu item in the Dock menu,\nor during a logout/restart/shutdown etc. If this is not defined, \\fBexit\\fR is\ncalled instead.\n.\\\" COMMAND: OnHide\n.TP\n\\fB::tk::mac::OnHide\\fR\n.\nIf defined, this is called when your application receives a kEventAppHidden\nevent, e.g. via the hide menu item in the application or Dock menus.\n.\\\" COMMAND: OnShow\n.TP\n\\fB::tk::mac::OnShow\\fR\n.\nIf defined, this is called when your application receives a kEventAppShown\nevent, e.g. via the show all menu item in the application menu, or by clicking\nthe Dock icon of a hidden application.\n.\\\" COMMAND: ShowHelp\n.TP\n\\fB::tk::mac::ShowHelp\\fR\n.\nCustomizes behavior of Apple Help menu; if this procedure is not defined, the\nplatform-specific standard Help menu item\n.QW \"YourApp Help\"\nperforms the default Cocoa action of showing the Help Book configured in the\napplication's Info.plist (or displaying an alert if no Help Book is\nset).\n.\\\" COMMAND: PerformService\n.TP\n\\fB::tk::mac::PerformService\\fR\n.\nExecutes a Tcl procedure called from the macOS\n.QW Services\nmenu in the Application menu item. The\n.QW Services\nmenu item allows for inter-application communication; data from one\napplication, such as selected text, can be sent to another application\nfor processing, for example to Safari as a search item for Google, or\nto TextEdit to be appended to a file. An example of the proc is below,\nand should be rewritten in an application script for customization:\n.RS\n.PP\n.CS\nproc ::tk::mac::PerformService {} {\n set data [clipboard get]\n $w insert end $data\n}\n.CE\n.RE\nNote that the mechanism for retrieving the data is from the clipboard;\nthere is no other supported way to obtain the data. If the Services\nprocess is not desired, the NSServices keys can be deleted from\nthe application's Info.plist file. The underlying code supporting this\ncommand also allows the text, entry and ttk::entry widgets to access\nservices from other applications via the Services menu. The NSPortName\nkey in Wish's Info.plist file is currently set as\n.QW \"Wish\"\n; if a developer changes the name of the Wish executable to something\n else, this key should be modified with the same name.\n.\\\" COMMAND: LaunchURL\n.TP\n\\fB::tk::mac::LaunchURL \\fIURL...\\fR\n.\nIf defined, launches a URL within Tk. This would be used if a Tk\napplication wants to handle a URL itself, such as displaying data from\nan RSS feed, rather than launching a default application to handle the\nURL, although it can defined as such. Wish includes a stub URL scheme\nof\n.QW foo://\nin the CFBundleURLSchemes key of its Info.plist file; this should be\ncustomized for the specific URL scheme the developer wants to support.\n.TP\n\\fB::tk::mac::GetAppPath\\fR\n.\nReturns the current applications's file path.\n.TP\n\\fB::tk::mac::GetInfoAsJSON\\fR\n.\nReturns a JSON-encoded Tcl string which serializes the application's\n\\fBmainBundle.infoDictionary\\fR (defined by its \\fIInfo.plist\\fR file).\n.PP\n.SH \"ADDITIONAL DIALOGS\"\n.PP\nAqua/macOS defines additional dialogs that applications should\nsupport.\n.\\\" COMMAND: standardAboutPanel\n.TP\n\\fB::tk::mac::standardAboutPanel\\fR\n.\nBrings the standard Cocoa about panel to the front with information filled in\nfrom the application bundle files. The panel displays the application icon and\nthe values associated to the info.plist keys named CFBundleName,\nCFBundleShortVersionString, NSAboutPanelOptionVersion and\nNSHumanReadableCopyright. If a file named \\fICredits.html\\fR or\n\\fICredits.rtf\\fR exists in the bundle's Resources directory then its contents\nwill be displayed in a scrolling text box at the bottom of the dialog. See the\ndocumentation for -[NSApplication orderFrontStandardAboutPanelWithOptions:]\nfor more details. A hook is also provided for a custom About dialog. If a Tcl\nproc named tkAboutDialog is defined in the main interpreter then that\nprocedure will be called instead of opening the standardAboutPanel.\n.SH \"SYSTEM CONFIGURATION\"\n.PP\nThere are a number of additional global configuration options that control the\ndetails of how Tk renders by default.\n.\\\" COMMAND: useCompatibilityMetrics\n.TP\n\\fB::tk::mac::useCompatibilityMetrics \\fIboolean\\fR\n.\nPreserves compatibility with older Tk/Aqua metrics; set to \\fBfalse\\fR for\nmore native spacing.\n.\\\" COMMAND: CGAntialiasLimit\n.TP\n\\fB::tk::mac::CGAntialiasLimit \\fIlimit\\fR\n.\nSets the antialiasing limit; lines thinner that \\fIlimit\\fR pixels will not be\nantialiased. Integer, set to 0 by default, making all lines be antialiased.\n.\\\" COMMAND: antialiasedtext\n.TP\n\\fB::tk::mac::antialiasedtext \\fInumber\\fR\n.\nSets anti-aliased text. Controls text antialiasing, possible values for\n\\fInumber\\fR are -1 (default, use system default for text AA), 0 (no text AA),\n1 (use text AA).\n.\\\" COMMAND: useThemedToplevel\n.TP\n\\fB::tk::mac::useThemedToplevel \\fIboolean\\fR\n.\nSets toplevel windows to draw with the modern grayish/ pinstripe Mac\nbackground. Equivalent to configuring the toplevel with\n.QW \"\\fB\\-background systemWindowHeaderBackground\\fR\" ,\nor to using a \\fBttk::frame\\fR.\n.SH \"SUPPORT COMMANDS\"\n.\\\" COMMAND: iconBitmap\n.TP\n\\fB::tk::mac::iconBitmap \\fIname width height \\-kind value\\fR\n.\nRenders native icons and bitmaps in Tk applications (including any image file\nreadable by NSImage). A native bitmap name is interpreted as follows (in\norder):\n.RS\n.IP \\(bu 3\npredefined builtin 32x32 icon name (\\fBstop\\fR, \\fBcaution\\fR, \\fBdocument\\fR,\netc.)\n.IP \\(bu 3\n\\fIname\\fR, as defined by \\fBtk::mac::iconBitmap\\fR\n.IP \\(bu 3\nNSImage named image name\n.IP \\(bu 3\nNSImage url string\n.IP \\(bu 3\n4-char OSType of IconServices icon\n.PP\nThe \\fIwidth\\fR and \\fIheight\\fR arguments to \\fBtk::mac::iconBitmap\\fR define\nthe dimensions of the image to create, and \\fI\\-kind\\fR must be one of:\n.\\\" OPTION: -file\n.TP\n\\fB\\-file\\fR\n.\nicon of file at given path\n.\\\" OPTION: -fileType\n.TP\n\\fB\\-fileType\\fR\n.\nicon of given file type\n.\\\" OPTION: -osType\n.TP\n\\fB\\-osType\\fR\n.\nicon of given 4-char OSType file type\n.\\\" OPTION: -systemType\n.TP\n\\fB\\-systemType\\fR\n.\nicon for given IconServices 4-char OSType\n.\\\" OPTION: -namedImage\n.TP\n\\fB\\-namedImage\\fR\n.\nnamed NSImage for given name\n.\\\" OPTION: -imageFile\n.TP\n\\fB\\-imageFile\\fR\n.\nimage at given path\n.RE\n.SH \"SEE ALSO\"\nbind(n), wm(n)\n.SH KEYWORDS\nabout dialog, antialiasing, Apple event, icon, NSImage\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/tkerror.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tkerror n 4.1 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntkerror \\- Command invoked to process background errors\n.SH SYNOPSIS\n\\fBtkerror \\fImessage\\fR\n.BE\n.SH DESCRIPTION\n.PP\nNote: as of Tk 4.1 the \\fBtkerror\\fR command has been renamed to\n\\fBbgerror\\fR because the event loop (which is what usually invokes\nit) is now part of Tcl. Using the \\fBtkerror\\fR name is deprecated.\n.PP\nFor backward compatibility\nthe \\fBbgerror\\fR provided by the current Tk version still\ntries to call \\fBtkerror\\fR if there is one (or an auto loadable one),\nso old script defining that error handler should still work, but you\nshould anyhow modify your scripts to use \\fBbgerror\\fR instead\nof \\fBtkerror\\fR because that support for the old name might vanish\nin the future. If that call fails, \\fBbgerror\\fR\nposts a dialog showing the error and offering to see the stack trace\nto the user. If you want your own error management you should\ndirectly override \\fBbgerror\\fR instead of \\fBtkerror\\fR.\nDocumentation for \\fBbgerror\\fR is available as part of Tcl's\ndocumentation.\n.SH KEYWORDS\nbackground error, reporting\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/tkvars.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tkvars n 4.1 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ngeometry, tk_library, tk_patchLevel, tk::scalingPct, tk_strictMotif, tk::svgFmt, tk_version \\- Variables used or set by Tk\n.BE\n.SH DESCRIPTION\n.PP\nThe following Tcl variables are either set or used by Tk at various times\nin its execution:\n.\\\" VARIABLE: tk_library\n.TP 15\n\\fBtk_library\\fR\n.\nThis variable holds the file name for a directory containing a library\nof Tcl scripts related to Tk. These scripts include an initialization\nfile that is normally processed whenever a Tk application starts up,\nplus other files containing procedures that implement default behaviors\nfor widgets.\n.RS\n.PP\nThe initial value of \\fBtk_library\\fR is set when Tk is added to\nan interpreter; this is done by searching several different directories\nuntil one is found that contains an appropriate Tk startup script.\nIf the \\fBTK_LIBRARY\\fR environment variable exists, then\nthe directory it names is checked first.\nIf \\fBTK_LIBRARY\\fR is not set or does not refer to an appropriate\ndirectory, then Tk checks several other directories based on a\ncompiled-in default location, the location of the Tcl library directory,\nthe location of the binary containing the application, and the current\nworking directory.\n.PP\nThe variable can be modified by an application to switch to a different\nlibrary.\n.RE\n.\\\" VARIABLE: tk_patchLevel\n.TP\n\\fBtk_patchLevel\\fR\n.\nContains a dot-separated sequence of decimal integers giving the\ncurrent patch level for Tk.\nThe patch level is incremented for each new release or patch, and\nit uniquely identifies an official version of Tk.\n.RS\n.PP\nThis value is normally the same as the result of\n.QW \"\\fBpackage require\\fR \\fBtk\\fR\" .\n.RE\n.\\\" VARIABLE: scalingPct\n.TP\n\\fBtk::scalingPct\\fR\n.\nTk sets this variable at initialization time to the scaling percentage\ncorresponding to the display's DPI scaling level. This value is at least\n100 and is restricted to multiples of 25 (100, 125, 150, 175, 200,\n225, ...). The sizes and various attributes of the Tk core and Ttk\nwidgets and their components, as well as the sizes of the images used by\nTk are chosen according to the scaling percentage, and this is\nrecommended for applications and library packages, too.\n.RS\n.PP\nNote that any access to this variable is supposed to be strictly\nread-only! Note also that whenever the scaling factor used to convert\nbetween physical units and pixels is changed via \\fBtk scaling\\fR, the\nvalue of the variable \\fBtk::scalingPct\\fR is automatically updated.\n.PP\nOn the windowing systems \\fBwin32\\fR and \\fBaqua\\fR the scaling\npercentage is computed by rounding [\\fBtk scaling\\fR] * 75 to the\nnearest multiple of 25 that is at least 100. (On \\fBaqua\\fR the result\nis always 100, and the desktop engine automatically scales everything as\nneeded.) On \\fBx11\\fR, deriving the scaling percentage from\n[\\fBtk scaling\\fR] is done as fallback method only, because the\nimplementation of display scaling is highly dependent on the desktop\nenvironment and it mostly manipulates system resources that are resident\noutside of Xlib, which Tk is based on. Moreover, for technical reasons,\nthe value assigned to the variable \\fBtk::scalingPct\\fR can be different\nfrom the one selected in the system settings (e.g., 200 rather than 125,\n150, or 175 when running GNOME on Xorg or the Cinnamon desktop). On\n\\fBx11\\fR the scaling percentage is computed mostly (but not\nexclusively) from the value of the X resource Xft.dpi, and, as an\nadditional step, Tk synchronizes the scaling factor used to convert\nbetween physical units and pixels with the scaling percentage, with the\naid of the \\fBtk scaling\\fR command.\n.RE\n.\\\" VARIABLE: tk_strictMotif\n.TP\n\\fBtk_strictMotif\\fR\n.\nThis variable is set to zero by default.\nIf an application sets it to one, then Tk attempts to adhere as\nclosely as possible to Motif look-and-feel standards.\nFor example, active elements such as buttons and scrollbar\nsliders will not change color when the pointer passes over them.\nModern applications should not normally set this variable.\n.\\\" VARIABLE: svgFmt\n.TP\n\\fBtk::svgFmt\\fR\n.\nThis variable is set at Tk initialization time to\n.RS\n.RS 4\n.PP\n[\\fBlist svg \\-scale\\fR [\\fBexpr\\fR {$\\fBtk::scalingPct\\fR / 100.0}]]\n.RE\n.PP\nTypical values are {\\fBsvg \\-scale\\fR 1.0}, {\\fBsvg \\-scale\\fR 1.25},\n{\\fBsvg \\-scale\\fR 2.0}, etc. It is recommended to pass the value of\nthis variable to the commands \\fBimage create photo\\fR, \\fIimageName\\fB\nconfigure\\fR, \\fIimageName\\fB put\\fR, and \\fIimageName\\fB read\\fR as the\nvalue of their \\fB\\-format\\fR option when creating or manipulating SVG\nimages, to make sure that their sizes will correspond to the display's\nDPI scaling level.\n.PP\nNote that any access to this variable is supposed to be strictly\nread-only! Note also that whenever the scaling factor used to convert\nbetween physical units and pixels is changed via \\fBtk scaling\\fR, the\nvalue of the variable \\fBtk::svgFmt\\fR is automatically updated.\n.RE\n.\\\" VARIABLE: tk_version\n.TP\n\\fBtk_version\\fR\n.\nTk sets this variable in the interpreter for each application.\nThe variable holds the current version number of the Tk\nlibrary in the form \\fImajor\\fR.\\fIminor\\fR. \\fIMajor\\fR and\n\\fIminor\\fR are integers. The major version number increases in\nany Tk release that includes changes that are not backward compatible\n(i.e. whenever existing Tk applications and scripts may have to change to\nwork with the new release). The minor version number increases with\neach new release of Tk, except that it resets to zero whenever the\nmajor version number changes.\n.SS \"INTERNAL AND DEBUGGING VARIABLES\"\n.PP\nThese variables should not normally be set by user code.\n.\\\" VARIABLE: Priv\n.TP\n\\fBtk::Priv\\fR\n.\nThis variable is an array containing several pieces of information\nthat are private to Tk. The elements of \\fBtk::Priv\\fR are used by\nTk library procedures and default bindings.\nThey should not be accessed by any code outside Tk.\n.\\\" VARIABLE: tk_textRedraw\n.\\\" VARIABLE: tk_textRelayout\n.TP\n\\fBtk_textRedraw\\fR\n.TP\n\\fBtk_textRelayout\\fR\n.\nThese variables are set by text widgets when they have debugging\nturned on. The values written to these variables can be used to\ntest or debug text widget operations. These variables are mostly\nused by Tk's test suite.\n.SH \"OTHER GLOBAL VARIABLES\"\nThe following variables are only guaranteed to exist in \\fBwish\\fR\nexecutables; the Tk library does not define them itself but many Tk\nenvironments do.\n.\\\" VARIABLE: geometry\n.TP\n\\fBgeometry\\fR\n.\nIf set, contains the user-supplied geometry specification to use for\nthe main Tk window.\n.SH \"SEE ALSO\"\npackage(n), tclvars(n), wish(1)\n.SH KEYWORDS\nenvironment, text, variables, version\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/tkwait.n", "content": "'\\\"\n'\\\" Copyright (c) 1992 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH tkwait n \"\" Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntkwait \\- Wait for variable to change or window to be destroyed\n.SH SYNOPSIS\n.nf\n\\fBtkwait variable \\fIname\\fR\n\\fBtkwait visibility \\fIname\\fR\n\\fBtkwait window \\fIname\\fR\n.fi\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBtkwait\\fR command waits for one of several things to happen,\nthen it returns without taking any other actions.\nThe return value is always an empty string.\n.\\\" METHOD: variable\nIf the first argument is \\fBvariable\\fR (or any abbreviation of\nit) then the second argument is the name of a global variable and the\ncommand waits for that variable to be modified.\n.\\\" METHOD: visibility\nIf the first argument is \\fBvisibility\\fR (or any abbreviation\nof it) then the second argument is the name of a window and the\n\\fBtkwait\\fR command waits for a change in its\nvisibility state (as indicated by the arrival of a VisibilityNotify\nevent). This form is typically used to wait for a newly-created\nwindow to appear on the screen before taking some action.\n.\\\" METHOD: window\nIf the first argument is \\fBwindow\\fR (or any abbreviation\nof it) then the second argument is the name of a window and the\n\\fBtkwait\\fR command waits for that window to be destroyed.\nThis form is typically used to wait for a user to finish interacting\nwith a dialog box before using the result of that interaction.\n.PP\nWhile the \\fBtkwait\\fR command is waiting it processes events in\nthe normal fashion, so the application will continue to respond\nto user interactions.\nIf an event handler invokes \\fBtkwait\\fR again, the nested call\nto \\fBtkwait\\fR must complete before the outer call can complete.\n.SH \"SEE ALSO\"\nbind(n), vwait(n)\n.SH KEYWORDS\nvariable, visibility, wait, window\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/toplevel.n", "content": "'\\\"\n'\\\" Copyright (c) 1990-1994 The Regents of the University of California.\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH toplevel n 8.4 Tk \"Tk Built-In Commands\"\n.so man.macros\n.BS\n'\\\" Note: do not modify the .SH NAME line immediately below!\n.SH NAME\ntoplevel \\- Create and manipulate 'toplevel' main and popup window widgets\n.SH SYNOPSIS\n\\fBtoplevel\\fI pathName \\fR?\\fIoptions\\fR?\n.SO\n\\-borderwidth\t\\-highlightcolor\t\\-pady\n\\-cursor\t\\-highlightthickness\t\\-relief\n\\-highlightbackground\t\\-padx\t\\-takefocus\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-background background Background\nThis option is the same as the standard \\fB\\-background\\fR option\nexcept that its value may also be specified as an empty string.\nIn this case, the widget will display no background or border, and\nno colors will be consumed from its colormap for its background\nand border.\n.VS \"9.0, TIP262\"\nAn empty background will disable drawing the background image.\n.OP \\-backgroundimage backgroundImage BackgroundImage\nThis specifies an image to display on the toplevel's background within\nthe border of the toplevel (i.e., the image will be clipped by the\ntoplevel's highlight ring and border, if either are present) on top of\nthe background;\nsubwidgets of the toplevel will be drawn on top. The image must have\nbeen created with the \\fBimage create\\fR command. If specified as the\nempty string, no image will be displayed.\n.VE \"9.0, TIP262\"\n.OP \\-class class Class\nSpecifies a class for the window.\nThis class will be used when querying the option database for\nthe window's other options, and it will also be used later for\nother purposes such as bindings. Some window managers display the\nclass name for windows in their dock while some others display the\nwindow title.\nThe \\fB\\-class\\fR option may not be changed with the \\fBconfigure\\fR\nwidget command.\n.OP \\-colormap colormap Colormap\nSpecifies a colormap to use for the window.\nThe value may be either \\fBnew\\fR, in which case a new colormap is\ncreated for the window and its children, or the name of another\nwindow (which must be on the same screen and have the same visual\nas \\fIpathName\\fR), in which case the new window will use the colormap\nfrom the specified window.\nIf the \\fB\\-colormap\\fR option is not specified, the new window\nuses the default colormap of its screen.\nThis option may not be changed with the \\fBconfigure\\fR\nwidget command.\n.OP \\-container container Container\nThe value must be a boolean. If true, it means that this window will\nbe used as a container in which some other application will be embedded\n(for example, a Tk toplevel can be embedded using the \\fB\\-use\\fR option).\nThe window will support the appropriate window manager protocols for\nthings like geometry requests. The window should not have any\nchildren of its own in this application.\nThis option may not be changed with the \\fBconfigure\\fR\nwidget command.\n.OP \\-height height Height\nSpecifies the desired height for the window in any of the forms\nacceptable to \\fBTk_GetPixels\\fR.\nIf this option is negative or zero then the window will\nnot request any size at all.\n.OP \\-menu menu Menu\nSpecifies a menu widget to be used as a menubar. On the Macintosh, the\nmenubar will be displayed across the top of the main monitor. On\nMicrosoft Windows and all UNIX platforms, the menu will appear across\nthe toplevel window as part of the window dressing maintained by the\nwindow manager.\n.OP \\-screen \"\" \"\"\nSpecifies the screen on which to place the new window.\nAny valid screen name may be used, even one associated with a\ndifferent display.\nDefaults to the same screen as its parent.\nThis option is special in that it may not be specified via the option\ndatabase, and it may not be modified with the \\fBconfigure\\fR\nwidget command.\n.OP \\-tile tile Tile\n.VS \"9.0, TIP262\"\nThis specifies how to draw the background image (see\n\\fB\\-backgroundimage\\fR) on the toplevel.\nIf true (according to \\fBTcl_GetBoolean\\fR), the image will be tiled\nto fill the whole toplevel, with the origin of the first copy of the\nimage being the top left of the interior of the toplevel.\nIf false (the default), the image will be centered within the toplevel.\n.VE \"9.0, TIP262\"\n.OP \\-use use Use\nThis option is used for embedding. If the value is not an empty string,\nit must be the window identifier of a container window, specified as\na hexadecimal string like the ones returned by the \\fBwinfo id\\fR\ncommand. The toplevel widget will be created as a child of the given\ncontainer instead of the root window for the screen. If the container\nwindow is in a Tk application, it must be a frame or toplevel widget for\nwhich the \\fB\\-container\\fR option was specified.\nThis option may not be changed with the \\fBconfigure\\fR\nwidget command.\n.OP \\-visual visual Visual\nSpecifies visual information for the new window in any of the\nforms accepted by \\fBTk_GetVisual\\fR.\nIf this option is not specified, the new window will use the default\nvisual for its screen.\nThe \\fB\\-visual\\fR option may not be modified with the \\fBconfigure\\fR\nwidget command.\n.OP \\-width width Width\nSpecifies the desired width for the window in any of the forms\nacceptable to \\fBTk_GetPixels\\fR.\nIf this option is negative or zero then the window will\nnot request any size at all.\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBtoplevel\\fR command creates a new toplevel widget (given\nby the \\fIpathName\\fR argument). Additional\noptions, described above, may be specified on the command line\nor in the option database\nto configure aspects of the toplevel such as its background color\nand relief. The \\fBtoplevel\\fR command returns the\npath name of the new window.\n.PP\nA toplevel is similar to a \\fBframe\\fR except that it is created as a\ntop-level window: its X parent is the root window of a screen\nrather than the logical parent from its Tk path name. The primary\npurpose of a toplevel is to serve as a container for dialog boxes\nand other collections of widgets. The only visible features\nof a toplevel are its background and an optional 3-D border\nto make the toplevel appear raised or sunken.\n.SH \"WIDGET COMMAND\"\n.PP\nThe \\fBtoplevel\\fR command creates a new Tcl command whose\nname is the same as the path name of the toplevel's window. This\ncommand may be used to invoke various\noperations on the widget. It has the following general form:\n.PP\n.CS\n\\fIpathName option \\fR?\\fIarg ...\\fR?\n.CE\n.PP\n\\fIPathName\\fR is the name of the command, which is the same as\nthe toplevel widget's path name. \\fIOption\\fR and the \\fIarg\\fRs\ndetermine the exact behavior of the command. The following\ncommands are possible for toplevel widgets:\n.\\\" METHOD: cget\n.TP\n\\fIpathName \\fBcget \\fIoption\\fR\n.\nReturns the current value of the configuration option given\nby \\fIoption\\fR.\n\\fIOption\\fR may have any of the values accepted by the \\fBtoplevel\\fR\ncommand.\n.\\\" METHOD: configure\n.TP\n\\fIpathName \\fBconfigure\\fR ?\\fIoption\\fR? ?\\fIvalue option value ...\\fR?\n.\nQuery or modify the configuration options of the widget.\nIf no \\fIoption\\fR is specified, returns a list describing all of\nthe available options for \\fIpathName\\fR (see \\fBTk_ConfigureInfo\\fR for\ninformation on the format of this list). If \\fIoption\\fR is specified\nwith no \\fIvalue\\fR, then the command returns a list describing the\none named option (this list will be identical to the corresponding\nsublist of the value returned if no \\fIoption\\fR is specified). If\none or more \\fIoption\\-value\\fR pairs are specified, then the command\nmodifies the given widget option(s) to have the given value(s); in\nthis case the command returns an empty string.\n\\fIOption\\fR may have any of the values accepted by the \\fBtoplevel\\fR\ncommand.\n.SH BINDINGS\n.PP\nWhen a new toplevel is created, it has no default event bindings:\ntoplevels are not intended to be interactive.\n.PP\nBe aware that bindings on toplevels may receive events from subwidgets.\n.SH \"SEE ALSO\"\nbind(n), bindtags(n), frame(n), wm(n)\n.SH KEYWORDS\ntoplevel, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_Geometry.3", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n.TH Geometry 3 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nTtk_MakeBox, Ttk_PadBox, Ttk_ExpandBox, Ttk_PackBox, Ttk_StickBox, Ttk_PlaceBox, Ttk_BoxContains, Ttk_MakePadding, Ttk_UniformPadding, Ttk_AddPadding, Ttk_RelievePadding, Ttk_GetPaddingFromObj, Ttk_GetBorderFromObj, Ttk_GetStickyFromObj \\- Tk themed geometry utilities\n.SH SYNOPSIS\n.nf\n\\fB#include \\fR\n\nTtk_Box\n\\fBTtk_MakeBox\\fR(int \\fIx\\fR, int \\fIy\\fR, int \\fIwidth\\fR, int \\fIheight\\fR);\n\nTtk_Box\n\\fBTtk_PadBox\\fR(Ttk_Box \\fIparcel\\fR, Ttk_Padding \\fIpadding\\fR);\n\nTtk_Box\n\\fBTtk_ExpandBox\\fR(Ttk_Box \\fIparcel\\fR, Ttk_Padding \\fIpadding\\fR);\n\nTtk_Box\n\\fBTtk_PackBox\\fR(Ttk_Box *\\fIcavity\\fR, int \\fIwidth\\fR, int \\fIheight\\fR, Ttk_Side \\fIside\\fR);\n\nTtk_Box\n\\fBTtk_StickBox\\fR(Ttk_Box \\fIparcel\\fR, int \\fIwidth\\fR, int \\fIheight\\fR, unsigned \\fIsticky\\fR);\n\nTtk_Box\n\\fBTtk_PlaceBox\\fR(Ttk_Box *\\fIcavity\\fR, int \\fIwidth\\fR, int \\fIheight\\fR, Ttk_Side \\fIside\\fR, unsigned \\fIsticky\\fR);\n\nTtk_Box\n\\fBTtk_AnchorBox\\fR(Ttk_Box \\fIparcel\\fR, int \\fIwidth\\fR, int \\fIheight\\fR, Tk_Anchor \\fIanchor\\fR);\n\nTtk_Padding\n\\fBTtk_MakePadding\\fR(short \\fIleft\\fR, short \\fItop\\fR, short \\fIright\\fR, short \\fIbottom\\fR);\n\nTtk_Padding\n\\fBTtk_UniformPadding\\fR(short \\fIborder\\fR);\n\nTtk_Padding\n\\fBTtk_AddPadding\\fR(Ttk_Padding \\fIpadding1\\fR, Ttk_Padding \\fIpadding2\\fR;\n\nTtk_Padding\n\\fBTtk_RelievePadding\\fR(Ttk_Padding \\fIpadding\\fR, int \\fIrelief\\fR);\n\nint\n\\fBTtk_BoxContains\\fR(Ttk_Box \\fIbox\\fR, int \\fIx\\fR, int \\fIy\\fR);\n\nint\n\\fBTtk_GetPaddingFromObj\\fR(Tcl_Interp *\\fIinterp\\fR, Tk_Window \\fItkwin\\fR, Tcl_Obj *\\fIobjPtr\\fR, Ttk_Padding *\\fIpadding_rtn\\fR);\n\nint\n\\fBTtk_GetBorderFromObj\\fR(Tcl_Interp *\\fIinterp\\fR, Tcl_Obj *\\fIobjPtr\\fR, Ttk_Padding *\\fIpadding_rtn\\fR);\n\nint\n\\fBTtk_GetStickyFromObj\\fR(Tcl_Interp *\\fIinterp\\fR, Tcl_Obj *\\fIobjPtr\\fR, int *\\fIsticky_rtn\\fR);\n.fi\n.SH ARGUMENTS\n.AP Tk_Anchor anchor in\nOne of the symbolic constants \\fBTK_ANCHOR_N\\fR, \\fBTK_ANCHOR_NE\\fR,\netc. See \\fITk_GetAnchorFromObj(3)\\fR.\n.AP \"Ttk_Box *\" cavity in/out\nA rectangular region from which a parcel is allocated.\n.AP short border in\nExtra padding (in pixels) to add uniformly to each side of a region.\n.AP short bottom in\nExtra padding (in pixels) to add to the bottom of a region.\n.AP Ttk_Box box in\nSpecifies a rectangular region.\n.AP \"Ttk_Box *\" box_rtn out\nA rectangular region.\n.AP int height in\nThe height in pixels of a region.\n.AP \"Tcl_Interp *\" interp in\nUsed to store error messages.\n.AP int left in\nExtra padding (in pixels) to add to the left side of a region.\n.AP \"Tcl_Obj *\" objPtr in\nString value contains a symbolic name\nto be converted to an enumerated value or bitmask.\nInternal rep may be be modified to cache corresponding value.\n.AP Ttk_Padding padding in\nExtra padding to add on the inside of a region.\n.AP \"Ttk_Padding *\" padding_rtn out\nPadding present in the inside of a region.\n.AP Ttk_Box parcel in\nA rectangular region, allocated from a cavity.\n.AP int relief in\nOne of the standard Tk relief options\n(\\fBTK_RELIEF_RAISED\\fR, \\fBTK_RELIEF_SUNKEN\\fR, etc.).\nSee \\fBTk_GetReliefFromObj\\fR.\n.AP short right in\nExtra padding (in pixels) to add to the right side of a region.\n.AP Ttk_Side side in\nOne of \\fBTTK_SIDE_LEFT\\fR, \\fBTTK_SIDE_TOP\\fR,\n\\fBTTK_SIDE_RIGHT\\fR, or \\fBTTK_SIDE_BOTTOM\\fR.\n.AP unsigned sticky in\nA bitmask containing one or more of the bits\n\\fBTTK_STICK_W\\fR (west, or left),\n\\fBTTK_STICK_E\\fR (east, or right),\n\\fBTTK_STICK_N\\fR (north, or top), and\n\\fBTTK_STICK_S\\fR (south, or bottom).\n\\fBTTK_FILL_X\\fR is defined as a synonym for\n(\\fBTTK_STICK_W\\fR|\\fBTTK_STICK_E\\fR),\n\\fBTTK_FILL_Y\\fR is a synonym for (\\fBTTK_STICK_N\\fR|\\fBTTK_STICK_S\\fR),\nand \\fBTTK_FILL_BOTH\\fR\nis a synonym for (\\fBTTK_FILL_X\\fR|\\fBTTK_FILL_Y\\fR).\nSee also: \\fIgrid(n)\\fR.\n.AP Tk_Window tkwin in\nWindow whose screen geometry determines\nthe conversion between absolute units and pixels.\n.AP short top in\nExtra padding at the top of a region.\n.AP int width in\nThe width in pixels of a region.\n.AP int x in\nX coordinate of upper-left corner of region.\n.AP int y in\nY coordinate of upper-left corner of region.\n.BE\n.SH \"BOXES\"\n.PP\nThe \\fBTtk_Box\\fR structure represents a rectangular region of a window:\n.CS\ntypedef struct {\n int \\fIx\\fR;\n int \\fIy\\fR;\n int \\fIwidth\\fR;\n int \\fIheight\\fR;\n} \\fBTtk_Box\\fR;\n.CE\nAll coordinates are relative to the window.\n.PP\n\\fBTtk_MakeBox\\fR is a convenience routine that constructs\na \\fBTtk_Box\\fR structure representing a region \\fIwidth\\fR pixels\nwide, \\fIheight\\fR pixels tall, at the specified \\fIx, y\\fR coordinates.\n.PP\n\\fBTtk_PadBox\\fR returns a new box located inside the specified \\fIparcel\\fR,\nshrunken according to the left, top, right, and bottom margins\nspecified by \\fIpadding\\fR.\n.PP\n\\fBTtk_ExpandBox\\fR is the inverse of \\fBTtk_PadBox\\fR:\nit returns a new box surrounding the specified \\fIparcel\\fR,\nexpanded according to the left, top, right, and bottom margins\nspecified by \\fIpadding\\fR.\n.PP\n\\fBTtk_PackBox\\fR allocates a parcel \\fIwidth\\fR by \\fIheight\\fR\npixels wide on the specified \\fIside\\fR of the \\fIcavity\\fR,\nand shrinks the \\fIcavity\\fR accordingly.\n.PP\n\\fBTtk_StickBox\\fR places a box with the requested \\fIwidth\\fR\nand \\fIheight\\fR inside the \\fIparcel\\fR according to the\n\\fIsticky\\fR bits.\n.PP\n\\fBTtk_PlaceBox\\fR combines \\fBTtk_PackBox\\fR and \\fBTtk_StickBox\\fR:\nit allocates a parcel on the specified \\fIside\\fR of the \\fIcavity\\fR,\nplaces a box of the requested size inside the parcel according to \\fIsticky\\fR,\nand shrinks the \\fIcavity\\fR.\n.PP\n\\fBTtk_AnchorBox\\fR places a box with the requested \\fIwidth\\fR\nand \\fIheight\\fR inside the \\fIparcel\\fR according to the\nspecified \\fIanchor\\fR option.\n.PP\n\\fBTtk_BoxContains\\fR tests if the specified \\fIx, y\\fR coordinate\nlies within the rectangular region \\fIbox\\fR.\n.SH \"PADDDING\"\n.PP\nThe \\fBTtk_Padding\\fR structure is used to represent\nborders, internal padding, and external margins:\n.CS\ntypedef struct {\n short \\fIleft\\fR;\n short \\fItop\\fR;\n short \\fIright\\fR;\n short \\fIbottom\\fR;\n} \\fBTtk_Padding\\fR;\n.CE\n.PP\n\\fBTtk_MakePadding\\fR is a convenience routine that constructs\na \\fBTtk_Padding\\fR structure with the specified left, top, right, and bottom\ncomponents.\n.PP\n\\fBTtk_UniformPadding\\fR constructs a \\fBTtk_Padding\\fR structure\nwith all components equal to the specified \\fIborder\\fR.\n.PP\n\\fBTtk_AddPadding\\fR adds two \\fBTtk_Padding\\fRs together\nand returns a combined padding containing the sum of the\nindividual padding components.\n.PP\n\\fBTtk_RelievePadding\\fR\nadds an extra 2 pixels of padding to \\fIpadding\\fR\naccording to the specified \\fIrelief\\fR.\nIf \\fIrelief\\fR is \\fBTK_RELIEF_SUNKEN\\fR,\nadds two pixels at the top and left\nso the inner region is shifted down and to the left.\nIf it is \\fBTK_RELIEF_RAISED\\fR, adds two pixels\nat the bottom and right so\nthe inner region is shifted up and to the right.\nOtherwise, adds 1 pixel on all sides.\nThis is typically used in element geometry procedures to simulate a\n.QW pressed-in\nlook for pushbuttons.\n.SH \"CONVERSION ROUTINES\"\n.PP\n\\fBTtk_GetPaddingFromObj\\fR converts the string in \\fIobjPtr\\fR\nto a \\fBTtk_Padding\\fR structure.\nThe string representation is a list of\nup to four length specifications\n.QW \"\\fIleft top right bottom\\fR\" .\nIf fewer than four elements are specified,\n\\fIbottom\\fR defaults to \\fItop\\fR,\n\\fIright\\fR defaults to \\fIleft\\fR, and\n\\fItop\\fR defaults to \\fIleft\\fR.\nSee \\fBTk_GetPixelsFromObj(3)\\fR for the syntax of length specifications.\n.PP\n\\fBTtk_GetBorderFromObj\\fR is the same as \\fBTtk_GetPaddingFromObj\\fR\nexcept that the lengths are specified as integers\n(i.e., resolution-dependent values like \\fI3m\\fR are not allowed).\n.PP\n\\fBTtk_GetStickyFromObj\\fR converts the string in \\fIobjPtr\\fR\nto a \\fIsticky\\fR bitmask. The string contains zero or more\nof the characters \\fBn\\fR, \\fBs\\fR, \\fBe\\fR, or \\fBw\\fR.\n.SH \"SEE ALSO\"\nTk_GetReliefFromObj(3), Tk_GetPixelsFromObj(3), Tk_GetAnchorFromObj(3)\n.SH \"KEYWORDS\"\ngeometry, padding, margins, box, region, sticky, relief\n" }, { "path": "doc/ttk_Theme.3", "content": "'\\\"\n'\\\" Copyright (c) 2003 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH Ttk_CreateTheme 3 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nTtk_CreateTheme, Ttk_GetTheme, Ttk_GetDefaultTheme, Ttk_GetCurrentTheme \\- create and use Tk themes.\n.SH SYNOPSIS\n.nf\nTtk_Theme Ttk_CreateTheme(\\fIinterp\\fR, \\fIname\\fR, \\fIparentTheme\\fR);\nTtk_Theme Ttk_GetTheme(\\fIinterp\\fR, \\fIname\\fR);\nTtk_Theme Ttk_GetDefaultTheme(\\fIinterp\\fR);\nTtk_Theme Ttk_GetCurrentTheme(\\fIinterp\\fR);\n.fi\n.SH ARGUMENTS\n.AP \"Tcl_Interp *\" interp in\nThe Tcl interpreter in which to register/query available themes.\n.AP \"Ttk_Theme\" parentTheme in\nFallback or parent theme from which the new theme will\ninherit elements and layouts.\n.AP \"const char *\" name in\nThe name of the theme.\n.BE\n.SH DESCRIPTION\n.\\\" TODO - Document these functions better!\n.SH \"SEE ALSO\"\nTtk_RegisterLayout, Ttk_BuildLayout\n.\\\" .SH KEYWORDS\n" }, { "path": "doc/ttk_button.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::button n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::button \\- Widget that issues a command when pressed\n.SH SYNOPSIS\n\\fBttk::button\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\nA \\fBttk::button\\fR widget displays a textual label and/or image,\nand evaluates a command when pressed.\n.SO ttk_widget\n\\-class\t\\-compound\t\\-cursor\n\\-image\t\\-justify\t\\-state\t\\-style\n\\-takefocus\t\\-text\t\\-textvariable\n\\-underline\t\\-width\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-command command Command\nA script to evaluate when the widget is invoked.\n.OP \\-default default Default\nMay be set to one of \\fBnormal\\fR, \\fBactive\\fR, or \\fBdisabled\\fR.\nIn a dialog box, one button may be designated the\n.QW default\nbutton (meaning, roughly,\n.QW \"the one that gets invoked when the user presses \" ).\n\\fBactive\\fR indicates that this is currently the default button;\n\\fBnormal\\fR means that it may become the default button, and\n\\fBdisabled\\fR means that it is not defaultable.\nThe default is \\fBnormal\\fR.\n.RS\n.PP\nDepending on the theme, the default button may be displayed\nwith an extra highlight ring, or with a different border color.\n.RE\n.\\\" Not documented -- may go away\n.\\\" .OP \\-padding padding Padding\n.\\\" .OP \\-foreground foreground Foreground\n.\\\" .OP \\-font font Font\n.\\\" .OP \\-anchor anchor Anchor\n.\\\" .OP \\-relief relief Relief\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\ncommands (see \\fBttk::widget\\fR),\nbutton widgets support the following additional commands:\n.\\\" METHOD: invoke\n.TP\n\\fIpathName \\fBinvoke\\fR\n.\nInvokes the command associated with the button.\n.SH \"STANDARD STYLES\"\n.PP\n\\fBTtk::button\\fR widgets support the \\fBToolbutton\\fR style in all standard\nthemes, which is useful for creating widgets for toolbars.\n.PP\nIn the Aqua theme there are several other styles which can be used to\nproduce replicas of many of the different button types that are\ndiscussed in Apple's Human Interface Guidelines. These include\n\\fBDisclosureButton\\fR, \\fBDisclosureTriangle\\fR, \\fBHelpButton\\fR,\n\\fBImageButton\\fR, \\fBInlineButton\\fR, \\fBGradientButton\\fR,\n\\fBRoundedRectButton\\fR, and \\fBRecessedButton\\fR.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::button\\fP is \\fBTButton\\fP.\n.PP\nDynamic states: \\fBactive\\fP, \\fBdisabled\\fP, \\fBpressed\\fP, \\fBreadonly\\fP.\n.PP\n\\fBTButton\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-anchor\\fP \\fIanchor\\fP\n.br\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-bordercolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-compound\\fP \\fIcompound\\fP\n.br\n\\fB\\-darkcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-font\\fP \\fIfont\\fP\n.br\n\\fB\\-highlightcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-highlightthickness\\fP \\fIamount\\fP\n.br\n\\fB\\-lightcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-padding\\fP \\fIpadding\\fP\n.br\n\\fB\\-relief\\fP \\fIrelief\\fP\n.br\n\\fB\\-shiftrelief\\fP \\fIamount\\fP\n.RS\n\\fB\\-shiftrelief\\fP specifies how far the button contents are\nshifted down and right in the \\fIpressed\\fP state.\nThis action provides additional skeuomorphic feedback.\n.RE\n\\fB\\-width\\fP \\fIamount\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), button(n)\n.SH \"KEYWORDS\"\nwidget, button, default, command\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_checkbutton.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::checkbutton n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::checkbutton \\- On/off widget\n.SH SYNOPSIS\n\\fBttk::checkbutton\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\nA \\fBttk::checkbutton\\fR widget is used to show or change a setting.\nIt has two states, selected and deselected.\nThe state of the checkbutton may be linked to a Tcl variable.\n.SO ttk_widget\n\\-class\t\\-compound\t\\-cursor\n\\-image\t\\-state\t\\-style\n\\-takefocus\t\\-text\t\\-textvariable\n\\-underline\t\\-width\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-command command Command\nA Tcl script to execute whenever the widget is invoked.\n.OP \\-offvalue offValue OffValue\nThe value to store in the associated \\fB\\-variable\\fR\nwhen the widget is deselected. Defaults to \\fB0\\fR.\n.OP \\-onvalue onValue OnValue\nThe value to store in the associated \\fB\\-variable\\fR\nwhen the widget is selected. Defaults to \\fB1\\fR.\n.OP \\-variable variable Variable\nThe name of a global variable whose value is linked to the widget.\nDefaults to the widget pathname if not specified.\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\ncommands (see \\fBttk::widget\\fR),\ncheckbutton widgets support the following additional commands:\n.\\\" METHOD: invoke\n.TP\n\\fIpathname\\fB invoke\\fR\n.\nToggles between the selected and deselected states\nand evaluates the associated \\fB\\-command\\fR.\nIf the widget is currently selected, sets the \\fB\\-variable\\fR\nto the \\fB\\-offvalue\\fR and deselects the widget;\notherwise, sets the \\fB\\-variable\\fR to the \\fB\\-onvalue\\fR\nReturns the result of the \\fB\\-command\\fR.\n.\\\" Missing: select, deselect, toggle\n.\\\" Are these useful? They don't invoke the -command\n.\\\" Missing: flash. This is definitely not useful.\n.SH \"WIDGET STATES\"\n.PP\nThe widget does not respond to user input if the \\fBdisabled\\fR state is set.\nThe widget sets the \\fBselected\\fR state whenever\nthe linked \\fB\\-variable\\fR is set to the widget's \\fB\\-onvalue\\fR,\nand clears it otherwise.\nThe widget sets the \\fBalternate\\fR state whenever the\nlinked \\fB\\-variable\\fR is unset.\n(The \\fBalternate\\fR state may be used to indicate a\n.QW tri-state\nor\n.QW indeterminate\nselection.)\n.SH \"STANDARD STYLES\"\n.PP\n\\fBTtk::checkbutton\\fR widgets support the \\fBToolbutton\\fR style in all\nstandard themes, which is useful for creating widgets for toolbars.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::checkbutton\\fP is \\fBTCheckbutton\\fP.\n.PP\nDynamic states: \\fBactive\\fP, \\fBalternate\\fP, \\fBdisabled\\fP,\n\\fBpressed\\fP, \\fBselected\\fP, \\fBreadonly\\fP.\n.PP\n\\fBTCheckbutton\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-compound\\fP \\fIcompound\\fP\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-indicatorbackground\\fP \\fIcolor\\fP\n.br\n\\fB\\-indicatorcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-indicatormargin\\fP \\fIpadding\\fP\n.br\n\\fB\\-indicatorrelief\\fP \\fIrelief\\fP\n.br\n\\fB\\-padding\\fP \\fIpadding\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), ttk::radiobutton(n), checkbutton(n)\n.SH \"KEYWORDS\"\nwidget, button, toggle, check, option\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_combobox.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::combobox n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::combobox \\- text field with popdown selection list\n.SH SYNOPSIS\n\\fBttk::combobox\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::combobox\\fR combines a text field with a pop-down list of values;\nthe user may select the value of the text field from among the\nvalues in the list.\n.SO ttk_widget\n\\-class\t\\-cursor\t\\-takefocus\n\\-style\t\\-placeholder\t\\-placeholderforeground\n.SE\n.\\\" ALSO: Other entry widget options\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-exportselection exportSelection ExportSelection\nBoolean value.\nIf set, the widget selection is linked to the X selection.\n.OP \\-justify justify Justify\nSpecifies how the text is aligned within the widget.\nMust be one of \\fBleft\\fR, \\fBcenter\\fR, or \\fBright\\fR.\n.OP \\-height height Height\nSpecifies the height of the pop-down listbox, in rows.\n.OP \\-postcommand postCommand PostCommand\nA Tcl script to evaluate immediately before displaying the listbox.\nThe \\fB\\-postcommand\\fR script may specify the \\fB\\-values\\fR to display.\n.OP \\-state state State\nOne of \\fBnormal\\fR, \\fBreadonly\\fR, or \\fBdisabled\\fR.\nIn the \\fBreadonly\\fR state,\nthe value may not be edited directly, and\nthe user can only select one of the \\fB\\-values\\fR from the\ndropdown list.\nIn the \\fBnormal\\fR state,\nthe text field is directly editable.\nIn the \\fBdisabled\\fR state, no interaction is possible.\n.OP \\-textvariable textVariable TextVariable\nSpecifies the name of a global variable whose value is linked\nto the widget value.\nWhenever the variable changes value the widget value is updated,\nand vice versa.\n.OP \\-values values Values\nSpecifies the list of values to display in the drop-down listbox.\n.OP \\-width width Width\nSpecifies an integer value indicating the desired width of the entry window,\nin average-size characters of the widget's font.\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\ncommands (see \\fBttk::widget\\fR),\ncombobox widgets support the following additional commands:\n.\\\" METHOD: current\n.TP\n\\fIpathName \\fBcurrent\\fR ?\\fInewIndex\\fR?\n.\nIf \\fInewIndex\\fR is supplied, sets the combobox value\nto the element at position \\fInewIndex\\fR in the list of \\fB\\-values\\fR\n(in addition to integers, the \\fBend\\fR index is supported and indicates\nthe last element of the list, moreover the same simple interpretation as\nfor the command \\fBstring index\\fR is supported, with simple integer index\narithmetic and indexing relative to \\fBend\\fR).\nOtherwise, returns the index of the current value in the list of\n\\fB\\-values\\fR or \\fB{}\\fR if the current value does not appear in the list.\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget\\fR\n.\nReturns the current value of the combobox.\n.\\\" METHOD: set\n.TP\n\\fIpathName \\fBset\\fI value\\fR\n.\nSets the value of the combobox to \\fIvalue\\fR.\n.PP\nThe combobox widget also supports the following \\fBttk::entry\\fR\nwidget commands:\n.DS\n.ta 5.5c 11c\n\\fBbbox\\fR\t\\fBdelete\\fR\t\\fBicursor\\fR\n\\fBindex\\fR\t\\fBinsert\\fR\t\\fBselection\\fR\n\\fBxview\\fR\n.DE\n.SH \"VIRTUAL EVENTS\"\n.PP\nThe combobox widget generates a \\fB<>\\fR virtual event\nwhen the user selects an element from the list of values.\nIf the selection action unposts the listbox,\nthis event is delivered after the listbox is unposted.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::combobox\\fP is \\fBTCombobox\\fP.\nThe \\fBttk::combobox\\fP uses the \\fBentry\\fP and\n\\fBlistbox\\fP widgets internally.\nThe listbox frame has a class name of \\fBComboboxPopdownFrame\\fP.\n.PP\nDynamic states: \\fBdisabled\\fP, \\fBfocus\\fP, \\fBpressed\\fP, \\fBreadonly\\fP.\n.PP\n\\fBTCombobox\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-arrowcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-arrowsize\\fP \\fIamount\\fP\n.br\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-bordercolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-darkcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-focusfill\\fP \\fIcolor\\fP\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-fieldbackground\\fP \\fIcolor\\fP\n.RS\nCan only be changed when using non-native and non-graphical themes.\n.RE\n\\fB\\-insertcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-insertwidth\\fP \\fIamount\\fP\n.br\n\\fB\\-lightcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-padding\\fP \\fIpadding\\fP\n.br\n\\fB\\-placeholderforeground\\fP \\fIcolor\\fP\n.br\n\\fB\\-postoffset\\fP \\fIpadding\\fP\n.br\n\\fB\\-selectbackground\\fP \\fIcolor\\fP\n.RS\nText entry select background.\n.RE\n\\fB\\-selectforeground\\fP \\fIcolor\\fP\n.RS\nText entry select foreground.\n.RE\n.PP\nThe \\fBttk::combobox\\fP popdown listbox cannot be configured using\n\\fBttk::style\\fP nor via the widget \\fBconfigure\\fP command. The listbox\ncan be configured using the option database.\n.PP\noption add *TCombobox*Listbox.background \\fIcolor\\fP\n.br\noption add *TCombobox*Listbox.font \\fIfont\\fP\n.br\noption add *TCombobox*Listbox.foreground \\fIcolor\\fP\n.br\noption add *TCombobox*Listbox.selectBackground \\fIcolor\\fP\n.br\noption add *TCombobox*Listbox.selectForeground \\fIcolor\\fP\n.PP\nTo configure a specific listbox (subject to future change):\n.CS\nset popdown [ttk::combobox::PopdownWindow .mycombobox]\n$popdown.f.l configure \\-font \\fIfont\\fP\n.CE\n.PP\n\\fBComboboxPopdownFrame\\fP\nstyling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-borderwidth\\fP \\fIamount\\fP\n.br\n\\fB\\-relief\\fP \\fIrelief\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), ttk::entry(n)\n.SH KEYWORDS\nchoice, entry, list box, text box, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_entry.n", "content": "'\\\"\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\" Copyright (c) 1998-2000 Scriptics Corporation.\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::entry n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::entry \\- Editable text field widget\n.SH SYNOPSIS\n\\fBttk::entry\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nAn \\fBttk::entry\\fR widget displays a one-line text string and\nallows that string to be edited by the user.\nThe value of the string may be linked to a Tcl variable\nwith the \\fB\\-textvariable\\fR option.\nEntry widgets support horizontal scrolling with the\nstandard \\fB\\-xscrollcommand\\fR option and \\fBxview\\fR widget command.\n.SO ttk_widget\n\\-class\t\\-cursor\n\\-font\t\\-foreground\n\\-style\n\\-takefocus\t\\-xscrollcommand\t\\-placeholder\t\\-placeholderforeground\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-exportselection exportSelection ExportSelection\nA boolean value specifying whether or not\na selection in the widget should be linked to the X selection.\nIf the selection is exported, then selecting in the widget deselects\nthe current X selection, selecting outside the widget deselects any\nwidget selection, and the widget will respond to selection retrieval\nrequests when it has a selection.\n.\\\" MAYBE: .OP \\-insertbackground insertBackground Foreground\n.\\\" MAYBE: .OP \\-insertwidth insertWidth InsertWidth\n.OP \\-invalidcommand invalidCommand InvalidCommand\nA script template to evaluate whenever the \\fB\\-validatecommand\\fR returns 0.\nSee \\fBVALIDATION\\fR below for more information.\n.OP \\-justify justify Justify\nSpecifies how the text is aligned within the entry widget.\nOne of \\fBleft\\fR, \\fBcenter\\fR, or \\fBright\\fR.\n.\\\" MAYBE: .OP \\-selectbackground selectBackground Foreground\n.\\\" MAYBE: .OP \\-selectborderwidth selectBorderWidth BorderWidth\n.\\\" MAYBE: .OP \\-selectforeground selectForeground Background\n.OP \\-show show Show\nIf this option is specified, then the true contents of the entry\nare not displayed in the window.\nInstead, each character in the entry's value will be displayed as\nthe first character in the value of this option, such as\n.QW *\nor a bullet.\nThis is useful, for example, if the entry is to be used to enter\na password.\nIf characters in the entry are selected and copied elsewhere, the\ninformation copied will be what is displayed, not the true contents\nof the entry.\n.OP \\-state state State\nCompatibility option; see \\fIttk::widget(n)\\fR for details.\nSpecifies one of three states for the entry,\n\\fBnormal\\fR, \\fBdisabled\\fR, or \\fBreadonly\\fR.\nSee \\fBWIDGET STATES\\fR, below.\n.OP \\-textvariable textVariable Variable\nSpecifies the name of a global variable whose value is linked\nto the entry widget's contents.\nWhenever the variable changes value, the widget's contents are updated,\nand vice versa.\n.OP \\-validate validate Validate\nSpecifies the mode in which validation should operate:\n\\fBnone\\fR, \\fBfocus\\fR, \\fBfocusin\\fR, \\fBfocusout\\fR, \\fBkey\\fR, or \\fBall\\fR.\nDefault is \\fBnone\\fR, meaning that validation is disabled.\nSee \\fBVALIDATION\\fR below.\n.OP \\-validatecommand validateCommand ValidateCommand\nA script template to evaluate whenever validation is triggered.\nIf set to the empty string (the default), validation is disabled.\nThe script must return a boolean value.\nSee \\fBVALIDATION\\fR below.\n.OP \\-width width Width\nSpecifies an integer value indicating the desired width of the entry window,\nin average-size characters of the widget's font.\n.\\\" Not in ttk: If the value is negative or zero, the widget picks a\n.\\\" Not in ttk: size just large enough to hold its current text.\n.SH NOTES\n.PP\nA portion of the entry may be selected as described below.\nIf an entry is exporting its selection (see the \\fB\\-exportselection\\fR\noption), then it will observe the standard X11 protocols for handling the\nselection; entry selections are available as type \\fBSTRING\\fR.\nEntries also observe the standard Tk rules for dealing with the\ninput focus. When an entry has the input focus it displays an\n\\fIinsert cursor\\fR to indicate where new characters will be\ninserted.\n.PP\nEntries are capable of displaying strings that are too long to\nfit entirely within the widget's window. In this case, only a\nportion of the string will be displayed; commands described below\nmay be used to change the view in the window. Entries use\nthe standard \\fB\\-xscrollcommand\\fR mechanism for interacting with\nscrollbars (see the description of the \\fB\\-xscrollcommand\\fR option\nfor details).\n.SH \"INDICES\"\n.PP\nMany of the \\fBentry\\fR widget commands take one or more indices as\narguments. An index specifies a particular character in the entry's\nstring, in any of the following ways:\n.IP \\fInumber\\fR\nSpecifies the character as a numerical index, where 0 corresponds\nto the first character in the string.\n.IP \\fB@\\fInumber\\fR\nIn this form, \\fInumber\\fR is treated as an x-coordinate in the\nentry's window; the character spanning that x-coordinate is used.\nFor example,\n.QW \\fB@0\\fR\nindicates the left-most character in the window.\n.IP \\fBend\\fR\nIndicates the character just after the last one in the entry's string.\nThis is equivalent to specifying a numerical index equal to the length\nof the entry's string.\n.IP \\fBinsert\\fR\nIndicates the character adjacent to and immediately following the\ninsert cursor.\n.IP \\fBsel.first\\fR\nIndicates the first character in the selection. It is an error to\nuse this form if the selection is not in the entry window.\n.IP \\fBsel.last\\fR\nIndicates the character just after the last one in the selection.\nIt is an error to use this form if the selection is not in the\nentry window.\n.LP\nAbbreviations may be used for any of the forms above, e.g.\\|\n.QW \\fBe\\fR\nor\n.QW \\fBsel.l\\fR .\nIn general, out-of-range indices are automatically rounded to the\nnearest legal value.\nIndexes support the same simple interpretation as\nfor the command \\fBstring index\\fR, with simple integer index\narithmetic and indexing relative to \\fBend\\fR.\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR, \\fBstyle\\fR and \\fBxview\\fR\ncommands (see \\fBttk::widget\\fR),\nentry widgets support the following additional commands:\n.\\\" METHOD: bbox\n.TP\n\\fIpathName \\fBbbox \\fIindex\\fR\n.\nReturns a list of four numbers describing the bounding box of the\ncharacter given by \\fIindex\\fR.\nThe first two elements of the list give the x and y coordinates of\nthe upper-left corner of the screen area covered by the character\n(in pixels relative to the widget) and the last two elements give\nthe width and height of the character, in pixels.\nThe bounding box may refer to a region outside the visible area\nof the window.\n.\\\" METHOD: delete\n.TP\n\\fIpathName \\fBdelete \\fIfirst \\fR?\\fIlast\\fR?\n.\nDelete one or more elements of the entry.\n\\fIFirst\\fR is the index of the first character to delete, and\n\\fIlast\\fR is the index of the character just after the last\none to delete.\nIf \\fIlast\\fR is not specified it defaults to \\fIfirst\\fR+1,\ni.e. a single character is deleted.\nThis command returns the empty string.\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget\\fR\n.\nReturns the entry's string.\n.\\\" METHOD: icursor\n.TP\n\\fIpathName \\fBicursor \\fIindex\\fR\n.\nArrange for the insert cursor to be displayed just before the character\ngiven by \\fIindex\\fR. Returns the empty string.\n.\\\" METHOD: index\n.TP\n\\fIpathName \\fBindex\\fI index\\fR\n.\nReturns the numerical index corresponding to \\fIindex\\fR.\n.\\\" METHOD: insert\n.TP\n\\fIpathName \\fBinsert \\fIindex string\\fR\n.\nInsert \\fIstring\\fR just before the character\nindicated by \\fIindex\\fR. Returns the empty string.\n.\\\" METHOD: selection\n.TP\n\\fIpathName \\fBselection \\fIoption arg\\fR\n.\nThis command is used to adjust the selection within an entry. It\nhas several forms, depending on \\fIoption\\fR:\n.RS\n.TP\n\\fIpathName \\fBselection clear\\fR\n.\nClear the selection if it is currently in this widget.\nIf the selection is not in this widget then the command has no effect.\nReturns the empty string.\n.TP\n\\fIpathName \\fBselection present\\fR\n.\nReturns 1 if there is are characters selected in the entry,\n0 if nothing is selected.\n.TP\n\\fIpathName \\fBselection range \\fIstart end\\fR\n.\nSets the selection to include the characters starting with\nthe one indexed by \\fIstart\\fR and ending with the one just\nbefore \\fIend\\fR.\nIf \\fIend\\fR refers to the same character as \\fIstart\\fR or an\nearlier one, then the entry's selection is cleared.\n.RE\n.\\\" METHOD: validate\n.TP\n\\fIpathName \\fBvalidate\\fR\n.\nForce revalidation, independent of the conditions specified\nby the \\fB\\-validate\\fR option.\nReturns 0 if validation fails, 1 if it succeeds.\nSets or clears the \\fBinvalid\\fR state accordingly.\nSee \\fBVALIDATION\\fR below for more details.\n.SH VALIDATION\n.PP\nThe \\fB\\-validate\\fR, \\fB\\-validatecommand\\fR, and \\fB\\-invalidcommand\\fR\noptions are used to enable entry widget validation.\n.SS \"VALIDATION MODES\"\n.PP\nThere are two main validation modes: \\fIprevalidation\\fR,\nin which the \\fB\\-validatecommand\\fR is evaluated prior to each edit\nand the return value is used to determine whether to accept\nor reject the change;\nand \\fIrevalidation\\fR, in which the \\fB\\-validatecommand\\fR is\nevaluated to determine whether the current value is valid.\n.PP\nThe \\fB\\-validate\\fR option determines when validation occurs;\nit may be set to any of the following values:\n.RS\n.IP \\fBnone\\fR\nDefault. This means validation will only occur when\nspecifically requested by the \\fBvalidate\\fR widget command.\n.IP \\fBkey\\fR\nThe entry will be prevalidated prior to each edit\n(specifically, whenever the \\fBinsert\\fR or \\fBdelete\\fR\nwidget commands are called).\nIf prevalidation fails, the edit is rejected.\n.IP \\fBfocus\\fR\nThe entry is revalidated when the entry receives or loses focus.\n.IP \\fBfocusin\\fR\nThe entry is revalidated when the entry receives focus.\n.IP \\fBfocusout\\fR\nThe entry is revalidated when the entry loses focus.\n.IP \\fBall\\fR\nValidation is performed for all above conditions.\n.RE\n.PP\nThe \\fB\\-invalidcommand\\fR is evaluated whenever\nthe \\fB\\-validatecommand\\fR returns a false value.\n.PP\nThe \\fB\\-validatecommand\\fR and \\fB\\-invalidcommand\\fR\nmay modify the entry widget's value\nvia the widget \\fBinsert\\fR or \\fBdelete\\fR commands,\nor by setting the linked \\fB\\-textvariable\\fR.\nIf either does so during prevalidation,\nthen the edit is rejected\nregardless of the value returned by the \\fB\\-validatecommand\\fR.\n.PP\nIf \\fB\\-validatecommand\\fR is empty (the default),\nvalidation always succeeds.\n.SS \"VALIDATION SCRIPT SUBSTITUTIONS\"\n.PP\nIt is possible to perform percent substitutions on the\n\\fB\\-validatecommand\\fR and \\fB\\-invalidcommand\\fR,\njust as in a \\fBbind\\fR script.\nThe following substitutions are recognized:\n.RS\n.IP \\fB%d\\fR\nType of action: 1 for \\fBinsert\\fR prevalidation,\n0 for \\fBdelete\\fR prevalidation,\nor \\-1 for revalidation.\n.IP \\fB%i\\fR\nIndex of character string to be inserted/deleted, if any, otherwise \\-1.\n.IP \\fB%P\\fR\nIn prevalidation, the new value of the entry if the edit is accepted.\nIn revalidation, the current value of the entry.\n.IP \\fB%s\\fR\nThe current value of entry prior to editing.\n.IP \\fB%S\\fR\nThe text string being inserted/deleted, if any, {} otherwise.\n.IP \\fB%v\\fR\nThe current value of the \\fB\\-validate\\fR option.\n.IP \\fB%V\\fR\nThe validation condition that triggered the callback\n(\\fBkey\\fR, \\fBfocusin\\fR, \\fBfocusout\\fR, or \\fBforced\\fR).\n.IP \\fB%W\\fR\nThe name of the entry widget.\n.RE\n.SS \"DIFFERENCES FROM TK ENTRY WIDGET VALIDATION\"\n.PP\nThe standard Tk entry widget automatically disables validation\n(by setting \\fB\\-validate\\fR to \\fBnone\\fR)\nif the \\fB\\-validatecommand\\fR or \\fB\\-invalidcommand\\fR modifies\nthe entry's value.\nThe Tk themed entry widget only disables validation if one\nof the validation scripts raises an error, or if \\fB\\-validatecommand\\fR\ndoes not return a valid boolean value.\n(Thus, it is not necessary to re-enable validation after\nmodifying the entry value in a validation script).\n.PP\nIn addition, the standard entry widget invokes validation whenever the linked\n\\fB\\-textvariable\\fR is modified; the Tk themed entry widget does not.\n.SH \"DEFAULT BINDINGS\"\n.PP\nThe entry widget's default bindings enable the following behavior.\nIn the descriptions below,\n.QW word\nrefers to a contiguous group of letters, digits, or\n.QW _\ncharacters, or any single character other than these.\n.IP \\0\\(bu 4\nClicking mouse button 1 positions the insert cursor\njust before the character underneath the mouse cursor, sets the\ninput focus to this widget, and clears any selection in the widget.\nDragging with mouse button 1 down strokes out a selection between\nthe insert cursor and the character under the mouse.\n.IP \\0\\(bu 4\nDouble-clicking with mouse button 1 selects the word under the mouse\nand positions the insert cursor at the end of the word.\nDragging after a double click strokes out a selection consisting\nof whole words.\n.IP \\0\\(bu 4\nTriple-clicking with mouse button 1 selects all of the text in the\nentry and positions the insert cursor at the end of the line.\n.IP \\0\\(bu 4\nThe ends of the selection can be adjusted by dragging with mouse\nbutton 1 while the Shift key is down.\nIf the button is double-clicked before dragging then the selection\nwill be adjusted in units of whole words.\n.IP \\0\\(bu 4\nClicking mouse button 1 with the Control key down will position the\ninsert cursor in the entry without affecting the selection.\n.IP \\0\\(bu 4\nIf any normal printing characters are typed in an entry, they are\ninserted at the point of the insert cursor.\n.IP \\0\\(bu 4\nThe view in the entry can be adjusted by dragging with the middle\nmouse button (button 2, or button 3 in TkAqua). If the middle mouse\nbutton is clicked without moving the mouse, the selection is copied\ninto the entry at the position of the mouse cursor.\n.IP \\0\\(bu 4\nIf the mouse is dragged out of the entry on the left or right sides\nwhile button 1 is pressed, the entry will automatically scroll to\nmake more text visible (if there is more text off-screen on the side\nwhere the mouse left the window).\n.IP \\0\\(bu 4\nThe Left and Right keys move the insert cursor one character to the\nleft or right; they also clear any selection in the entry.\nIf Left or Right is typed with the Shift key down, then the insertion\ncursor moves and the selection is extended to include the new character.\nControl-Left and Control-Right move the insert cursor by words, and\nControl-Shift-Left and Control-Shift-Right move the insert cursor\nby words and also extend the selection.\nControl-b and Control-f behave the same as Left and Right, respectively.\n.IP \\0\\(bu 4\nThe Home key and Control-a move the insert cursor to the\nbeginning of the entry and clear any selection in the entry.\nShift-Home moves the insert cursor to the beginning of the entry\nand extends the selection to that point.\n.IP \\0\\(bu 4\nThe End key and Control-e move the insert cursor to the\nend of the entry and clear any selection in the entry.\nShift-End moves the cursor to the end and extends the selection\nto that point.\n.IP \\0\\(bu 4\nControl-/ selects all the text in the entry.\n.IP \\0\\(bu 4\nControl-\\e clears any selection in the entry.\n.IP \\0\\(bu 4\nThe standard Tk <>, <>, <>, and <>\nvirtual events operate on the selection in the expected manner.\n.IP \\0\\(bu 4\nThe Delete key deletes the selection, if there is one in the entry.\nIf there is no selection, it deletes the character to the right of\nthe insert cursor.\n.IP \\0\\(bu 4\nThe BackSpace key and Control-h delete the selection, if there is one\nin the entry.\nIf there is no selection, it deletes the character to the left of\nthe insert cursor.\n.IP \\0\\(bu 4\nControl-d deletes the character to the right of the insert cursor.\n.IP \\0\\(bu 4\nControl-k deletes all the characters to the right of the insertion\ncursor.\n.SH \"WIDGET STATES\"\n.PP\nIn the \\fBdisabled\\fR state,\nthe entry cannot be edited and the text cannot be selected.\nIn the \\fBreadonly\\fR state,\nno insert cursor is displayed and\nthe entry cannot be edited\n(specifically: the \\fBinsert\\fR and \\fBdelete\\fR commands have no effect).\nThe \\fBdisabled\\fR state is the same as \\fBreadonly\\fR,\nand in addition text cannot be selected.\n.PP\nNote that changes to the linked \\fB\\-textvariable\\fR will\nstill be reflected in the entry, even if it is disabled or readonly.\n.PP\nTypically, the text is\n.QW grayed-out\nin the \\fBdisabled\\fR state,\nand a different background is used in the \\fBreadonly\\fR state.\n.PP\nThe entry widget sets the \\fBinvalid\\fR state if revalidation fails,\nand clears it whenever validation succeeds.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::entry\\fP is \\fBTEntry\\fP.\n.PP\nDynamic states: \\fBdisabled\\fP, \\fBfocus\\fP, \\fBreadonly\\fP.\n.PP\n\\fBTEntry\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.RS\nFor backwards compatibility, when using the aqua theme (for macOS), this\noption behaves as an alias for the \\fB\\-fieldbackground\\fP provided that no\nvalue is specified for \\fB\\-fieldbackground\\fP. Otherwise it is ignored.\n.RE\n\\fB\\-bordercolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-darkcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-fieldbackground\\fP \\fIcolor\\fP\n.RS\nSome themes use a graphical background and their field background colors\ncannot be changed.\n.RE\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-insertcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-insertwidth\\fP \\fIamount\\fP\n.br\n\\fB\\-lightcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-padding\\fP \\fIpadding\\fP\n.br\n\\fB\\-placeholderforeground\\fP \\fIcolor\\fP\n.br\n\\fB\\-relief\\fP \\fIrelief\\fP\n.br\n\\fB\\-selectbackground\\fP \\fIcolor\\fP\n.br\n\\fB\\-selectborderwidth\\fP \\fIamount\\fP\n.br\n\\fB\\-selectforeground\\fP \\fIcolor\\fP\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), entry(n)\n.SH KEYWORDS\nentry, widget, text field\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_frame.n", "content": "'\\\"\n'\\\" Copyright (c) 2005 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::frame n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::frame \\- Simple container widget\n.SH SYNOPSIS\n\\fBttk::frame\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::frame\\fR widget is a container, used to group other widgets\ntogether.\n.SO ttk_widget\n\\-class\t\\-cursor\t\\-padding\n\\-style\t\\-takefocus\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-borderwidth borderWidth BorderWidth\nThe desired width of the widget border. Defaults to 0.\nMay be ignored depending on the theme used.\n.OP \\-relief relief Relief\nOne of the standard Tk border styles:\n\\fBflat\\fR, \\fBgroove\\fR, \\fBraised\\fR, \\fBridge\\fR,\n\\fBsolid\\fR, or \\fBsunken\\fR.\nDefaults to \\fBflat\\fR.\n.OP \\-width width Width\nIf specified, the widget's requested width in pixels.\n.OP \\-height height Height\nIf specified, the widget's requested height in pixels.\n.SH \"WIDGET COMMAND\"\n.PP\nFrame widgets support the standard commands\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\n(see \\fBttk::widget\\fR).\n.SH \"NOTES\"\n.PP\nNote that if the \\fBpack\\fR, \\fBgrid\\fR, or other geometry managers\nare used to manage the children of the \\fBframe\\fR,\nby the GM's requested size will normally take precedence\nover the \\fBframe\\fR widget's \\fB\\-width\\fR and \\fB\\-height\\fR options.\n\\fBpack propagate\\fR and \\fBgrid propagate\\fR can be used\nto change this.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::frame\\fP is \\fBTFrame\\fP.\n.PP\n\\fBTFrame\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-relief\\fP \\fIrelief\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH BINDINGS\n.PP\nWhen a new \\fBttk::frame\\fR is created, it has no default event bindings;\n\\fBttk::frame\\fRs are not intended to be interactive.\n.SH \"SEE ALSO\"\nttk::widget(n), ttk::labelframe(n), frame(n)\n.SH \"KEYWORDS\"\nwidget, frame, container\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_image.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk_image n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk_image \\- Define an element based on an image\n.SH SYNOPSIS\n\\fBttk::style element create \\fIname \\fBimage\\fI imageSpec\\fR ?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fIimage\\fR element factory creates a new element\nin the current theme whose visual appearance is determined\nby Tk images.\n\\fIimageSpec\\fP is a list of one or more elements.\nThe first element is the default image name.\nThe rest of the list is a sequence of \\fIstatespec / value\\fR\npairs specifying other images to use when the element is\nin a particular state or combination of states.\n.SH OPTIONS\n.PP\nValid \\fIoptions\\fR are:\n.\\\" OPTION: -border\n.TP\n\\fB\\-border\\fI padding\\fR\n.\n\\fIpadding\\fR is a list of up to four integers, specifying\nthe left, top, right, and bottom borders, respectively.\nIf fewer than four elements are specified,\n\\fIbottom\\fR defaults to \\fItop\\fR,\n\\fIright\\fR defaults to \\fIleft\\fR, and\n\\fItop\\fR defaults to \\fIleft\\fR.\nIn other words, a list of three numbers specify the left, vertical, and right\nborder; a list of two numbers specify the horizontal and the vertical border;\na single number specifies the same border all the way around the element.\nSee \\fBIMAGE STRETCHING\\fR, below.\n.\\\" OPTION: -height\n.TP\n\\fB\\-height \\fIheight\\fR\n.\nSpecifies a minimum height for the element.\nIf negative, the base image's height is used as a default.\n.\\\" OPTION: -padding\n.TP\n\\fB\\-padding\\fI padding\\fR\n.\nSpecifies the element's interior padding.\nThe padding is a list of up to four length specifications\n\\fIleft top right bottom\\fR.\nIf fewer than four elements are specified,\n\\fIbottom\\fR defaults to \\fItop\\fR,\n\\fIright\\fR defaults to \\fIleft\\fR, and\n\\fItop\\fR defaults to \\fIleft\\fR.\nIn other words, a list of three numbers specify the left, vertical, and right\npadding; a list of two numbers specify the horizontal and the vertical padding;\na single number specifies the same padding all the way around the widget.\nDefaults to \\fB\\-border\\fR if not specified.\n.\\\" OPTION: -sticky\n.TP\n\\fB\\-sticky\\fI spec\\fR\n.\nSpecifies how the image is placed within the final parcel.\n\\fIspec\\fR contains zero or more characters\n.QW n ,\n.QW s ,\n.QW w ,\nor\n.QW e .\n.\\\" OPTION: -width\n.TP\n\\fB\\-width \\fIwidth\\fR\n.\nSpecifies a minimum width for the element.\nIf negative, the base image's width is used as a default.\n.SH \"IMAGE STRETCHING\"\n.PP\nIf the element's allocated parcel is larger than the image,\nthe image will be placed in the parcel based on the \\fB\\-sticky\\fR option.\nIf the image needs to stretch horizontally (i.e., \\fB\\-sticky ew\\fR)\nor vertically (\\fB\\-sticky ns\\fR),\nsubregions of the image are replicated to fill the parcel\nbased on the \\fB\\-border\\fR option.\nThe \\fB\\-border\\fR divides the image into 9 regions:\nfour fixed corners, top and left edges (which may be tiled horizontally),\nleft and right edges (which may be tiled vertically),\nand the central area (which may be tiled in both directions).\n.PP\nAn image element that is not meant to claim any space (for example when used\nas a background image) should use \\fB\\-width 0\\fR and \\fB\\-height 0\\fR.\n.SH \"EXAMPLE\"\n.PP\n.CS\nset img1 [image create photo -file button.png]\nset img2 [image create photo -file button-pressed.png]\nset img3 [image create photo -file button-active.png]\nttk::style element create Button.button image \\e\n [list $img1 pressed $img2 active $img3] \\e\n -border {2 4} -sticky we\n.CE\n.SH \"SEE ALSO\"\nttk::intro(n), ttk::style(n), ttk_vsapi(n), image(n), photo(n)\n.SH KEYWORDS\nstyle, theme, appearance, pixmap theme, image\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_intro.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::intro n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::intro \\- Introduction to the Tk theme engine\n.BE\n.SH \"OVERVIEW\"\n.PP\nThe Tk themed widget set is based on a revised and enhanced version\nof TIP #48 (https://tip.tcl-lang.org/48) specified style engine.\nThe main concepts are described below.\nThe basic idea is to separate, to the extent possible,\nthe code implementing a widget's behavior from\nthe code implementing its appearance.\nWidget class bindings are primarily responsible for\nmaintaining the widget state and invoking callbacks;\nall aspects of the widget's appearance are controlled by the style of\nthe widget (i.e. the style of the elements of the widget).\n.SH \"THEMES\"\n.PP\nA \\fItheme\\fR is a collection of elements and styles\nthat determine the look and feel of the widget set.\nThemes can be used to:\n.IP \\(bu\nisolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...)\n.IP \\(bu\nadapt to display limitations (low-color, grayscale, monochrome, tiny screens)\n.IP \\(bu\naccessibility (high contrast, large type)\n.IP \\(bu\napplication suite branding\n.IP \\(bu\nblend in with the rest of the desktop (Gnome, KDE, Java)\n.IP \\(bu\nand, of course: eye candy.\n.SH \"ELEMENTS\"\n.PP\nAn \\fIelement\\fR displays an individual part of a widget.\nFor example, a vertical scrollbar widget contains \\fBuparrow\\fR,\n\\fBdownarrow\\fR, \\fBtrough\\fR and \\fBslider\\fR elements.\n.PP\nElement names use a recursive dotted notation.\nFor example, \\fBuparrow\\fR identifies a generic arrow element,\nand \\fBScrollbar.uparrow\\fR and \\fBCombobox.uparrow\\fR identify\nwidget-specific elements.\nWhen looking for an element, the style engine looks for\nthe specific name first, and if an element of that name is\nnot found it looks for generic elements by stripping off\nsuccessive leading components of the element name.\n.PP\nLike widgets, elements have \\fIoptions\\fR which\nspecify what to display and how to display it.\nFor example, the \\fBtext\\fR element\n(which displays a text string) has\n\\fB\\-text\\fR, \\fB\\-font\\fR, \\fB\\-foreground\\fR, \\fB\\-background\\fR,\n\\fB\\-underline\\fR, and \\fB\\-width\\fR options.\nThe value of an element option is taken from (in precedence order):\n.IP \\(bu\nan option of the same name and type in the widget containing the element;\n.IP \\(bu\na dynamic setting specified by \\fBstyle map\\fR and the current state;\n.IP \\(bu\nthe default setting specified by \\fBstyle configure\\fR; or\n.IP \\(bu\nthe element's built-in default value for the option.\n.SH \"LAYOUTS\"\n.PP\nA \\fIlayout\\fR specifies which elements make up a widget\nand how they are arranged.\nThe layout engine uses a simplified version of the \\fBpack\\fR\nalgorithm: starting with an initial cavity equal to the size\nof the widget, elements are allocated a parcel within the cavity along\nthe side specified by the \\fB\\-side\\fR option,\nand placed within the parcel according to the \\fB\\-sticky\\fR\noption.\nFor example, the layout for a horizontal scrollbar is:\n.PP\n.CS\nttk::\\fBstyle layout\\fR Horizontal.TScrollbar {\n Scrollbar.trough -children {\n\tScrollbar.leftarrow -side left -sticky w\n\tScrollbar.rightarrow -side right -sticky e\n\tScrollbar.thumb -sticky ew\n }\n}\n.CE\n.PP\nBy default, the layout for a widget is the same as its class name.\nSome widgets may override this (for example, the \\fBttk::scrollbar\\fR\nwidget chooses different layouts based on the \\fB\\-orient\\fR option).\n.SH \"STATES\"\n.PP\nIn standard Tk, many widgets have a \\fB\\-state\\fR option\nwhich (in most cases) is either \\fBnormal\\fR or \\fBdisabled\\fR.\nSome widgets support additional states, such\nas the \\fBentry\\fR widget which has a \\fBreadonly\\fR state\nand the various flavors of buttons which have \\fBactive\\fR state.\n.PP\nThe themed Tk widgets generalizes this idea:\nevery widget has a bitmap of independent state flags.\nWidget state flags include \\fBactive\\fR, \\fBdisabled\\fR,\n\\fBpressed\\fR, \\fBfocus\\fR, etc.,\n(see \\fIttk::widget(n)\\fR for the full list of state flags).\n.PP\nInstead of a \\fB\\-state\\fR option, every widget now has\na \\fBstate\\fR widget command which is used to set or query\nthe state.\nA \\fIstate specification\\fR is a list of symbolic state names\nindicating which bits are set, each optionally prefixed with an\nexclamation point indicating that the bit is cleared instead.\n.PP\nFor example, the class bindings for the \\fBttk::button\\fR\nwidget are:\n.PP\n.CS\nbind TButton \t\t{ %W state active }\nbind TButton \t\t{ %W state !active }\nbind TButton \t\t{ %W state pressed }\nbind TButton \t{ %W state !pressed }\nbind TButton \t{ %W state pressed }\nbind TButton \t\\e\n { %W instate {pressed} { %W state !pressed ; %W invoke } }\n.CE\n.PP\nThis specifies that the widget becomes \\fBactive\\fR when\nthe pointer enters the widget, and inactive when it leaves.\nSimilarly it becomes \\fBpressed\\fR when the mouse button is pressed,\nand \\fB!pressed\\fR on the ButtonRelease event.\nIn addition, the button unpresses if\npointer is dragged outside the widget while Button-1 is held down,\nand represses if it's dragged back in.\nFinally, when the mouse button is released, the widget's\n\\fB\\-command\\fR is invoked, but only if the button is currently\nin the \\fBpressed\\fR state.\n(The actual bindings are a little more complicated than the above,\nbut not by much).\n'\\\" Note to self: rewrite that paragraph. It's horrible.\n.SH \"STYLES\"\n.PP\nEach widget is associated with a \\fIstyle\\fR,\nwhich specifies values for element options.\nStyle names use a recursive dotted notation like layouts and elements;\nby default, widgets use the class name to look up a style in the current theme.\nFor example:\n.PP\n.CS\nttk::\\fBstyle configure\\fR TButton \\e\n\t-background #d9d9d9 \\e\n\t-foreground black \\e\n\t-relief raised \\e\n\t;\n.CE\n.PP\nMany elements are displayed differently depending on the widget state.\nFor example, buttons have a different background when they are active,\na different foreground when disabled, and a different relief when pressed.\nThe \\fBstyle map\\fR command specifies dynamic option settings\nfor a particular style:\n.PP\n.CS\nttk::\\fBstyle map\\fR TButton \\e\n\t-background [list disabled #d9d9d9 active #ececec] \\e\n\t-foreground [list disabled #a3a3a3] \\e\n\t-relief [list {pressed !disabled} sunken] \\e\n\t;\n.CE\n.SH \"SEE ALSO\"\nttk::widget(n), ttk::style(n)\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_label.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::label n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::label \\- Display a text string and/or image\n.SH SYNOPSIS\n\\fBttk::label\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::label\\fR widget displays a textual label and/or image.\nThe label may be linked to a Tcl variable\nto automatically change the displayed text.\n.SO ttk_widget\n\\-anchor\t\\-class\t\\-compound\n\\-cursor\t\\-font\t\\-foreground\n\\-image\t\\-justify\t\\-padding\n\\-state\t\\-style\t\\-takefocus\n\\-text\t\\-textvariable\t\\-underline\n\\-width\t\\-wraplength\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-background frameColor FrameColor\nThe widget's background color.\nIf unspecified, the theme default is used.\n.OP \\-relief relief Relief\n.\\\" Rewrite this:\nSpecifies the 3-D effect desired for the widget border.\nValid values are\n\\fBflat\\fR, \\fBgroove\\fR, \\fBraised\\fR, \\fBridge\\fR, \\fBsolid\\fR,\nand \\fBsunken\\fR.\n.OP \\-wraplength wrapLength WrapLength\nSpecifies the maximum line length (in pixels).\nIf this option is negative or zero,\nthen automatic wrapping is not performed; otherwise\nthe text is split into lines such that no line is longer\nthan the specified value.\n.SH \"WIDGET COMMAND\"\n.PP\nLabel widgets support the standard commands\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\n(see \\fBttk::widget\\fR).\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::label\\fP is \\fBTLabel\\fP.\n.PP\nDynamic states: \\fBdisabled\\fP, \\fBreadonly\\fP.\n.PP\n\\fBTLabel\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-compound\\fP \\fIcompound\\fP\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-font\\fP \\fIfont\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), label(n)\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_labelframe.n", "content": "'\\\"\n'\\\" Copyright (c) 2005 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::labelframe n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::labelframe \\- Container widget with optional label\n.SH SYNOPSIS\n\\fBttk::labelframe\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::labelframe\\fR widget is a container used to group other widgets\ntogether. It has an optional label, which may be a plain text string or\nanother widget.\n.SO ttk_widget\n\\-class\t\\-cursor\t\\-padding\n\\-style\t\\-takefocus\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.\\\" XXX: Currently included, but may go away:\n.\\\" XXX: .OP -borderwidth borderWidth BorderWidth\n.\\\" XXX: The desired width of the widget border. Default is theme-dependent.\n.\\\" XXX: .OP -relief relief Relief\n.\\\" XXX: One of the standard Tk border styles:\n.\\\" XXX: \\fBflat\\fR, \\fBgroove\\fR, \\fBraised\\fR, \\fBridge\\fR,\n.\\\" XXX: \\fBsolid\\fR, or \\fBsunken\\fR.\n.\\\" XXX: Default is theme-dependent.\n.OP \\-height height Height\nIf specified, the widget's requested height in pixels.\n(See \\fIttk::frame(n)\\fR for further notes on \\fB\\-width\\fR and\n\\fB\\-height\\fR).\n.OP \\-labelanchor labelAnchor LabelAnchor\nSpecifies where to place the label.\nAllowed values are (clockwise from the top upper left corner):\n\\fBnw\\fR, \\fBn\\fR, \\fBne\\fR, \\fBen\\fR, \\fBe\\fR, \\fBes\\fR,\n\\fBse\\fR, \\fBs\\fR,\\fBsw\\fR, \\fBws\\fR, \\fBw\\fR and \\fBwn\\fR.\nThe default value is theme-dependent.\n.\\\" Alternate explanation: The first character must be one of n, s, e, or w\n.\\\" and specifies which side the label should be placed on;\n.\\\" the remaining characters specify how the label is aligned on that side.\n.\\\" NOTE: Now allows other values as well; leave this undocumented for now\n.OP \\-labelwidget labelWidget LabelWidget\nThe name of a widget to use for the label.\nIf set, overrides the \\fB\\-text\\fR option.\nThe \\fB\\-labelwidget\\fR must be a child of the \\fBlabelframe\\fR widget\nor one of the \\fBlabelframe\\fR's ancestors, and must belong to the\nsame top-level widget as the \\fBlabelframe\\fR.\n.OP \\-text text Text\nSpecifies the text of the label.\n.OP \\-underline underline Underline\nIf set, specifies the integer index (0-based) of a character to\nunderline in the text string.\nThe underlined character is used for mnemonic activation.\nMnemonic activation for a \\fBttk::labelframe\\fR\nsets the keyboard focus to the first child of the \\fBttk::labelframe\\fR widget.\n.OP \\-width width Width\nIf specified, the widget's requested width in pixels.\n.SH \"WIDGET COMMAND\"\n.PP\nLabelframe widgets support the standard commands\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\n(see \\fBttk::widget\\fR).\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::labelframe\\fP is \\fBTLabelframe\\fP.\nThe text label\nhas a class of \\fBTLabelframe.Label\\fP.\n.PP\nDynamic states: \\fBdisabled\\fP, \\fBreadonly\\fP.\n.PP\n\\fBTLabelframe\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-bordercolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-borderwidth\\fP \\fIamount\\fP\n.br\n\\fB\\-darkcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-labelmargins\\fP \\fIamount\\fP\n.br\n\\fB\\-labeloutside\\fP \\fIboolean\\fP\n.br\n\\fB\\-lightcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-relief\\fP \\fIrelief\\fP\n.PP\n\\fBTLabelframe.Label\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-font\\fP \\fIfont\\fP\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), ttk::frame(n), labelframe(n)\n.SH \"KEYWORDS\"\nwidget, frame, container, label, groupbox\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_menubutton.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::menubutton n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::menubutton \\- Widget that pops down a menu when pressed\n.SH SYNOPSIS\n\\fBttk::menubutton\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::menubutton\\fR widget displays a textual label and/or image,\nand displays a menu when pressed.\n.SO ttk_widget\n\\-class\t\\-compound\t\\-cursor\n\\-image\t\\-state\t\\-style\n\\-takefocus\t\\-text\t\\-textvariable\n\\-underline\t\\-width\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-direction direction Direction\nSpecifies where the menu is to be popped up relative\nto the menubutton.\nOne of: \\fBabove\\fR, \\fBbelow\\fR, \\fBleft\\fR, \\fBright\\fR,\nor \\fBflush\\fR. The default is \\fBbelow\\fR.\n\\fBflush\\fR pops the menu up directly over the menubutton.\n.OP \\-menu menu Menu\nSpecifies the path name of the menu associated with the menubutton.\nTo be on the safe side, the menu ought to be a direct child of the\nmenubutton.\n.\\\" not documented: may go away:\n.\\\" .OP \\-anchor anchor Anchor\n.\\\" .OP \\-padding padding Pad\n.SH \"WIDGET COMMAND\"\n.PP\nMenubutton widgets support the standard commands\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\n(see \\fBttk::widget\\fR).\n.SH \"STANDARD STYLES\"\n.PP\n\\fBTtk::menubutton\\fR widgets support the \\fBToolbutton\\fR style in all\nstandard themes, which is useful for creating widgets for toolbars.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::menubutton\\fP is \\fBTMenubutton\\fP.\n.PP\nDynamic states: \\fBactive\\fP, \\fBdisabled\\fP, \\fBreadonly\\fP.\n.PP\n\\fBTMenubutton\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-arrowsize\\fP \\fIamount\\fP\n.br\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-compound\\fP \\fIcompound\\fP\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-font\\fP \\fIfont\\fP\n.br\n\\fB\\-padding\\fP \\fIpadding\\fP\n.br\n\\fB\\-relief\\fP \\fIrelief\\fP\n.br\n\\fB\\-width\\fP \\fIamount\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), menu(n), menubutton(n)\n.SH \"KEYWORDS\"\nwidget, button, menu\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_notebook.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::notebook n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::notebook \\- Multi-paned container widget\n.SH SYNOPSIS\n.nf\n\\fBttk::notebook\\fI pathname \\fR?\\fIoptions...\\fR?\n.br\n\\fIpathname \\fBadd\\fI window\\fR ?\\fIoptions...\\fR?\n\\fIpathname \\fBinsert\\fI index window\\fR ?\\fIoptions...\\fR?\n.fi\n.BE\n.SH DESCRIPTION\nA \\fBttk::notebook\\fR widget manages a collection of windows\nand displays a single one at a time.\nEach content window is associated with a \\fItab\\fR,\nwhich the user may select to change the currently-displayed window.\n.SO ttk_widget\n\\-class\t\\-cursor\t\\-takefocus\n\\-style\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-height height Height\nIf present and greater than zero,\nspecifies the desired height of the pane area\n(not including internal padding or tabs).\nOtherwise, the maximum height of all panes is used.\n.OP \\-padding padding Padding\nSpecifies the amount of extra space to add around the outside\nof the notebook.\nThe padding is a list of up to four length specifications\n\\fIleft top right bottom\\fR.\nIf fewer than four elements are specified,\n\\fIbottom\\fR defaults to \\fItop\\fR,\n\\fIright\\fR defaults to \\fIleft\\fR, and\n\\fItop\\fR defaults to \\fIleft\\fR.\nIn other words, a list of three numbers specify the left, vertical, and right\npadding; a list of two numbers specify the horizontal and the vertical padding;\na single number specifies the same padding all the way around the widget.\n.OP \\-width width Width\nIf present and greater than zero,\nspecifies the desired width of the pane area\n(not including internal padding).\nOtherwise, the maximum width of all panes is used.\n.SH \"TAB OPTIONS\"\nThe following options may be specified for individual notebook panes:\n.OP \\-state state State\nEither \\fBnormal\\fR, \\fBdisabled\\fR or \\fBhidden\\fR.\nIf \\fBdisabled\\fR, then the tab is not selectable.\nIf \\fBhidden\\fR, then the tab is not shown.\n.OP \\-sticky sticky Sticky\nSpecifies how the content window is positioned within the pane area.\nValue is a string containing zero or more of the characters\n\\fBn, s, e,\\fR or \\fBw\\fR.\nEach letter refers to a side (north, south, east, or west)\nthat the content window will\n.QW stick\nto, as per the \\fBgrid\\fR geometry manager.\n.OP \\-padding padding Padding\nSpecifies the amount of extra space to add between the notebook and this pane.\nSyntax is the same as for the widget \\fB\\-padding\\fR option.\n.OP \\-text text Text\nSpecifies a string to be displayed in the tab.\n.OP \\-image image Image\nSpecifies an image to display in the tab.\nSee \\fIttk_widget(n)\\fR for details.\n.OP \\-compound compound Compound\nSpecifies how to display the image relative to the text,\nin the case both \\fB\\-text\\fR and \\fB\\-image\\fR are present.\nSee \\fIlabel(n)\\fR for legal values.\n.OP \\-underline underline Underline\nSpecifies the integer index (0-based) of a character to underline\nin the text string.\nThe underlined character is used for mnemonic activation\nif \\fBttk::notebook::enableTraversal\\fR is called.\n.SH \"TAB IDENTIFIERS\"\nThe \\fItabid\\fR argument to the following commands may take\nany of the following forms:\n.IP \\(bu\nAn integer between zero and the number of tabs;\n.IP \\(bu\nThe name of a content window;\n.IP \\(bu\nA positional specification of the form\n.QW @\\fIx\\fR,\\fIy\\fR ,\nwhich identifies the tab\n.IP \\(bu\nThe literal string\n.QW \\fBcurrent\\fR ,\nwhich identifies the currently-selected tab; or:\n.IP \\(bu\nThe literal string\n.QW \\fBend\\fR ,\nwhich returns the number of tabs\n(only valid for\n.QW \"\\fIpathname \\fBindex\\fR\" ).\n.PP\nIndexes support the same simple interpretation as\nfor the command \\fBstring index\\fR, with simple integer index\narithmetic and indexing relative to \\fBend\\fR.\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\ncommands (see \\fBttk::widget\\fR),\nnotebook widgets support the following additional commands:\n.\\\" METHOD: add\n.TP\n\\fIpathname \\fBadd \\fIwindow\\fR ?\\fIoptions...\\fR?\n.\nAdds a new tab to the notebook.\nSee \\fBTAB OPTIONS\\fR for the list of available \\fIoptions\\fR.\nIf \\fIwindow\\fR is currently managed by the notebook but hidden,\nit is restored to its previous position.\n.\\\" METHOD: forget\n.TP\n\\fIpathname \\fBforget \\fItabid\\fR\n.\nRemoves the tab specified by \\fItabid\\fR,\nunmaps and unmanages the associated window.\n.\\\" METHOD: hide\n.TP\n\\fIpathname \\fBhide \\fItabid\\fR\n.\nHides the tab specified by \\fItabid\\fR.\nThe tab will not be displayed, but the associated window\nremains managed by the notebook and its configuration remembered.\nHidden tabs may be restored with the \\fBadd\\fR command.\n.\\\" METHOD: identify\n.TP\n\\fIpathname \\fBidentify\\fI component x y\\fR\n.\nReturns the name of the element under the point given by \\fIx\\fR and \\fIy\\fR,\nor the empty string if no component is present at that location.\nThe following subcommands are supported:\n.RS\n.TP\n\\fIpathname \\fBidentify element\\fI x y\\fR\n.\nReturns the name of the element at the specified location.\n.TP\n\\fIpathname \\fBidentify tab\\fI x y\\fR\n.\nReturns the index of the tab at the specified location.\n.RE\n.\\\" METHOD: index\n.TP\n\\fIpathname \\fBindex \\fItabid\\fR\n.\nReturns the numeric index of the tab specified by \\fItabid\\fR,\nor the total number of tabs if \\fItabid\\fR is the string\n.QW \\fBend\\fR .\n.\\\" METHOD: insert\n.TP\n\\fIpathname \\fBinsert \\fIpos subwindow options...\\fR\n.\nInserts a pane at the specified position.\n\\fIpos\\fR is either the string \\fBend\\fR, an integer index,\nor the name of a managed subwindow.\nIf \\fIsubwindow\\fR is already managed by the notebook,\nmoves it to the specified position.\nSee \\fBTAB OPTIONS\\fR for the list of available options.\n.\\\" METHOD: select\n.TP\n\\fIpathname \\fBselect\\fR ?\\fItabid\\fR?\n.\nSelects the specified tab.\nThe associated content window will be displayed,\nand the previously-selected window (if different) is unmapped.\nIf \\fItabid\\fR is omitted, returns the widget name of the\ncurrently selected pane.\n.\\\" METHOD: tab\n.TP\n\\fIpathname \\fBtab \\fItabid\\fR ?\\fI\\-option \\fR?\\fIvalue ...\\fR\n.\nQuery or modify the options of the specific tab.\nIf no \\fI\\-option\\fR is specified,\nreturns a dictionary of the tab option values.\nIf one \\fI\\-option\\fR is specified,\nreturns the value of that \\fIoption\\fR.\nOtherwise, sets the \\fI\\-option\\fRs to the corresponding \\fIvalue\\fRs.\nSee \\fBTAB OPTIONS\\fR for the available options.\n.\\\" METHOD: tabs\n.TP\n\\fIpathname \\fBtabs\\fR\n.\nReturns the list of windows managed by the notebook, in the index order of\ntheir associated tabs.\n.SH \"KEYBOARD TRAVERSAL\"\nTo enable keyboard traversal for a toplevel window\ncontaining a notebook widget \\fI$nb\\fR, call:\n.CS\nttk::notebook::enableTraversal $nb\n.CE\n.PP\nThis will extend the bindings for the toplevel window\ncontaining the notebook as follows:\n.IP \\(bu\n\\fBControl-Tab\\fR selects the tab following the currently selected one.\n.IP \\(bu\n\\fBControl-Shift-Tab\\fR selects the tab preceding the currently selected one.\n.IP \\(bu\n\\fBAlt-\\fIK\\fR, where \\fIK\\fR is the mnemonic (underlined) character\nof any tab, will select that tab.\n.PP\nMultiple notebooks in a single toplevel may be enabled for traversal,\nincluding nested notebooks.\nHowever, notebook traversal only works properly if all panes\nare direct children of the notebook.\n.SH \"VIRTUAL EVENTS\"\nThe notebook widget generates a \\fB<>\\fR\nvirtual event after a new tab is selected.\n.SH \"EXAMPLE\"\n.CS\npack [\\fBttk::notebook\\fR .nb]\n\\&.nb add [frame .nb.f1] -text \"First tab\"\n\\&.nb add [frame .nb.f2] -text \"Second tab\"\n\\&.nb select .nb.f2\nttk::notebook::enableTraversal .nb\n.CE\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::notebook\\fP is \\fBTNotebook\\fP. The tab has\na class name of \\fBTNotebook.Tab\\fP\n.PP\nDynamic states: \\fBactive\\fP, \\fBdisabled\\fP, \\fBselected\\fP.\n.PP\n\\fBTNotebook\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-bordercolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-darkcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-lightcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-padding\\fP \\fIpadding\\fP\n.br\n\\fB\\-tabmargins\\fP \\fIpadding\\fP\n.br\n\\fB\\-tabposition\\fP \\fIposition\\fP\n.RS\nSpecifies the position of the tab row or column as a string of length\n1 or 2. The first character indicates the side as \\fBn\\fP, \\fBs\\fP,\n\\fBw\\fP, or \\fBe\\fP, while the second character (if present) is the\nsticky bit (specified as \\fBw\\fP, \\fBe\\fP, \\fBn\\fP, or \\fBs\\fP) within\nthe tab position. The default position is \\fBn\\fP for the \\fBaqua\\fP\ntheme and \\fBnw\\fP for all the other built-in themes.\n.RE\n.br\n\\fB\\-tabplacement\\fP \\fIplacement\\fP\n.RS\nSpecifies the placement (anchor) of the tabs within the tab row or column\nas a string of length 1 or 2. The first character indicates the side as\n\\fBw\\fP, \\fBe\\fP, \\fBn\\fP, or \\fBs\\fP, while the second character (if\npresent) is the sticky bit (specified as \\fBs\\fP, \\fBn\\fP, \\fBe\\fP, or\n\\fBw\\fP) within the tab placement. For example, the tab placement \\fBws\\fP\nmeans: attach the west (left) side of each tab to the previous one and\nalign the south (bottom) edges with each other. Similarly, the tab\nplacement \\fBse\\fP specifies to attach the south (bottom) side of each tab\nto the previous one and align the east (right) edges with each other. The\ndefault placement depends on the first character of the tab position:\n\\fBws\\fP for \\fBn*\\fP, \\fBwn\\fP for \\fBs*\\fP, \\fBne\\fP for \\fBw*\\fP, and \n\\fBnw\\fP for \\fBe*\\fP.\n.RE\n.br\n.PP\n\\fBTNotebook.Tab\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-bordercolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-compound\\fP \\fIcompound\\fP\n.br\n\\fB\\-expand\\fP \\fIpadding\\fP\n.RS\nDefines how much the tab grows in size. Usually used with the\n\\fBselected\\fP dynamic state. \\fB\\-tabmargins\\fP should be\nset appropriately so that there is room for the tab growth.\nFor example, the Ttk library file \\fBvistaTheme.tcl\\fP contains\nthe lines\n.CS\nttk::style configure TNotebook -tabmargins {2 2 2 0}\nttk::style map TNotebook.Tab -expand {selected {2 2 2 2}}\n.CE\nwhich are valid for the default value \\fBnw\\fP of the \\fB\\-tabposition\\fP\nstyle option. For a \\fBttk::notebook\\fP style \\fBnbStyle\\fP defined by\n.CS\nset nbStyle SW.TNotebook\nttk::style configure $nbStyle -tabposition sw\n.CE\nyou will have to adapt the above settings as follows:\n.CS\nttk::style configure $nbStyle -tabmargins {2 0 2 2}\nttk::style map $nbStyle.Tab -expand {selected {2 2 2 2}}\n.CE\nThe easiest way to do this is to invoke the library procedure\n\\fBttk::configureNotebookStyle\\fP with \\fB$nbStyle\\fP as argument, after\nsetting the style's \\fB\\-tabposition\\fP option.\n.RE\n\\fB\\-font\\fP \\fIfont\\fP\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-padding\\fP \\fIpadding\\fP\n.RS\nSome themes use a different \\fIpadding\\fP for the selected tab. For example,\nthe Ttk library file \\fBclamTheme.tcl\\fP contains the lines\n.CS\nttk::style configure TNotebook.Tab \\\\\n -padding {4.5p 1.5p 4.5p 1.5p}\nttk::style map TNotebook.Tab \\\\\n -padding {selected {4.5p 3p 4.5p 1.5p}}\n.CE\nwhich are valid for the default value \\fBnw\\fP of the \\fB\\-tabposition\\fP\nstyle option. For a \\fBttk::notebook\\fP style having a different tab position\nyou will have to adapt the above settings accordingly. Again, the easiest way\nto do this is to invoke the library procedure \\fBttk::configureNotebookStyle\\fP\nwith the style name as argument, after setting the style's \\fB\\-tabposition\\fP\noption.\n.RE\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), grid(n)\n.SH \"KEYWORDS\"\npane, tab\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_panedwindow.n", "content": "'\\\"\n'\\\" Copyright (c) 2005 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::panedwindow n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::panedwindow \\- Multi-pane container window\n.SH SYNOPSIS\n.nf\n\\fBttk::panedwindow\\fI pathname \\fR?\\fIoptions\\fR?\n.br\n\\fIpathname \\fBadd\\fI window\\fR ?\\fIoptions...\\fR?\n\\fIpathname \\fBinsert\\fI index window\\fR ?\\fIoptions...\\fR?\n.fi\n.BE\n.SH DESCRIPTION\nA \\fBttk::panedwindow\\fR widget displays a number of subwindows,\nstacked either vertically or horizontally.\nThe user may adjust the relative sizes of the subwindows\nby dragging the sash between panes.\n.SO ttk_widget\n\\-class\t\\-cursor\t\\-takefocus\n\\-style\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-orient orient Orient\nSpecifies the orientation of the window.\nIf \\fBvertical\\fR, subpanes are stacked top-to-bottom;\nif \\fBhorizontal\\fR, subpanes are stacked left-to-right.\n.OP \\-width width Width\nIf present and greater than zero,\nspecifies the desired width of the widget in pixels.\nOtherwise, the requested width is determined by the width\nof the managed windows.\n.OP \\-height height Height\nIf present and greater than zero,\nspecifies the desired height of the widget in pixels.\nOtherwise, the requested height is determined by the height\nof the managed windows.\n.SH \"PANE OPTIONS\"\nThe following options may be specified for each pane:\n.OP \\-weight weight Weight\nAn integer specifying the relative stretchability of the pane.\nWhen the paned window is resized, the extra space is added\nor subtracted to each pane proportionally to its \\fB\\-weight\\fR.\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\ncommands (see \\fBttk::widget\\fR),\npanedwindow widgets support the following additional commands:\n.\\\" METHOD: add\n.TP\n\\fIpathname \\fBadd \\fIsubwindow options...\\fR\n.\nAdds a new pane to the window.\nSee \\fBPANE OPTIONS\\fR for the list of available options.\n.\\\" METHOD: forget\n.TP\n\\fIpathname \\fBforget \\fIpane\\fR\n.\nRemoves the specified subpane from the widget.\n\\fIpane\\fR is either an integer index or the name of a managed subwindow.\n.\\\" METHOD: identify\n.TP\n\\fIpathname \\fBidentify \\fIcomponent x y\\fR\n.\nReturns the name of the element under the point given by \\fIx\\fR and \\fIy\\fR,\nor the empty string if no component is present at that location.\nIf \\fIcomponent\\fR is omitted, it defaults to \\fBsash\\fR.\nThe following subcommands are supported:\n.RS\n.TP\n\\fIpathname \\fBidentify element \\fIx y\\fR\n.\nReturns the name of the element at the specified location.\n.TP\n\\fIpathname \\fBidentify sash \\fIx y\\fR\n.\nReturns the index of the sash at the specified location.\n.RE\n.\\\" METHOD: insert\n.TP\n\\fIpathname \\fBinsert \\fIpos subwindow options...\\fR\n.\nInserts a pane at the specified position.\n\\fIpos\\fR is either the string \\fBend\\fR, an integer index,\nor the name of a managed subwindow.\nIf \\fIsubwindow\\fR is already managed by the paned window,\nmoves it to the specified position.\nSee \\fBPANE OPTIONS\\fR for the list of available options.\n.\\\" METHOD: pane\n.TP\n\\fIpathname \\fBpane \\fIpane \\-option \\fR?\\fIvalue \\fR?\\fI\\-option value...\\fR\n.\nQuery or modify the options of the specified \\fIpane\\fR,\nwhere \\fIpane\\fR is either an integer index or the name of a managed subwindow.\nIf no \\fI\\-option\\fR is specified, returns a dictionary of the pane\noption values.\nIf one \\fI\\-option\\fR is specified, returns the value of that \\fIoption\\fR.\nOtherwise, sets the \\fI\\-option\\fRs to the corresponding \\fIvalue\\fRs.\n.\\\" METHOD: panes\n.TP\n\\fIpathname \\fBpanes\\fR\n.\nReturns the list of all windows managed by the widget, in the index order of\ntheir associated panes.\n.\\\" METHOD: sashpos\n.TP\n\\fIpathname \\fBsashpos \\fIindex\\fR ?\\fInewpos\\fR?\n.\nIf \\fInewpos\\fR is specified, sets the position\nof sash number \\fIindex\\fR.\nMay adjust the positions of adjacent sashes\nto ensure that positions are monotonically increasing.\nSash positions are further constrained to be between 0\nand the total size of the widget.\n.\\\" Full story: \"total size\" is either the -height (resp -width),\n.\\\" or the actual window height (resp actual window width),\n.\\\" depending on which changed most recently.\nReturns the new position of sash number \\fIindex\\fR.\n.\\\" Full story: new position may be different than the requested position.\n.SH \"VIRTUAL EVENTS\"\n.PP\nThe panedwindow widget generates an \\fB<>\\fR virtual event on\nLeaveNotify/NotifyInferior events.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::panedwindow\\fP is \\fBTPanedwindow\\fP. The\nsash has a class name of \\fBSash\\fP.\n.PP\n\\fBTPanedwindow\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.PP\n\\fBSash\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-bordercolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-gripsize\\fP \\fIsize\\fP (number of screen units)\n.br\n\\fB\\-handlepad\\fP \\fIamount\\fP\n.br\n\\fB\\-handlesize\\fP \\fIamount\\fP\n.br\n\\fB\\-lightcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-sashpad\\fP \\fIamount\\fP\n.br\n\\fB\\-sashrelief\\fP \\fIrelief\\fP\n.br\n\\fB\\-sashthickness\\fP \\fIamount\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), ttk::notebook(n), panedwindow(n)\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_progressbar.n", "content": "'\\\"\n'\\\" Copyright (c) 2005 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::progressbar n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::progressbar \\- Provide progress feedback\n.SH SYNOPSIS\n\\fBttk::progressbar\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::progressbar\\fR widget shows the status of a long-running\noperation. They can operate in two modes: \\fIdeterminate\\fR mode shows the\namount completed relative to the total amount of work to be done, and\n\\fIindeterminate\\fR mode provides an animated display to let the user know\nthat something is happening.\n.PP\nIf the value of \\fB\\-orient\\fR is \\fBhorizontal\\fR a text string can be\ndisplayed inside the progressbar. This string can be configured using\nthe \\fB\\-anchor\\fR, \\fB\\-font\\fR, \\fB\\-foreground\\fR, \\fB\\-justify\\fR,\n\\fB\\-text\\fR and \\fB\\-wraplength\\fR options. If the value of \\fB\\-orient\\fR\nis \\fBvertical\\fR then these options are ignored.\n.SO ttk_widget\n\\-anchor\t\\-class\t\\-cursor\n\\-font\t\\-foreground\t\\-justify\t\\-style\n\\-takefocus\t\\-text\t\\-wraplength\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-length length Length\nSpecifies the length of the long axis of the progress bar\n(width if horizontal, height if vertical). The value may have any of the forms\nacceptable to \\fBTk_GetPixels\\fR.\n.OP \\-maximum maximum Maximum\nA floating point number specifying the maximum \\fB\\-value\\fR.\nDefaults to 100.\n.OP \\-mode mode Mode\nOne of \\fBdeterminate\\fR or \\fBindeterminate\\fR.\n.OP \\-orient orient Orient\nOne of \\fBhorizontal\\fR or \\fBvertical\\fR.\nSpecifies the orientation of the progress bar.\n.OP \\-phase phase Phase\nRead-only option.\nThe widget periodically increments the value of this option\nwhenever the \\fB\\-value\\fR is greater than 0 and,\nin \\fIdeterminate\\fR mode, less than \\fB\\-maximum\\fR.\nThis option may be used by the current theme\nto provide additional animation effects.\n.OP \\-value value Value\nThe current value of the progress bar.\nIn \\fIdeterminate\\fR mode, this represents the amount of work completed.\nIn \\fIindeterminate\\fR mode, it is interpreted modulo \\fB\\-maximum\\fR;\nthat is, the progress bar completes one\n.QW cycle\nwhen the \\fB\\-value\\fR increases by \\fB\\-maximum\\fR.\nIf \\fB\\-variable\\fR is set to an existing variable, specifying \\fB\\-value\\fR\nhas no effect (the variable value takes precedence).\n.OP \\-variable variable Variable\nThe name of a global Tcl variable which is linked to the \\fB\\-value\\fR.\nIf specified to an existing variable, the \\fB\\-value\\fR of the progress bar is\nautomatically set to the value of the variable whenever\nthe latter is modified.\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\ncommands (see \\fBttk::widget\\fR),\nprogressbar widgets support the following additional commands:\n.\\\" METHOD: start\n.TP\n\\fIpathName \\fBstart\\fR ?\\fIinterval\\fR?\n.\nBegin autoincrement mode:\nschedules a recurring timer event that calls \\fBstep\\fR\nevery \\fIinterval\\fR milliseconds.\nIf omitted, \\fIinterval\\fR defaults to 50 milliseconds (20 steps/second).\n.\\\" METHOD: step\n.TP\n\\fIpathName \\fBstep\\fR ?\\fIamount\\fR?\n.\nIncrements the \\fB\\-value\\fR by \\fIamount\\fR.\n\\fIamount\\fR defaults to 1.0 if omitted.\n.\\\" METHOD: stop\n.TP\n\\fIpathName \\fBstop\\fR\n.\nStop autoincrement mode:\ncancels any recurring timer event initiated by \\fIpathName \\fBstart\\fR.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::progressbar\\fP is \\fBTProgressbar\\fP.\n.PP\n\\fBTProgressbar\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-bordercolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-darkcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-lightcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-maxphase\\fP\n.RS\nFor the aqua theme.\n.RE\n\\fB\\-period\\fP\n.RS\nFor the aqua theme.\n.RE\n\\fB\\-troughcolor\\fP \\fIcolor\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n)\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_radiobutton.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::radiobutton n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::radiobutton \\- Mutually exclusive option widget\n.SH SYNOPSIS\n\\fBttk::radiobutton\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\n\\fBttk::radiobutton\\fR widgets are used in groups to show or change\na set of mutually-exclusive options.\nRadiobuttons are linked to a Tcl variable,\nand have an associated value; when a radiobutton is clicked,\nit sets the variable to its associated value.\n.SO ttk_widget\n\\-class\t\\-compound\t\\-cursor\n\\-image\t\\-state\t\\-style\n\\-takefocus\t\\-text\t\\-textvariable\n\\-underline\t\\-width\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-command command Command\nA Tcl script to evaluate whenever the widget is invoked.\n.OP \\-value Value Value\nThe value to store in the associated \\fB\\-variable\\fR\nwhen the widget is selected.\n.OP \\-variable variable Variable\nThe name of a global variable whose value is linked to the widget.\nDefault value is \\fB::selectedButton\\fR.\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\ncommands (see \\fBttk::widget\\fR),\nradiobutton widgets support the following additional commands:\n.\\\" METHOD: invoke\n.TP\n\\fIpathname\\fB invoke\\fR\n.\nSets the \\fB\\-variable\\fR to the \\fB\\-value\\fR, selects the widget,\nand evaluates the associated \\fB\\-command\\fR.\nReturns the result of the \\fB\\-command\\fR, or the empty\nstring if no \\fB\\-command\\fR is specified.\n.\\\" Missing: select, deselect. Useful?\n.\\\" Missing: flash. This is definitely not useful.\n.SH \"WIDGET STATES\"\n.PP\nThe widget does not respond to user input if the \\fBdisabled\\fR state is set.\nThe widget sets the \\fBselected\\fR state whenever\nthe linked \\fB\\-variable\\fR is set to the widget's \\fB\\-value\\fR,\nand clears it otherwise.\nThe widget sets the \\fBalternate\\fR state whenever the\nlinked \\fB\\-variable\\fR is unset.\n(The \\fBalternate\\fR state may be used to indicate a\n.QW tri-state\nor\n.QW indeterminate\nselection.)\n.SH \"STANDARD STYLES\"\n.PP\n\\fBTtk::radiobutton\\fR widgets support the \\fBToolbutton\\fR style in all\nstandard themes, which is useful for creating widgets for toolbars.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::radiobutton\\fP is \\fBTRadiobutton\\fP.\n.PP\nDynamic states: \\fBactive\\fP, \\fBalternate\\fP, \\fBdisabled\\fP,\n\\fBpressed\\fP, \\fBreadonly\\fP, \\fBselected\\fP.\n.PP\n\\fBTRadiobutton\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-compound\\fP \\fIcompound\\fP\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-indicatorbackground\\fP \\fIcolor\\fP\n.br\n\\fB\\-indicatorcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-indicatormargin\\fP \\fIpadding\\fP\n.br\n\\fB\\-indicatorrelief\\fP \\fIrelief\\fP\n.br\n\\fB\\-padding\\fP \\fIpadding\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), ttk::checkbutton(n), radiobutton(n)\n.SH \"KEYWORDS\"\nwidget, button, option\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_scale.n", "content": ".\\\"\n.\\\" Copyright (c) 2008 Donal Fellows\n.\\\"\n.\\\" See the file \"license.terms\" for information on usage and redistribution\n.\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n.\\\"\n.TH ttk::scale n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::scale \\- Create and manipulate a scale widget\n.SH SYNOPSIS\n\\fBttk::scale \\fIpathName \\fR?\\fIoptions...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::scale\\fR widget is typically used to control the numeric value of a\nlinked variable that varies uniformly over some range. A scale displays a\n\\fIslider\\fR that can be moved along over a \\fItrough\\fR, with the relative\nposition of the slider over the trough indicating the value of the variable.\n.SO ttk_widget\n\\-class\t\\-cursor\t\\-style\n\\-takefocus\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-command command Command\nSpecifies the prefix of a Tcl command to invoke whenever the scale's value is\nchanged via a widget command. The actual command consists of this option\nfollowed by a space and a real number indicating the new value of the scale.\n.OP \\-from from From\nA real value corresponding to the left or top end of the scale.\n.OP \\-length length Length\nSpecifies the desired long dimension of the scale in screen units (i.e. any of\nthe forms acceptable to \\fBTk_GetPixels\\fR). For vertical scales this is the\nscale's height; for horizontal scales it is the scale's width.\n.OP \\-orient orient Orient\nSpecifies which orientation whether the widget should be laid out horizontally\nor vertically. Must be either \\fBhorizontal\\fR or \\fBvertical\\fR or an\nabbreviation of one of these.\n.OP \\-to to To\nSpecifies a real value corresponding to the right or bottom end of the scale.\nThis value may be either less than or greater than the \\fB\\-from\\fR option.\n.OP \\-value value Value\nSpecifies the current floating-point value of the variable.\nIf \\fB\\-variable\\fR is set to an existing variable, specifying \\fB\\-value\\fR\nhas no effect (the variable value takes precedence).\n.OP \\-variable variable Variable\nSpecifies the name of a global variable to link to the scale. Whenever the\nvalue of the variable changes, the scale will update to reflect this value.\nWhenever the scale is manipulated interactively, the variable will be modified\nto reflect the scale's new value.\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\ncommands (see \\fBttk::widget\\fR),\nscale widgets support the following additional commands:\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget \\fR?\\fIx y\\fR?\n.\nGet the current value of the \\fB\\-value\\fR option, or the value corresponding\nto the coordinates \\fIx,y\\fR if they are specified. \\fIX\\fR and \\fIy\\fR are\npixel coordinates relative to the scale widget origin.\n.\\\" METHOD: see\n.TP\n\\fIpathName \\fBset \\fIvalue\\fR\n.\nSet the value of the widget (i.e. the \\fB\\-value\\fR option) to \\fIvalue\\fR.\nThe value will be clipped to the range given by the \\fB\\-from\\fR and\n\\fB\\-to\\fR options. Note that setting the linked variable (i.e. the variable\nnamed in the \\fB\\-variable\\fR option) does not cause such clipping.\n.SH \"INTERNAL COMMANDS\"\n.PP\n.\\\" METHOD: coords\n.TP\n\\fIpathName \\fBcoords \\fR?\\fIvalue\\fR?\n.\nGet the coordinates corresponding to \\fIvalue\\fR, or the coordinates\ncorresponding to the current value of the \\fB\\-value\\fR option if \\fIvalue\\fR\nis omitted.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::scale\\fP is \\fBTScale\\fP.\n.PP\nDynamic states: \\fBactive\\fP.\n.PP\n\\fBTScale\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-borderwidth\\fP \\fIamount\\fP\n.br\n\\fB\\-darkcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-groovewidth\\fP \\fIamount\\fP\n.br\n\\fB\\-lightcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-sliderwidth\\fP \\fIamount\\fP\n.br\n\\fB\\-troughcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-troughrelief\\fP \\fIrelief\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), scale(n)\n.SH KEYWORDS\nscale, slider, trough, widget\n.\\\" Local Variables:\n.\\\" mode: nroff\n.\\\" fill-column: 78\n.\\\" End:\n" }, { "path": "doc/ttk_scrollbar.n", "content": "'\\\"\n'\\\" Copyright (c) 1994-1996 Sun Microsystems, Inc.\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::scrollbar n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::scrollbar \\- Control the viewport of a scrollable widget\n.SH SYNOPSIS\n\\fBttk::scrollbar\\fI pathName \\fR?\\fIoptions...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\n\\fBttk::scrollbar\\fR widgets are typically linked to an associated window\nthat displays a document of some sort, such as a file being edited or a\ndrawing.\nA scrollbar displays a \\fIthumb\\fR in the middle portion of the scrollbar,\nwhose position and size provides information about the portion of the\ndocument visible in the associated window.\nThe thumb may be dragged by the user to control the visible region.\nDepending on the theme, two or more arrow buttons may also be present;\nthese are used to scroll the visible region in discrete units.\n.SO ttk_widget\n\\-class\t\\-cursor\t\\-style\n\\-takefocus\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-command command Command\nA Tcl script prefix to evaluate\nto change the view in the widget associated with the scrollbar.\nAdditional arguments are appended to the value of this option,\nas described in \\fBSCROLLING COMMANDS\\fR below,\nwhenever the user requests a view change by manipulating the scrollbar.\n.RS\n.PP\nThis option typically consists of a two-element list,\ncontaining the name of a scrollable widget followed by\neither \\fBxview\\fR (for horizontal scrollbars)\nor \\fByview\\fR (for vertical scrollbars).\n.RE\n.OP \\-orient orient Orient\nOne of \\fBhorizontal\\fR or \\fBvertical\\fR.\nSpecifies the orientation of the scrollbar.\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\ncommands (see \\fBttk::widget\\fR),\nscrollbar widgets support the following additional commands:\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget\\fR\n.\nReturns the scrollbar settings in the form of a list whose\nelements are the arguments to the most recent \\fBset\\fR widget command.\n.\\\" METHOD: set\n.TP\n\\fIpathName \\fBset \\fIfirst last\\fR\n.\nThis command is normally invoked by the scrollbar's associated widget\nfrom an \\fB\\-xscrollcommand\\fR or \\fB\\-yscrollcommand\\fR callback.\nSpecifies the visible range to be displayed.\n\\fIfirst\\fR and \\fIlast\\fR are real fractions between 0 and 1.\n.SH \"INTERNAL COMMANDS\"\n.PP\nThe following widget commands are used internally\nby the \\fBTScrollbar\\fP widget class bindings.\n.\\\" METHOD: delta\n.TP\n\\fIpathName \\fBdelta \\fIdeltaX deltaY\\fR\n.\nReturns a real number indicating the fractional change in\nthe scrollbar setting that corresponds to a given change\nin thumb position. For example, if the scrollbar is horizontal,\nthe result indicates how much the scrollbar setting must change\nto move the thumb \\fIdeltaX\\fR pixels to the right (\\fIdeltaY\\fR is\nignored in this case).\nIf the scrollbar is vertical, the result indicates how much the\nscrollbar setting must change to move the thumb \\fIdeltaY\\fR pixels\ndown. The arguments and the result may be zero or negative.\n.\\\" METHOD: fraction\n.TP\n\\fIpathName \\fBfraction \\fIx y\\fR\n.\nReturns a real number between 0 and 1 indicating where the point\ngiven by \\fIx\\fR and \\fIy\\fR lies in the trough area of the scrollbar,\nwhere 0.0 corresponds to the top or left of the trough\nand 1.0 corresponds to the bottom or right.\n\\fIX\\fR and \\fIy\\fR are pixel coordinates relative to the scrollbar\nwidget.\nIf \\fIx\\fR and \\fIy\\fR refer to a point outside the trough, the closest\npoint in the trough is used.\n.SH \"SCROLLING COMMANDS\"\n.PP\nWhen the user interacts with the scrollbar, for example by dragging\nthe thumb, the scrollbar notifies the associated widget that it\nmust change its view.\nThe scrollbar makes the notification by evaluating a Tcl command\ngenerated from the scrollbar's \\fB\\-command\\fR option.\nThe command may take any of the following forms.\nIn each case, \\fIprefix\\fR is the contents of the\n\\fB\\-command\\fR option, which usually has a form like \\fB.t yview\\fR\n.TP\n\\fIprefix \\fBmoveto \\fIfraction\\fR\n.\n\\fIFraction\\fR is a real number between 0 and 1.\nThe widget should adjust its view so that the point given\nby \\fIfraction\\fR appears at the beginning of the widget.\nIf \\fIfraction\\fR is 0 it refers to the beginning of the\ndocument. 1.0 refers to the end of the document, 0.333\nrefers to a point one-third of the way through the document,\nand so on.\n.TP\n\\fIprefix \\fBscroll \\fInumber \\fBpages\\fR\n.\nThe widget should adjust its view by \\fInumber\\fR pages.\nIt is up to the widget to define the meaning of a page; typically\nit is slightly less than what fits in the window, so that there\nis a slight overlap between the old and new views.\n\\fINumber\\fR is either 1, which means the next page should\nbecome visible, or \\-1, which means that the previous page should\nbecome visible.\n.TP\n\\fIprefix \\fBscroll \\fInumber \\fBunits\\fR\n.\nThe widget should adjust its view by \\fInumber\\fR units.\nThe units are defined in whatever way makes sense for the widget,\nsuch as characters or lines in a text widget.\n\\fINumber\\fR is either 1, which means one unit should scroll off\nthe top or left of the window, or \\-1, which means that one unit\nshould scroll off the bottom or right of the window.\n.SH \"WIDGET STATES\"\n.PP\nThe scrollbar automatically sets the \\fBdisabled\\fR state bit.\nwhen the entire range is visible (range is 0.0 to 1.0),\nand clears it otherwise.\nIt also sets the \\fBactive\\fR and \\fBpressed\\fR state flags\nof individual elements, based on the position and state of the mouse pointer.\n.SH EXAMPLE\n.PP\n.CS\nset f [frame .f]\n\\fBttk::scrollbar\\fR $f.hsb -orient horizontal -command [list $f.t xview]\n\\fBttk::scrollbar\\fR $f.vsb -orient vertical -command [list $f.t yview]\ntext $f.t -xscrollcommand [list $f.hsb set] -yscrollcommand [list $f.vsb set]\ngrid $f.t -row 0 -column 0 -sticky nsew\ngrid $f.vsb -row 0 -column 1 -sticky nsew\ngrid $f.hsb -row 1 -column 0 -sticky nsew\ngrid columnconfigure $f 0 -weight 1\ngrid rowconfigure $f 0 -weight 1\npack $f\n.CE\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::scrollbar\\fP is \\fBTScrollbar\\fP.\n.PP\nDynamic states: \\fBactive\\fP, \\fBdisabled\\fP.\n.PP\n\\fBTScrollbar\\fP (or more specifically \\fBVertical.TScrollbar\\fP and\n\\fBHorizontal.TScrollbar\\fP) styling options that are configurable with\n\\fBttk::style\\fP are:\n.PP\n\\fB\\-arrowcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-arrowsize\\fP \\fIamount\\fP\n.br\n\\fB\\-background\\fP \\fIcolor\\fP\n.br\n\\fB\\-bordercolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-darkcolor\\fP \\fIcolor\\fP (color of the dark part of the 3D relief)\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-gripsize\\fP \\fIsize\\fP (number of screen units)\n.br\n\\fB\\-lightcolor\\fP \\fIcolor\\fP (color of the light part of the 3D relief)\n.br\n\\fB\\-troughcolor\\fP \\fIcolor\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n), scrollbar(n)\n.SH KEYWORDS\nscrollbar, widget\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_separator.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::separator n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::separator \\- Separator bar\n.SH SYNOPSIS\n\\fBttk::separator\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::separator\\fR widget displays a horizontal or vertical separator\nbar.\n.SO ttk_widget\n\\-class\t\\-cursor\n\\-style\t\\-takefocus\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-orient orient Orient\nOne of \\fBhorizontal\\fR or \\fBvertical\\fR.\nSpecifies the orientation of the separator.\n.SH \"WIDGET COMMAND\"\n.PP\nSeparator widgets support the standard commands\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\n(see \\fBttk::widget\\fR).\n.PP\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::separator\\fP is \\fBTSeparator\\fP.\n.PP\n\\fBTSeparator\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n)\n.SH \"KEYWORDS\"\nwidget, separator\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_sizegrip.n", "content": "'\\\"\n'\\\" Copyright (c) 2006 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::sizegrip n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::sizegrip \\- Bottom-right corner resize widget\n.SH SYNOPSIS\n\\fBttk::sizegrip\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::sizegrip\\fR widget (also known as a \\fIgrow box\\fR)\nallows the user to resize the containing toplevel window\nby pressing and dragging the grip.\n.SO ttk_widget\n\\-class\t\\-cursor\n\\-style\t\\-takefocus\n.SE\n.SH \"WIDGET COMMAND\"\n.PP\nSizegrip widgets support the standard commands\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR and \\fBstyle\\fR\n(see \\fBttk::widget\\fR).\n.SH \"PLATFORM-SPECIFIC NOTES\"\n.PP\nOn macOS, toplevel windows automatically include a built-in\nsize grip by default.\nAdding a \\fBttk::sizegrip\\fR there is harmless, since\nthe built-in grip will just mask the widget.\n.SH EXAMPLES\n.PP\nUsing pack:\n.CS\npack [ttk::frame $top.statusbar] -side bottom -fill x\npack [\\fBttk::sizegrip\\fR $top.statusbar.grip] -side right -anchor se\n.CE\n.PP\nUsing grid:\n.CS\ngrid [\\fBttk::sizegrip\\fR $top.statusbar.grip] \\e\n -row $lastRow -column $lastColumn -sticky se\n# ... optional: add vertical scrollbar in $lastColumn,\n# ... optional: add horizontal scrollbar in $lastRow\n.CE\n.SH \"BUGS\"\n.PP\nIf the containing toplevel's position was specified\nrelative to the right or bottom of the screen\n(e.g.,\n.QW \"\\fBwm geometry ... \\fIw\\fBx\\fIh\\fB\\-\\fIx\\fB\\-\\fIy\\fR\"\ninstead of\n.QW \"\\fBwm geometry ... \\fIw\\fBx\\fIh\\fB+\\fIx\\fB+\\fIy\\fR\" ),\nthe sizegrip widget will not resize the window.\n.PP\n\\fBttk::sizegrip\\fR widgets only support\n.QW southeast\nresizing.\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::sizegrip\\fP is \\fBTSizegrip\\fP.\n.PP\n\\fBTSizegrip\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-background\\fP \\fIcolor\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.SH \"SEE ALSO\"\nttk::widget(n)\n.SH \"KEYWORDS\"\nwidget, sizegrip, grow box\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_spinbox.n", "content": "'\\\"\n'\\\" Copyright (c) 2008 Pat Thoyts\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::spinbox n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::spinbox \\- Selecting text field widget\n.SH SYNOPSIS\n\\fBttk::spinbox\\fI pathName \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::spinbox\\fR widget is a \\fBttk::entry\\fR widget with built-in\nup and down buttons that are used to either modify a numeric value or\nto select among a set of values. The widget implements all the features\nof the \\fBttk::entry\\fR widget including support of the\n\\fB\\-textvariable\\fR option to link the value displayed by the widget\nto a Tcl variable.\n.SO ttk_widget\n\\-class\t\\-cursor\t\\-state\n\\-style\t\\-takefocus\t\\-xscrollcommand\n\\-placeholder\t\\-placeholderforeground\n.SE\n.SO ttk_entry\n\\-validate\t\\-validatecommand\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-command command Command\nSpecifies a Tcl command to be invoked whenever a spinbutton is invoked.\n.OP \\-format format Format\nSpecifies an alternate format to use when setting the string value\nwhen using the \\fB\\-from\\fR and \\fB\\-to\\fR range.\nThis must be a format specifier of the form \\fB%.f\\fR,\nas it will format a floating-point number.\n.OP \\-from from From\nA floating-point value specifying the lowest value for the spinbox. This is\nused in conjunction with \\fB\\-to\\fR and \\fB\\-increment\\fR to set a numerical\nrange.\n.OP \\-increment increment Increment\nA floating-point value specifying the change in value to be applied each\ntime one of the widget spin buttons is pressed. The up button applies a\npositive increment, the down button applies a negative increment.\n.OP \\-to to To\nA floating-point value specifying the highest permissible value for the\nwidget. See also \\fB\\-from\\fR and \\fB\\-increment\\fR.\nrange.\n.OP \\-values values Values\nThis must be a Tcl list of values. If this option is set then this will\noverride any range set using the \\fB\\-from\\fR, \\fB\\-to\\fR and\n\\fB\\-increment\\fR options. The widget will instead use the values\nspecified beginning with the first value.\n.OP \\-wrap wrap Wrap\nMust be a proper boolean value. If on, the spinbox will wrap around the\nvalues of data in the widget.\n.SH \"INDICES\"\n.PP\nSee the \\fBttk::entry\\fR manual for information about indexing characters.\n.SH \"VALIDATION\"\n.PP\nSee the \\fBttk::entry\\fR manual for information about using the\n\\fB\\-validate\\fR and \\fB\\-validatecommand\\fR options.\n.SH \"WIDGET COMMAND\"\n.PP\nThe following subcommands are possible for spinbox widgets in addition to\nthe commands described for the \\fBttk::entry\\fR widget:\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget\\fR\n.\nReturns the spinbox's current value.\n.\\\" METHOD: set\n.TP\n\\fIpathName \\fBset \\fIvalue\\fR\n.\nSet the spinbox string to \\fIvalue\\fR. If a \\fB\\-format\\fR option has\nbeen configured then this format will be applied. If formatting fails\nor is not set or the \\fB\\-values\\fR option has been used then the value\nis set directly.\n.SH \"VIRTUAL EVENTS\"\n.PP\nThe spinbox widget generates a \\fB<>\\fR virtual event when\nthe user presses , and a \\fB<>\\fR virtual event when the\nuser presses .\n.SH \"STYLING OPTIONS\"\n.PP\nThe class name for a \\fBttk::spinbox\\fP is \\fBTSpinbox\\fP.\n.PP\nDynamic states: \\fBactive\\fP, \\fBdisabled\\fP, \\fBfocus\\fP, \\fBreadonly\\fP.\n.PP\n\\fBTSpinbox\\fP styling options configurable with \\fBttk::style\\fP\nare:\n.PP\n\\fB\\-arrowcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-arrowsize\\fP \\fIamount\\fP\n.br\n\\fB\\-background\\fP \\fIcolor\\fP\n.RS\nFor backwards compatibility, when using the aqua theme (for macOS), this\noption behaves as an alias for the \\fB\\-fieldbackground\\fP provided that no\nvalue is specified for \\fB\\-fieldbackground\\fP. Otherwise it is ignored.\n.RE\n\\fB\\-bordercolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-darkcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-fieldbackground\\fP \\fIcolor\\fP\n.br\n\\fB\\-foreground\\fP \\fIcolor\\fP\n.br\n\\fB\\-insertcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-insertwidth\\fP \\fIamount\\fP\n.br\n\\fB\\-lightcolor\\fP \\fIcolor\\fP\n.br\n\\fB\\-padding\\fP \\fIpadding\\fP\n.br\n\\fB\\-placeholderforeground\\fP \\fIcolor\\fP\n.br\n\\fB\\-selectbackground\\fP \\fIcolor\\fP\n.br\n\\fB\\-selectforeground\\fP \\fIcolor\\fP\n.PP\nSome options are only available for specific themes.\n.PP\nSee the \\fBttk::style\\fP manual page for information on how to configure\nttk styles.\n.PP\nBesides the standard \\fBTSpinbox\\fP layout with small arrow buttons, in\nwhich the up arrow is placed above the down arrow, \\fBttk::spinbox\\fP\nwidgets support the \\fBWide.TSpinbox\\fP style, whose up and down arrows\nare of a more user-friendly size and in which the up arrow is placed to\nthe right of the down arrow. The size of these arrows depends on the\ndisplay's scaling level and Tk's scaling factor given by \\fB[tk scaling]\\fP\nat the time the first themed spinbox widget is created.\n.SH \"SEE ALSO\"\nttk::widget(n), ttk::entry(n), spinbox(n)\n.SH KEYWORDS\nentry, spinbox, widget, text field\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_style.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::style n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::style \\- Manipulate style database\n.SH SYNOPSIS\n\\fBttk::style\\fI option\\fR ?\\fIargs\\fR?\n.BE\n.SH NOTES\n.PP\nSee also the Tcl'2004 conference presentation,\navailable at https://tktable.sourceforge.net/tile/tile-tcl2004.pdf\n.SH DEFINITIONS\n.PP\nEach widget is assigned a \\fIstyle\\fR,\nwhich specifies the set of elements making up the widget\nand how they are arranged, along with dynamic and default\nsettings for element options.\nBy default, the style name is the same as the widget's class;\nthis may be overridden by the \\fB\\-style\\fR option.\n.PP\nA \\fItheme\\fR is a collection of elements and styles\nwhich controls the overall look and feel of an application.\nThe\n.QW .\nstyle is the theme root style on which derived styles are based.\n.SH DESCRIPTION\n.PP\nThe \\fBttk::style\\fR command takes the following arguments:\n.\\\" METHOD: configure\n.TP\n\\fBttk::style configure \\fIstyle\\fR ?\\fI\\-option\\fR ?\\fIvalue option value...\\fR? ?\n.\nSets the default value of the specified option(s) in \\fIstyle\\fR.\nIf \\fIstyle\\fR does not exist, it is created.\nIf only \\fIstyle\\fR and \\fI\\-option\\fR are specified, get the default value\nfor option \\fI\\-option\\fR of style \\fIstyle\\fR.\nIf only \\fIstyle\\fR is specified, get the default value for all options\nof style \\fIstyle\\fR.\n.\\\" METHOD: element\n.TP\n\\fBttk::style element\\fI args\\fR\n.RS\n.TP\n\\fBttk::style element create\\fI elementName type\\fR ?\\fIargs...\\fR?\n.\nCreates a new element in the current theme of type \\fItype\\fR.\nThe only cross-platform built-in element type is \\fIimage\\fR\n(see \\fBttk_image\\fR(n)) but themes may define other element types\n(see \\fBTtk_RegisterElementFactory\\fR). On suitable versions of Windows\nan element factory is registered to create Windows theme elements\n(see \\fBttk_vsapi\\fR(n)).\n.TP\n\\fBttk::style element names\\fR\n.\nReturns the list of elements defined in the current theme.\n.TP\n\\fBttk::style element options \\fIelement\\fR\n.\nReturns the list of \\fIelement\\fR's options.\n.RE\n.\\\" METHOD: layout\n.TP\n\\fBttk::style layout \\fIstyle\\fR ?\\fIlayoutSpec\\fR?\n.\nDefine the widget layout for style \\fIstyle\\fR.\nSee \\fBLAYOUTS\\fR below for the format of \\fIlayoutSpec\\fR.\nIf \\fIlayoutSpec\\fR is omitted, return the layout specification\nfor style \\fIstyle\\fR.\n.\\\" METHOD: lookup\n.TP\n\\fBttk::style lookup \\fIstyle \\-option \\fR?\\fIstate \\fR?\\fIdefault\\fR??\n.\nReturns the value specified for \\fI\\-option\\fR in style \\fIstyle\\fR\nin state \\fIstate\\fR, using the standard lookup rules for element options.\n\\fIstate\\fR is a list of state names; if omitted,\nit defaults to all bits off (the\n.QW normal\nstate).\nIf the \\fIdefault\\fR argument is present, it is used as a fallback\nvalue in case no specification for \\fI\\-option\\fR is found.\n.\\\" Otherwise -- signal error? return empty string? Leave unspecified for now.\nIf \\fIstyle\\fR does not exist, it is created.\n.\\\" METHOD: map\n.TP\n\\fBttk::style map \\fIstyle\\fR ?\\fI\\-option\\fB { \\fIstatespec value...\\fB }\\fR?\n.\nSets dynamic (state dependent) values of the specified option(s) in \\fIstyle\\fR.\nEach \\fIstatespec / value\\fR pair is examined in order;\nthe value corresponding to the first matching \\fIstatespec\\fR\nis used.\nIf \\fIstyle\\fR does not exist, it is created.\nIf only \\fIstyle\\fR and \\fI\\-option\\fR are specified, get the dynamic values\nfor option \\fI\\-option\\fR of style \\fIstyle\\fR.\nIf only \\fIstyle\\fR is specified, get the dynamic values for all options\nof style \\fIstyle\\fR.\n.\\\" METHOD: theme\n.TP\n\\fBttk::style theme\\fI args\\fR\n.RS\n.TP\n\\fBttk::style theme create\\fI themeName\\fR ?\\fB\\-parent \\fIbasedon\\fR? ?\\fB\\-settings \\fIscript...\\fR ?\n.\nCreates a new theme. It is an error if \\fIthemeName\\fR already exists.\nIf \\fB\\-parent\\fR is specified, the new theme will inherit\nstyles, elements, and layouts from the parent theme \\fIbasedon\\fR.\nIf \\fB\\-settings\\fR is present, \\fIscript\\fR is evaluated in the\ncontext of the new theme as per \\fBttk::style theme settings\\fR.\n.TP\n\\fBttk::style theme names\\fR\n.\nReturns a list of all known themes.\n.TP\n\\fBttk::style theme settings \\fIthemeName script\\fR\n.\nTemporarily sets the current theme to \\fIthemeName\\fR,\nevaluate \\fIscript\\fR, then restore the previous theme.\nTypically \\fIscript\\fR simply defines styles and elements,\nthough arbitrary Tcl code may appear.\n.TP\n\\fBttk::style theme styles\\fR ?\\fIthemeName\\fR?\n.\nReturns a list of all styles in \\fIthemeName\\fR. If \\fIthemeName\\fR\nis omitted, the current theme is used.\n.TP\n\\fBttk::style theme use\\fR ?\\fIthemeName\\fR?\n.\nWithout an argument the result is the name of the current theme.\nOtherwise this command sets the current theme to \\fIthemeName\\fR,\nand refreshes all widgets.\n.RE\n.SH LAYOUTS\n.PP\nA \\fIlayout\\fR specifies a list of elements, each followed\nby one or more options specifying how to arrange the element.\nThe layout mechanism uses a simplified version of the \\fBpack\\fR\ngeometry manager: given an initial cavity,\neach element is allocated a parcel.\nThen the parcel actually used by the element is adjusted within\nthe allocated parcel.\nValid options are:\n.\\\" -border should remain undocumented for now (dubious usefulness)\n.\\\" .TP\n.\\\" \\fB\\-border\\fI boolean\\fR\n.\\\" .\n.\\\" Specifies whether the element is drawn after its children. Defaults to 0.\n.\\\" OPTION: -children\n.TP\n\\fB\\-children { \\fIsublayout...\\fB }\\fR\n.\nSpecifies a list of elements to place inside the element.\n.\\\" OPTION: -expand\n.TP\n\\fB\\-expand\\fI boolean\\fR\n.\nSpecifies whether the allocated parcel is the entire cavity. If so,\nsimultaneous specification of \\fB\\-side\\fR is ignored.\nDefaults to 0.\n.\\\" OPTION: -side\n.TP\n\\fB\\-side \\fIside\\fR\n.\nSpecifies which side of the cavity to place the element;\none of \\fBleft\\fR, \\fBright\\fR, \\fBtop\\fR, or \\fBbottom\\fR.\nFor instance, \\fB\\-side top\\fR allocates the parcel along the top of\nthe cavity having width and height respectively the width of the cavity\nand the height of the element.\nIf omitted, the allocated parcel is the entire cavity (same effect\nas \\fB\\-expand\\fR 1).\n.\\\" OPTION: -sticky\n.TP\n\\fB\\-sticky\\fR \\fB[\\fInswe\\fB]\\fR\n.\nSpecifies the actual parcel position and size inside the allocated parcel.\nIf specified as an empty string then the actual parcel is centered in\nthe allocated parcel. Default is \\fBnswe\\fR.\n.\\\" -unit should remain undocumented for now (dubious usefulness)\n.\\\" .TP\n.\\\" \\fB\\-unit\\fI boolean\\fR\n.\\\" .\n.\\\" Specifies whether the element propagates its state to its children.\n.\\\" Defaults to 0.\n.PP\nFor example:\n.CS\nttk::style layout Horizontal.TScrollbar {\n Scrollbar.trough -children {\n Scrollbar.leftarrow -side left\n Scrollbar.rightarrow -side right\n Horizontal.Scrollbar.thumb -side left -sticky ew\n }\n}\n.CE\n.SH ROOT STYLE\n.PP\nThe\n.QW .\ntheme root style can be configured like any other style, providing defaults\nfor its derived styles. In addition to the usual options,\n.QW .\nstyling options configurable with \\fBttk::style\\fP are:\n.PP\n\\fB\\-insertofftime\\fP \\fIamount\\fP\n.RS\nSpecifies a non-negative integer value indicating the number of milliseconds\nthe insertion cursor should remain\n.QW off\nin each blink cycle. If this option is zero then the cursor does not blink:\nit is on all the time. Defaults to 300 ms, unless overriden with a\n\\fBRESOURCE_MANAGER\\fR property or \\fB.Xdefaults\\fR file.\n.RE\n.PP\n\\fB\\-insertontime\\fP \\fIamount\\fP\n.RS\nSpecifies a non-negative integer value indicating the number of milliseconds\nthe insertion cursor should remain\n.QW on\nin each blink cycle. Defaults to 600 ms, unless overriden with a\n\\fBRESOURCE_MANAGER\\fR property or \\fB.Xdefaults\\fR file.\n.RE\n.SH \"SEE ALSO\"\nttk::intro(n), ttk::widget(n), photo(n), ttk_image(n)\n.SH KEYWORDS\nstyle, theme, appearance\n'\\\" Local Variables:\n'\\\" mode: nroff\n'\\\" End:\n" }, { "path": "doc/ttk_toggleswitch.n", "content": ".\\\"\n.\\\" Copyright (c) 2025 Csaba Nemethi\n.\\\"\n.\\\" See the file \"license.terms\" for information on usage and redistribution\n.\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n.\\\"\n.TH ttk::toggleswitch n 9.1 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::toggleswitch \\- Create and manipulate a toggleswitch widget\n.SH SYNOPSIS\n\\fBttk::toggleswitch \\fIpathName \\fR?\\fIoptions...\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nA \\fBttk::toggleswitch\\fR widget is used to show or change a binary setting.\nIt consists of a horizontal \\fItrough\\fR (a fully rounded filled rectangle)\nand a \\fIslider\\fR (a filled circle or fully rounded filled rectangle\ncontained in the trough). Their dimensions depend on the value of the\n\\fB-size\\fR configuration option, the current theme, the display's scaling\nlevel, and Tk's scaling factor given by \\fB[tk scaling]\\fR at the time the\nfirst toggleswitch widget is created.\n.PP\nJust like a light switch, a toggleswitch widget can have one of two possible\n\\fIswitch state\\fRs: on or off. In the on state the slider is placed at the\nend of the trough, and in the off state at its beginning. The user can toggle\nbetween these two states with the mouse or the space key.\n.PP\nThe colors used when drawing the trough and slider in the various widget\nstates depend on the current theme. If the theme is \\fBaqua\\fR then they also\ndepend on the system appearance (light mode or dark mode) and the accent\ncolor, and are automatically adapted whenever one of these global system\nsettings changes.\n.PP\nThe implementation creates these elements when needed with the aid of generic\ncode for arbitrary themes and theme-specific one for a few built-in themes.\nApplications can add \\fIexplicit\\fR support for any theme \\fItheme\\fR by\nproviding an appropriate command of the name\n\\fBttk::toggleswitch::CreateElements_\\fR\\fItheme\\fR.\n.SO ttk_widget\n\\-class\t\\-cursor\t\\-style\n\\-takefocus\n.SE\n.PP\nThe default value of the \\fB-class\\fR option is \\fBToggleswitch\\fR. The value\nof the \\fB-style\\fR option defaults to \\fBToggleswitch2\\fR, corresponding to\nthe \\fB-size\\fR option's default value \\fB2\\fR (see below).\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-command command Command\nSpecifies a Tcl script to be evaluated at global scope whenever the switch\nstate of the widget is toggled (programmatically, by invoking the\n\\fBswitchstate\\fR or \\fBtoggle\\fR subcommand, or interactively). The default\nis an empty string.\n.OP \\-offvalue offValue OffValue\nThe value to store in the associated \\fB\\-variable\\fR\nwhen the widget's switch state is set to off. Defaults to \\fB0\\fR.\n.OP \\-onvalue onValue OnValue\nThe value to store in the associated \\fB\\-variable\\fR\nwhen the widget's switch state is set to on. Defaults to \\fB1\\fR.\n.OP \\-size size Size\nSpecifies the size identifier of the toggleswitch widget. The supported\nvalues are the strings \\fB1\\fR, \\fB2\\fR (the default), and \\fB3\\fR. In the\ncase of the \\fBaqua\\fR theme, these size IDs correspond to the control sizes\n\"mini\", \"small\", and \"large\" of the native toggle switches on macOS.\n.RS\n.PP\nNote that by setting this option to a value \\fIsize\\fR, the \\fB-style\\fR\noption's value will automatically change to \\fBToggleswitch\\fR\\fIsize\\fR if\nits previous or requested value was \\fBToggleswitch1\\fR, \\fBToggleswitch2\\fR,\nor \\fBToggleswitch3\\fR, and to \\fIprefix\\fR.\\fBToggleswitch\\fR\\fIsize\\fR if\nits previous or requested value was \\fIprefix\\fR.\\fBToggleswitch1\\fR,\n\\fIprefix\\fR.\\fBToggleswitch2\\fR, or \\fIprefix\\fR.\\fBToggleswitch3\\fR.\nConversely, by setting the \\fB-style\\fR option to a value of the form\n\\fBToggleswitch\\fR\\fIsize\\fR or \\fIprefix\\fR.\\fBToggleswitch\\fR\\fIsize\\fR\n(where \\fIsize\\fR is one of \\fB1\\fR, \\fB2\\fR, or \\fB3\\fR), the \\fB-size\\fR\noption will automatically be set to \\fIsize\\fR. When configuring both options\n\\fB-size\\fR and \\fB-style\\fR, the former will take precedence over the latter,\nregardless of the order in which they were specified.\n.PP\nFor example, if you create the widget with\n.PP\n.CS\n\\fBttk::toggleswitch\\fR \\fIpathName\\fR \\fB-size 3 -style\\fR My.\\fBToggleswitch3\\fR\n.CE\n.PP\nor invoke\n.PP\n.CS\n\\fIpathName\\fR \\fBconfigure -style\\fR My.\\fBToggleswitch3\\fR\n.CE\n.PP\nthen the \\fB-style\\fR option will be set to My.\\fBToggleswitch3\\fR (and the\n\\fB-size\\fR option will have the value \\fB3\\fR). On the other hand, if you\ncreate the widget with\n.PP\n.CS\n\\fBttk::toggleswitch\\fR \\fIpathName\\fR \\fB-style\\fR My.\\fBToggleswitch3\\fR\n.CE\n.PP\nthen the \\fB-style\\fR option will have the value My.\\fBToggleswitch2\\fR rather\nthan My.\\fBToggleswitch3\\fR, because the widget creation triggers the default\n\\fB-size 2\\fR setting, which takes precedence over \\fB-style\\fR\nMy.\\fBToggleswitch3\\fR.\n.RE\n.OP \\-variable variable Variable\nThe name of a global variable whose value is linked to the toggleswitch. The\nwidget's switch state changes to on when this variable is set to the value\nspecified by the \\fB-onvalue\\fR option and to off otherwise. Defaults to the\nwidget's pathname if not specified.\n.RS\n.PP\nNote that, just like in the case of the (ttk::)checkbutton, toggling the\nwidget's switch state by changing the value of this variable will \\fInot\\fR\ncause the script specified by the \\fB-command\\fR option to get executed.\n.RE\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBidentify element\\fR, \\fBinstate\\fR,\n\\fBstate\\fR, and \\fBstyle\\fR commands (see \\fBttk::widget\\fR), toggleswitch\nwidgets support the following additional commands:\n.\\\" METHOD: switchstate\n.TP\n\\fIpathName \\fBswitchstate \\fR?\\fIboolean\\fR?\n.\nModifies or inquires the widget's switch state. If the optional argument is\npresent then it must be a boolean (a numeric value, where 0 is false and\nanything else is true, or a string such as \\fBtrue\\fR/\\fByes\\fR/\\fBon\\fR or\n\\fBfalse\\fR/\\fBno\\fR/\\fBoff\\fR). If the widget's \\fBdisabled\\fR state flag is\nset then the command returns an empty string immediately after checking the\nargument. Otherwise, if the argument is true then the command sets the\nwidget's switch state to on by setting its \\fBselected\\fR flag, moving the\nslider to the end of the trough, and setting the associated \\fB-variable\\fR to\nthe value specified by the \\fB-onvalue\\fR option; if the argument is false\nthen the command sets the widget's switch state to off by clearing the\n\\fBselected\\fR flag, moving the slider to the beginning of the trough, and\nsetting the associated variable to the value specified by the \\fB-offvalue\\fR\noption.\n.RS\n.PP\nIf the argument's value causes the widget's switch state to get toggled and\nthe script specified as the value of the \\fB-command\\fR option is a nonempty\nstring then the command evaluates that script at global scope and returns its\nresult; otherwise the return value is an empty string.\n.PP\nIf the optional argument is not present then the command returns the widget's\ncurrent switch state as \\fB0\\fR (off) or \\fB1\\fR (on). When a toggleswitch\nwidget is created, its switch state is initialized with \\fB0\\fR.\n.RE\n.\\\" METHOD: toggle\n.TP\n\\fIpathName \\fBtoggle\\fR\n.\nThis convenience subcommand toggles the widget's switch state. It is\nlogically equivalent to invoking the \\fBswitchstate\\fR command with the\nargument \\fB0\\fR if the current switch state is on and with the argument\n\\fB1\\fR otherwise.\n.SH \"INTERNAL COMMANDS\"\n.PP\nThe following widget commands are used internally by the \\fBToggleswitch\\fR\nwidget class bindings. They provide a means to access the widget's internal\nvalue, which is a real number within a certain invariant interval.\n.\\\" METHOD: get\n.TP\n\\fIpathName \\fBget \\fR?\\fBmin\\fR|\\fBmax\\fR|\\fIx\\fR?\n.\nReturns the current/minimum/maximum internal value, or the one corresponding\nto the coordinate \\fIx\\fR relative to the widget origin if it is specified.\n.\\\" METHOD: set\n.TP\n\\fIpathName \\fBset \\fIvalue\\fR\n.\nSets the widget's internal value to \\fIvalue\\fR. The value will be clipped to\nthe range given by the minimum and maximum values, as returned by\n\\fBget min\\fR and \\fBget max\\fR.\n.PP\n.\\\" METHOD: xcoord\n.TP\n\\fIpathName \\fBxcoord \\fR?\\fIvalue\\fR?\n.\nReturns the x coordinate corresponding to \\fIvalue\\fR, or to the current\ninternal value if \\fIvalue\\fR is omitted.\n.SH \"DEFAULT BINDINGS\"\n.PP\nThe toggleswitch widget's default bindings enable the following behavior.\n.PP\nIf the current theme is \\fBaqua\\fR:\n.IP \\0\\(bu 4\nBy pressing mouse button 1 over the slider and then dragging the mouse with\nbutton 1 down until the pointer enters the trough, the slider moves smoothly\nto the opposite edge of the trough and the widget's switch state gets\ntoggled. The same happens if mouse button 1 is pressed outside the slider and\nthen the pointer leaves the widget horizontally with button 1 down.\n.IP \\0\\(bu 4\nBy pressing mouse button 1 anywhere within the widget and then releasing it\nover the widget without previously moving the slider, the latter moves\nsmoothly to the opposite edge of the trough and the widget's switch state gets\ntoggled.\n.IP \\0\\(bu 4\nWhen the widget has the input focus, the space key causes its switch state to\nget toggled.\n.PP\nIf the current theme is different from \\fBaqua\\fR:\n.IP \\0\\(bu 4\nBy pressing mouse button 1 anywhere within the widget and then dragging the\nmouse with button 1 down, the slider moves in the same (horizontal) direction\nas the pointer. By releasing the button, the switch state is set to off or\non, depending on the slider's position relative to the middle of the widget.\n.IP \\0\\(bu 4\nBy pressing mouse button 1 anywhere within the widget and then releasing it\nover the widget without previously dragging the mouse horizontally, the\nwidget's switch state gets toggled.\n.IP \\0\\(bu 4\nWhen the widget has the input focus, the space key causes its switch state to\nget toggled.\n.PP\nIf the widget's \\fBdisabled\\fR state flag is set then none of the above\nactions occur.\n.SH \"WIDGET STATES\"\n.PP\nThe widget sets the \\fBselected\\fR state whenever the switch state changes to\non and clears it otherwise. The widget sets the \\fBinvalid\\fR state whenever\nthe linked \\fB\\-variable\\fR is unset. The defalt bindings set and clear the\n\\fBactive\\fR and \\fBpressed\\fR state flags.\n.SH \"STYLING OPTIONS\"\n.PP\nThe default class name for a \\fBttk::toggleswitch\\fP is \\fBToggleswitch\\fP.\n.PP\nDynamic states: \\fBactive\\fP, \\fBbackground\\fP, \\fBdisabled\\fP, \\fBinvalid\\fP,\n\\fBpressed\\fP, \\fBselected\\fP.\n.PP\n\\fBToggleswitch1\\fP, \\fBToggleswitch2\\fP, and \\fBToggleswitch3\\fP styling\noptions configurable with \\fBttk::style\\fP are:\n.PP\n\\fB\\-focuscolor\\fP \\fIcolor\\fP\n.RS\nThe default is theme-specific.\n.RE\n.br\n\\fB\\-focussolid\\fP \\fIboolean\\fP\n.RS\nDefaults to true for the \\fBclassic\\fP theme and false for all the others.\n.RE\n.br\n\\fB\\-focusthickness\\fP \\fIamount\\fP\n.RS\nThe default is 1. The value may have any of the forms acceptable to\n\\fBTk_GetPixels\\fP.\n.RE\n.br\n\\fB\\-padding\\fP \\fIpadding\\fP\n.RS\nDefaults to 1.5p for the \\fBaqua\\fP theme (for which the three above-mentioned\nstyles have no \\fBfocus\\fP element) and 0.75p for all the other themes.\n.RE\n.PP\nFor the \\fBaqua\\fP theme only the \\fB\\-padding\\fP option is available, the\nothers are simply ignored.\n.PP\nSee the \\fBttk_style\\fP manual page for information on how to configure ttk\nstyles.\n.SH \"SEE ALSO\"\nttk::widget(n), ttk::style(n), ttk::checkbutton(n), checkbutton(n).\n.SH KEYWORDS\ntoggleswitch, trough, slider, widget\n.\\\" Local Variables:\n.\\\" mode: nroff\n.\\\" fill-column: 78\n.\\\" End:\n" }, { "path": "doc/ttk_treeview.n", "content": "'\\\"\n'\\\" Copyright (c) 2004 Joe English\n'\\\"\n'\\\" See the file \"license.terms\" for information on usage and redistribution\n'\\\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.\n'\\\"\n.TH ttk::treeview n 8.5 Tk \"Tk Themed Widget\"\n.so man.macros\n.BS\n.SH NAME\nttk::treeview \\- hierarchical multicolumn data display widget\n.SH SYNOPSIS\n\\fBttk::treeview \\fIpathname \\fR?\\fIoptions\\fR?\n.BE\n.SH DESCRIPTION\n.PP\nThe \\fBttk::treeview\\fR widget displays a hierarchical collection of items.\nEach item has a textual label, an optional image,\nand an optional list of data values.\nThe data values are displayed in successive columns after\nthe tree label.\n.PP\nThe order in which data values are displayed may be controlled\nby setting the \\fB\\-displaycolumns\\fR widget option.\nThe tree widget can also display column headings.\nColumns may be accessed by number or by symbolic names\nlisted in the \\fB\\-columns\\fR widget option;\nsee \\fBCOLUMN IDENTIFIERS\\fR.\n.PP\nEach item is identified by a unique name.\nThe widget will generate item IDs if they are not supplied by the caller.\nThere is a distinguished root item, named \\fB{}\\fR.\nThe root item itself is not displayed;\nits children appear at the top level of the hierarchy.\n.PP\nEach item also has a list of \\fItags\\fR,\nwhich can be used to associate event bindings with individual items\nand control the appearance of the item.\n.\\\" .PP\n.\\\" @@@HERE: describe selection, focus item\n.PP\nTreeview widgets support horizontal and vertical scrolling with the\nstandard \\fB\\-\\fR[\\fBxy\\fR]\\fBscrollcommand\\fR options\nand [\\fBxy\\fR]\\fBview\\fR widget commands.\n.SO ttk_widget\n\\-class\t\\-cursor\t\\-takefocus\n\\-style\t\\-xscrollcommand\t\\-yscrollcommand\n\\-padding\n.SE\n.SH \"WIDGET-SPECIFIC OPTIONS\"\n.OP \\-columns columns Columns\nA list of column identifiers,\nspecifying the number of columns and their names.\n.\\\"X: This is a read-only option; it may only be set when the widget is created.\n.OP \\-displaycolumns displayColumns DisplayColumns\nA list of column identifiers\n(either symbolic names or integer indices)\nspecifying which data columns are displayed\nand the order in which they appear,\nor the string \\fB#all\\fP.\nIf set to \\fB#all\\fP (the default),\nall columns are shown in the order given.\n.OP \\-height height Height\nSpecifies the number of rows which should be visible.\nNote that\nthe requested width is determined from the sum of the column widths.\n.OP \\-selectmode selectMode SelectMode\nControls how the built-in class bindings manage the selection.\nOne of \\fBextended\\fR, \\fBbrowse\\fR, or \\fBnone\\fR.\n.RS\n.PP\nIf set to \\fBextended\\fR (the default), multiple items may be selected.\nIf \\fBbrowse\\fR, only a single item will be selected at a time.\nIf \\fBnone\\fR, the selection will not be changed.\n.PP\nNote that application code and tag bindings can set the selection\nhowever they wish, regardless of the value of \\fB\\-selectmode\\fR.\n.RE\n.OP \\-selecttype selectType SelectType\nControls how the built-in class bindings manage the selection.\nOne of \\fBitem\\fR or \\fBcell\\fR.\n.OP \\-show show Show\nA list containing zero or more of the following values, specifying\nwhich elements of the tree to display.\n.RS\n.IP \\fBtree\\fR\nDisplay tree labels in column #0.\n.IP \\fBheadings\\fR\nDisplay the heading row.\n.PP\nThe default is \\fBtree headings\\fR.\n.PP\n\\fBNOTE:\\fR Column #0 always refers to the tree column,\neven if \\fB\\-show tree\\fR is not specified.\n.RE\n.OP \\-striped striped Striped\nBoolean specifying zebra striped item coloring.\nNote that\nstriped items uses the \\fB\\-stripedbackground\\fR option if set by the theme or\na tag. If not supported by the current theme, it will not show.\n.OP \\-titlecolumns titleColumns TitleColumns\nNumber of display columns at the left that should not be scrolled. The tree\ncolumn counts, even if \\fB\\-show tree\\fR is not specified. Thus for value N of\nthis option, column #N is the first one that is scrollable. Default is 0.\n.OP \\-titleitems titleItems TitleItems\nNumber of items at the top that should not be vertically scrolled. Default is 0.\n.SH \"WIDGET COMMAND\"\n.PP\nIn addition to the standard\n\\fBcget\\fR, \\fBconfigure\\fR, \\fBinstate\\fR,\n\\fBstate\\fR, \\fBstyle\\fR, \\fBxview\\fR and \\fByview\\fR\ncommands (see \\fBttk::widget\\fR),\ntreeview widgets support the following additional commands:\n.\\\" METHOD: bbox\n.TP\n\\fIpathname \\fBbbox \\fIitem\\fR ?\\fIcolumn\\fR?\n.\nReturns the bounding box (relative to the treeview widget's window)\nof the specified \\fIitem\\fR in the form \\fIx y width height\\fR.\nIf the \\fIitem\\fR is not visible\n(i.e., if it is a descendant of a closed item or is vertically scrolled\noffscreen), returns the empty list.\nIf \\fIcolumn\\fR is specified and is not hidden (by the \\fB\\-displaycolumns\\fR\noption), returns the bounding box of that cell within \\fIitem\\fR\n(even if the cell is horizontally scrolled offscreen).\n.\\\" METHOD: cellselection\n.TP\n\\fIpathname \\fBcellselection\\fR ?\\fIselop arg ...\\fR?\n.\nManages cell selection. Cell selection is independent from item selection\nhandled by the \\fBselection\\fR command. A cell is given by a list of two\nelements, item and column.\nFor the rectangle versions of commands, the cells must be in displayed columns.\nAny change to \\fB\\-columns\\fR clears the cell selection.\nA \\fIcellList\\fR argument may be a single cell or a list of cells.\nIf \\fIselop\\fR is not specified, returns the list of selected cells.\nOtherwise, \\fIselop\\fR is one of the following:\n.RS\n.TP\n\\fIpathname \\fBcellselection set \\fIcellList\\fR\n.\n\\fIcellList\\fR becomes the new cell selection.\n.TP\n\\fIpathname \\fBcellselection set \\fIfirstCell lastCell\\fR\n.\nThe rectangle defined becomes the new cell selection.\n.TP\n\\fIpathname \\fBcellselection add \\fIcellList\\fR\n.\nAdd \\fIcellList\\fR to the cell selection.\n.TP\n\\fIpathname \\fBcellselection add \\fIfirstCell lastCell\\fR\n.\nThe rectangle defined is added to the cell selection.\n.TP\n\\fIpathname \\fBcellselection remove \\fIcellList\\fR\n.\nRemove \\fIcellList\\fR from the cell selection.\n.TP\n\\fIpathname \\fBcellselection remove \\fIfirstCell lastCell\\fR\n.\nThe rectangle defined is removed from the cell selection.\n.TP\n\\fIpathname \\fBcellselection toggle \\fIcellList\\fR\n.\nToggle the cell selection state of each cell in \\fIcellList\\fR.\nIf the element is partially visible, the result gives the full area of the\nelement, including any parts that are not visible.\n.TP\n\\fIpathname \\fBcellselection toggle \\fIfirstCell lastCell\\fR\n.\nToggle the cell selection state of each cell in the rectangle defined.\n.RE\n.\\\" METHOD: children\n.TP\n\\fIpathname \\fBchildren \\fIitem\\fR ?\\fInewchildren\\fR?\n.\nIf \\fInewchildren\\fR is not specified,\nreturns the list of children belonging to \\fIitem\\fR.\n.RS\n.PP\nIf \\fInewchildren\\fR is specified, replaces \\fIitem\\fR's child list\nwith \\fInewchildren\\fR.\nItems in the old child list not present in the new child list\nare detached from the tree.\nNone of the items in \\fInewchildren\\fR may be an ancestor\nof \\fIitem\\fR.\n.RE\n.\\\" METHOD: column\n.TP\n\\fIpathname \\fBcolumn \\fIcolumn\\fR ?\\fI\\-option \\fR?\\fIvalue \\-option value...\\fR?\n.\nQuery or modify the options for the specified \\fIcolumn\\fR.\nIf no \\fI\\-option\\fR is specified,\nreturns a dictionary of option/value pairs.\nIf a single \\fI\\-option\\fR is specified,\nreturns the value of that option.\nOtherwise, the options are updated with the specified values.\nThe following options may be set on each column:\n.RS\n.\\\" OPTION: -id\n.TP\n\\fB\\-id \\fIname\\fR\n.\nThe column name. This is a read-only option.\nFor example, [\\fI$pathname \\fBcolumn #\\fIn \\fB\\-id\\fR]\nreturns the data column associated with display column \\fIn\\fR.\nThe tree column has \\fB\\-id #0\\fR.\n.\\\" OPTION: -anchor\n.TP\n\\fB\\-anchor \\fIanchor\\fR\n.\nSpecifies how the text in this column should be aligned\nwith respect to the cell. \\fIAnchor\\fR is one of\n\\fBn\\fR, \\fBne\\fR, \\fBe\\fR, \\fBse\\fR,\n\\fBs\\fR, \\fBsw\\fR, \\fBw\\fR, \\fBnw\\fR, or \\fBcenter\\fR.\n.\\\" OPTION: -minwidth\n.TP\n\\fB\\-minwidth \\fIminwidth\\fR\n.\nThe minimum width of the column in pixels.\nThe treeview widget will not make the column any smaller than\n\\fB\\-minwidth\\fR when the widget is resized or the user drags a\nheading column separator. Default is 20 pixels.\n.\\\" OPTION: -separator\n.TP\n\\fB\\-separator \\fIboolean\\fR\n.\nSpecifies whether or not a column separator should be drawn to the right\nof the column. Default is false.\n.\\\" OPTION: -stretch\n.TP\n\\fB\\-stretch \\fIboolean\\fR\n.\nSpecifies whether or not the column width should be adjusted\nwhen the widget is resized or the user drags a heading column separator.\n\\fIBoolean\\fR may have any of the forms accepted by \\fBTcl_GetBoolean\\fR.\nBy default columns are stretchable.\n.\\\" OPTION: -width\n.TP\n\\fB\\-width \\fIwidth\\fR\n.\nThe width of the column in pixels. Default is 200 pixels. The specified\ncolumn width may be changed by Tk in order to honor \\fB\\-stretch\\fR\nand/or \\fB\\-minwidth\\fR, or when the widget is resized or the user drags a\nheading column separator.\n.PP\nUse \\fIpathname fBcolumn #0\\fR to configure the tree column.\n.RE\n.\\\" METHOD: delete\n.TP\n\\fIpathname \\fBdelete \\fIitemList\\fR\n.\nDeletes each of the items in \\fIitemList\\fR and all of their descendants.\nThe root item may not be deleted.\nSee also: \\fBdetach\\fR.\n.\\\" METHOD: detach\n.TP\n\\fIpathname \\fBdetach \\fIitemList\\fR\n.\nUnlinks all of the specified items in \\fIitemList\\fR from the tree.\nThe items and all of their descendants are still present\nand may be reinserted at another point in the tree\nwith the \\fBmove\\fR operation,\nbut will not be displayed until that is done.\nThe root item may not be detached.\nSee also: \\fBdelete\\fR.\n.\\\" METHOD: detached\n.TP\n\\fIpathname \\fBdetached \\fR?\\fIitem\\fR?\n.\nIf \\fIitem\\fR is provided, returns a boolean value indicating whether it is\nthe name of a detached item (see \\fBdetach\\fR). Otherwise, returns a list of\nall the detached items (in an arbitrary order). The root item is never\ndetached.\n.\\\" METHOD: exists\n.TP\n\\fIpathname \\fBexists \\fIitem\\fR\n.\nReturns 1 if the specified \\fIitem\\fR is present in the tree,\n0 otherwise.\n.\\\" METHOD: focus\n.TP\n\\fIpathname \\fBfocus \\fR?\\fIitem\\fR?\n.\nIf \\fIitem\\fR is specified, sets the focus item to \\fIitem\\fR.\nOtherwise, returns the current focus item, or \\fB{}\\fR if there is none.\n.\\\" Need: way to clear the focus item. {} works for this...\n.\\\"\n.\\\" METHOD: heading\n.TP\n\\fIpathname \\fBheading \\fIcolumn\\fR ?\\fI\\-option \\fR?\\fIvalue \\-option value...\\fR?\n.\nQuery or modify the heading options for the specified \\fIcolumn\\fR.\nValid options are:\n.RS\n.\\\" OPTION: -text\n.TP\n\\fB\\-text \\fItext\\fR\n.\nThe text to display in the column heading.\n.\\\" OPTION: -image\n.TP\n\\fB\\-image \\fIimageName\\fR\n.\nSpecifies an image to display to the right of the column heading.\n.\\\" OPTION: -anchor\n.TP\n\\fB\\-anchor \\fIanchor\\fR\n.\nSpecifies how the heading text should be aligned.\nOne of the standard Tk anchor values.\n.\\\" OPTION: -command\n.TP\n\\fB\\-command \\fIscript\\fR\n.\nA script to evaluate when the heading label is pressed.\n.PP\nUse \\fIpathname heading #0\\fR to configure the tree column heading.\n.RE\n.\\\" METHOD: identify\n.TP\n\\fIpathname \\fBidentify \\fIcomponent x y\\fR\n.\nReturns a description of the specified \\fIcomponent\\fR\nunder the point given by \\fIx\\fR and \\fIy\\fR,\nor the empty string if no such \\fIcomponent\\fR is present at that position.\nThe values \\fIx\\fR and \\fIy\\fR may have any of the forms acceptable to\n\\fBTk_GetPixels\\fR.\nThe following subcommands are supported:\n.RS\n.TP\n\\fIpathname \\fBidentify region \\fIx y\\fR\n.RS\nReturns one of:\n.IP heading\nTree heading area;\nuse [\\fBpathname identify column \\fIx y\\fR]\nto determine the heading number.\n.IP separator\nSpace between two column headings;\n[\\fBpathname identify column \\fIx y\\fR]\nwill return the display column identifier\nof the heading to left of the separator.\n.IP tree\nThe tree area.\n.IP cell\nA data cell.\n.RE\n.TP\n\\fIpathname \\fBidentify item \\fIx y\\fR\n.\nReturns the item ID of the item at position \\fIy\\fR.\n.TP\n\\fIpathname \\fBidentify column \\fIx y\\fR\n.\nReturns the display column identifier of the cell at position \\fIx\\fR.\nThe tree column has ID \\fB#0\\fR.\n.TP\n\\fIpathname \\fBidentify cell \\fIx y\\fR\n.\nReturns the cell identifier of the cell at position \\fIx y\\fR.\nA cell identifier is a list of item ID and column ID.\n.TP\n\\fIpathname \\fBidentify element \\fIx y\\fR\n.\nThe element at position \\fIx,y\\fR.\n.TP\n\\fIpathname \\fBidentify row \\fIx y\\fR\n.\nObsolescent synonym for \\fIpathname \\fBidentify item\\fR.\n.PP\nSee \\fBCOLUMN IDENTIFIERS\\fR for a discussion of display columns\nand data columns.\n.RE\n.\\\" METHOD: index\n.TP\n\\fIpathname \\fBindex \\fIitem\\fR\n.\nReturns the integer index of \\fIitem\\fR within its parent's list of children.\n.\\\" METHOD: insert\n.TP\n\\fIpathname \\fBinsert \\fIparent index\\fR ?\\fB\\-id \\fIid\\fR? \\fIoptions...\\fR\n.\nCreates a new item.\n\\fIparent\\fR is the item ID of the parent item,\nor the empty string \\fB{}\\fR\nto create a new top-level item.\n\\fIindex\\fR is an integer, or the value \\fBend\\fR, specifying where in the\nlist of \\fIparent\\fR's children to insert the new item.\nIf \\fIindex\\fR is negative or zero,\nthe new node is inserted at the beginning;\nif \\fIindex\\fR is greater than or equal to the current number of children,\nit is inserted at the end.\nIf \\fB\\-id\\fR is specified, it is used as the item identifier;\n\\fIid\\fR must not already exist in the tree.\nOtherwise, a new unique identifier is generated.\n.RS\n.PP\n\\fIpathname \\fBinsert\\fR returns the item identifier of the\nnewly created item.\nSee \\fBITEM OPTIONS\\fR for the list of available options.\n.RE\n.\\\" METHOD: item\n.TP\n\\fIpathname \\fBitem \\fIitem\\fR ?\\fI\\-option \\fR?\\fIvalue \\-option value...\\fR?\n.\nQuery or modify the options for the specified \\fIitem\\fR.\nIf no \\fI\\-option\\fR is specified,\nreturns a dictionary of option/value pairs.\nIf a single \\fI\\-option\\fR is specified,\nreturns the value of that option.\nOtherwise, the item's options are updated with the specified values.\nSee \\fBITEM OPTIONS\\fR for the list of available options.\n.\\\" METHOD: move\n.TP\n\\fIpathname \\fBmove \\fIitem parent index\\fR\n.\nMoves \\fIitem\\fR to position \\fIindex\\fR in \\fIparent\\fR's list of children.\nIt is illegal to move an item under one of its descendants.\n.RS\n.PP\nIf \\fIindex\\fR is negative or zero, \\fIitem\\fR is moved\nto the beginning; if greater than or equal to the number of children,\nit is moved to the end.\n.RE\n.\\\" METHOD: next\n.TP\n\\fIpathname \\fBnext \\fIitem\\fR\n.\nReturns the identifier of \\fIitem\\fR's next sibling,\nor \\fB{}\\fR if \\fIitem\\fR is the last child of its parent.\n.\\\" METHOD: parent\n.TP\n\\fIpathname \\fBparent \\fIitem\\fR\n.\nReturns the ID of the parent of \\fIitem\\fR,\nor \\fB{}\\fR if \\fIitem\\fR is at the top level of the hierarchy.\n.\\\" METHOD: prev\n.TP\n\\fIpathname \\fBprev \\fIitem\\fR\n.\nReturns the identifier of \\fIitem\\fR's previous sibling,\nor \\fB{}\\fR if \\fIitem\\fR is the first child of its parent.\n.\\\" METHOD: see\n.TP\n\\fIpathname \\fBsee \\fIitem\\fR\n.\nEnsure that \\fIitem\\fR is visible:\nsets all of \\fIitem\\fR's ancestors to \\fB\\-open true\\fR,\nand scrolls the widget if necessary so that \\fIitem\\fR is\nwithin the visible portion of the tree.\n.\\\" METHOD: selection\n.TP\n\\fIpathname \\fBselection\\fR ?\\fIselop itemList\\fR?\n.\nManages item selection. Item selection is independent from cell selection\nhandled by the \\fBcellselection\\fR command.\nIf \\fIselop\\fR is not specified, returns the list of selected items.\nOtherwise, \\fIselop\\fR is one of the following:\n.RS\n.TP\n\\fIpathname \\fBselection set \\fIitemList\\fR\n.\n\\fIitemList\\fR becomes the new selection.\n.TP\n\\fIpathname \\fBselection add \\fIitemList\\fR\n.\nAdd \\fIitemList\\fR to the selection.\n.TP\n\\fIpathname \\fBselection remove \\fIitemList\\fR\n.\nRemove \\fIitemList\\fR from the selection.\n.TP\n\\fIpathname \\fBselection toggle \\fIitemList\\fR\n.\nToggle the selection state of each item in \\fIitemList\\fR.\n.RE\n.\\\" METHOD: set\n.TP\n\\fIpathname \\fBset \\fIitem\\fR ?\\fIcolumn\\fR? ?\\fIvalue\\fR?\n.\nWith one argument, returns a dictionary of column/value pairs\nfor the specified \\fIitem\\fR.\nWith two arguments, returns the current value of the specified \\fIcolumn\\fR.\nWith three arguments, sets the value of column \\fIcolumn\\fR\nin item \\fIitem\\fR to the specified \\fIvalue\\fR.\nSee also \\fBCOLUMN IDENTIFIERS\\fR.\n.\\\" METHOD: tag\n.TP\n\\fIpathName \\fBtag \\fIargs...\\fR\n.\nManages tags. Tags can be set on items as well as on cells.\nThe set of tags is shared between items and cells. However item tagging is\nindependent from cell tagging (for instance adding a tag on an item does\nnot also add this tag on the cells in that item). Cell tags take precedence\nover item tags when drawing.\nThe following subcommands are supported:\n.RS\n.TP\n\\fIpathName \\fBtag add \\fItag items\\fR\n.\nAdds the specified \\fItag\\fR to each of the listed \\fIitems\\fR.\nIf \\fItag\\fR is already present for a particular item,\nthen the \\fB\\-tags\\fR for that item are unchanged.\n.TP\n\\fIpathName \\fBtag bind \\fItagName \\fR?\\fIsequence\\fR? ?\\fIscript\\fR?\n.\nAdd a Tk binding script for the event sequence \\fIsequence\\fR\nto the tag \\fItagName\\fR. When an X event is delivered to an item,\nbinding scripts for each of the item's \\fB\\-tags\\fR are evaluated\nin order as per \\fIbindtags(n)\\fR.\nIf the event can be associated with a cell (i.e. mouse events) any\nbindings for the cell's \\fB\\-tags\\fR are evaluated as well.\n.RS\n.PP\n\\fB\\fR, \\fB\\fR, and virtual events\nare sent to the focus item.\n\\fB