tk9.0.3/0000755001000000100000000000000015105111006015030 5ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmanstk9.0.3/.github/0000755001000000100000000000000015105111006016370 5ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmanstk9.0.3/.github/workflows/0000755001000000100000000000000015105111007020426 5ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmanstk9.0.3/.github/workflows/linux-build.yml0000664001000000100000000001357115105057705023434 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmansname: Linux on: push: branches: - "main" - "core-9-0-branch" tags: - "core-*" permissions: contents: read defaults: run: shell: bash working-directory: tk/unix env: ERROR_ON_FAILURES: 1 jobs: build: runs-on: ubuntu-22.04 strategy: matrix: compiler: - "gcc" - "clang" config: - "" - "CFLAGS=-DTK_NO_DEPRECATED=1" - "--disable-shared" - "--disable-xft" - "--disable-xss" - "--enable-symbols" steps: - name: Checkout Tk uses: actions/checkout@v5 with: path: tk - name: Checkout Tcl 9.0 uses: actions/checkout@v5 with: repository: tcltk/tcl ref: core-9-0-branch path: tcl - name: Setup Environment (compiler=${{ matrix.compiler }}) run: | sudo apt-get install libxss-dev libxft-dev mkdir "$HOME/install dir" touch tk/doc/man.macros tk/generic/tkStubInit.c echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV echo "CC=$COMPILER" >> $GITHUB_ENV echo "TOOL_DIR=$(cd tcl/tools;pwd)" >> $GITHUB_ENV echo "BUILD_CONFIG_ID=$OPTS" >> $GITHUB_ENV working-directory: "." env: CFGOPT: ${{ matrix.config }} COMPILER: ${{ matrix.compiler }} OPTS: ${{ matrix.compiler }}${{ matrix.config }} - name: Configure and Build Tcl run: | ./configure $CFGOPT "--prefix=$HOME/install dir" || { cat config.log echo "::warning::Failure during Tcl Configure" exit 1 } make all install || { echo "::warning::Failure during Tcl Build" exit 1 } echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV working-directory: tcl/unix - name: Configure (opts=${{ matrix.config }}) run: | ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || { cat config.log echo "::error::Failure during Configure" exit 1 } - name: Build run: | make binaries libraries || { echo "::error::Failure during Build" exit 1 } - name: Build Test Harness run: | make tktest || { echo "::error::Failure during Build" exit 1 } - name: Test-Drive Installation run: | make install || { echo "::error::Failure during Install" exit 1 } - name: Create Distribution Package run: | make dist || { echo "::error::Failure during Distribute" exit 1 } - name: Convert Documentation to HTML run: | make html-tk TOOL_DIR=$TOOL_DIR || { echo "::error::Failure during Distribute" exit 1 } - name: Discover Version ID if: ${{ env.BUILD_CONFIG_ID == 'gcc' }} run: | cd /tmp/dist echo "VERSION=`ls -d tk* | sed 's/tk//'`" >> $GITHUB_ENV - name: Upload Source Distribution if: ${{ env.BUILD_CONFIG_ID == 'gcc' }} uses: actions/upload-artifact@v5 with: name: Tk ${{ env.VERSION }} Source distribution (snapshot) path: | /tmp/dist/tk* !/tmp/dist/tk*/html/** - name: Upload Documentation Distribution if: ${{ env.BUILD_CONFIG_ID == 'gcc' }} uses: actions/upload-artifact@v5 with: name: Tk ${{ env.VERSION }} HTML documentation (snapshot) path: /tmp/dist/tk*/html test: runs-on: ubuntu-22.04 strategy: matrix: compiler: - "gcc" config: - "" - "--disable-xft" - "--enable-symbols" steps: - name: Checkout Tk uses: actions/checkout@v5 with: path: tk - name: Checkout Tcl 9.0 uses: actions/checkout@v5 with: repository: tcltk/tcl ref: core-9-0-branch path: tcl - name: Setup Environment (compiler=${{ matrix.compiler }}) run: | sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev xfonts-75dpi xfonts-100dpi xfonts-scalable libxfont2 unifont mkdir "$HOME/install dir" touch tk/doc/man.macros tk/generic/tkStubInit.c echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV echo "CC=$COMPILER" >> $GITHUB_ENV working-directory: "." env: CFGOPT: ${{ matrix.config }} COMPILER: ${{ matrix.compiler }} - name: Configure and Build Tcl run: | ./configure $CFGOPT "--prefix=$HOME/install dir" || { cat config.log echo "::warning::Failure during Tcl Configure" exit 1 } make all install || { echo "::warning::Failure during Tcl Build" exit 1 } echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV working-directory: tcl/unix - name: Configure ${{ matrix.config }} run: | ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || { cat config.log echo "::error::Failure during Configure" exit 1 } - name: Build run: | make binaries libraries tktest || { echo "::error::Failure during Build" exit 1 } - name: Run Tests run: | xvfb-run --auto-servernum make test-classic | tee out-classic.txt xvfb-run --auto-servernum make test-ttk | tee out-ttk.txt grep -q "Failed 0" out-classic.txt || { echo "::error::Failure during Test" exit 1 } grep -q "Failed 0" out-ttk.txt || { echo "::error::Failure during Test" exit 1 } timeout-minutes: 10 tk9.0.3/.github/workflows/linux-with-tcl91-build.yml0000664001000000100000000001222015105057705025325 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmansname: Linux (with Tcl 9.1) on: push: branches: - "main" - "core-9-0-branch" tags: - "core-**" permissions: contents: read defaults: run: shell: bash working-directory: tk/unix env: ERROR_ON_FAILURES: 1 jobs: build: runs-on: ubuntu-22.04 strategy: matrix: compiler: - "gcc" - "clang" config: - "" - "CFLAGS=-DTK_NO_DEPRECATED=1" - "--disable-shared" - "--disable-xft" - "--disable-xss" - "--enable-symbols" steps: - name: Checkout uses: actions/checkout@v5 with: path: tk - name: Checkout Tcl 9.1 uses: actions/checkout@v5 with: repository: tcltk/tcl ref: main path: tcl - name: Setup Environment (compiler=${{ matrix.compiler }}) run: | sudo apt-get install libxss-dev libxft-dev mkdir "$HOME/install dir" touch tk/doc/man.macros tk/generic/tkStubInit.c echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV echo "CC=$COMPILER" >> $GITHUB_ENV echo "TOOL_DIR=$(cd tcl/tools;pwd)" >> $GITHUB_ENV echo "BUILD_CONFIG_ID=$OPTS" >> $GITHUB_ENV working-directory: "." env: CFGOPT: ${{ matrix.config }} COMPILER: ${{ matrix.compiler }} OPTS: ${{ matrix.compiler }}${{ matrix.config }} - name: Configure and Build Tcl run: | ./configure $CFGOPT "--prefix=$HOME/install dir" || { cat config.log echo "::warning::Failure during Tcl Configure" exit 1 } make all install || { echo "::warning::Failure during Tcl Build" exit 1 } echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV working-directory: tcl/unix - name: Configure (opts=${{ matrix.config }}) run: | ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || { cat config.log echo "::error::Failure during Configure" exit 1 } - name: Build run: | make binaries libraries || { echo "::error::Failure during Build" exit 1 } - name: Build Test Harness run: | make tktest || { echo "::error::Failure during Build" exit 1 } - name: Test-Drive Installation run: | make install || { echo "::error::Failure during Install" exit 1 } - name: Create Distribution Package run: | make dist || { echo "::error::Failure during Distribute" exit 1 } - name: Convert Documentation to HTML run: | make html-tk TOOL_DIR=$TOOL_DIR || { echo "::error::Failure during Distribute" exit 1 } test: runs-on: ubuntu-22.04 strategy: matrix: compiler: - "gcc" config: - "" - "--disable-xft" - "--enable-symbols" steps: - name: Checkout uses: actions/checkout@v5 with: path: tk - name: Checkout Tcl 9.1 uses: actions/checkout@v5 with: repository: tcltk/tcl ref: main path: tcl - name: Setup Environment (compiler=${{ matrix.compiler }}) run: | sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev xfonts-75dpi xfonts-100dpi xfonts-scalable libxfont2 unifont mkdir "$HOME/install dir" touch tk/doc/man.macros tk/generic/tkStubInit.c echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV echo "CC=$COMPILER" >> $GITHUB_ENV working-directory: "." env: CFGOPT: ${{ matrix.config }} COMPILER: ${{ matrix.compiler }} - name: Configure and Build Tcl run: | ./configure $CFGOPT "--prefix=$HOME/install dir" || { cat config.log echo "::warning::Failure during Tcl Configure" exit 1 } make all install || { echo "::warning::Failure during Tcl Build" exit 1 } echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV working-directory: tcl/unix - name: Configure ${{ matrix.config }} run: | ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || { cat config.log echo "::error::Failure during Configure" exit 1 } - name: Build run: | make binaries libraries tktest || { echo "::error::Failure during Build" exit 1 } - name: Run Tests run: | xvfb-run --auto-servernum make test-classic | tee out-classic.txt xvfb-run --auto-servernum make test-ttk | tee out-ttk.txt grep -q "Failed 0" out-classic.txt || { echo "::error::Failure during Test" exit 1 } grep -q "Failed 0" out-ttk.txt || { echo "::error::Failure during Test" exit 1 } timeout-minutes: 15 tk9.0.3/.github/workflows/mac-build.yml0000664001000000100000000001147215105057705023033 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmansname: macOS on: push: branches: - "main" - "core-9-0-branch" tags: - "core-*" permissions: contents: read env: ERROR_ON_FAILURES: 1 jobs: framework: runs-on: macos-15 defaults: run: shell: bash working-directory: tk/macosx steps: - name: Checkout Tk uses: actions/checkout@v5 with: path: tk - name: Check out Tcl 9.0 uses: actions/checkout@v5 with: repository: tcltk/tcl ref: core-9-0-branch path: tcl - name: Prepare checked out repositories run: | touch tk/generic/tkStubInit.c mkdir build echo "BUILD_DIR=`cd build && pwd`" >> $GITHUB_ENV echo "DESTDIR=`cd build && pwd`" >> $GITHUB_ENV working-directory: . - name: Build Tcl run: | make all working-directory: tcl/macosx - name: Build run: | make all install || { echo "::error::Failure during Build" exit 1 } - name: Run Tests run: | make TK_NO_STDERR=1 test | tee out.txt nmatches=$( grep -c "Failed 0" out.txt ) if [ $nmatches -lt 4 ] then echo "::error::Failure during Test" exit 1 fi timeout-minutes: 30 prefix: runs-on: macos-15 strategy: matrix: symbols: - 'no' - 'mem' options: - '--enable-aqua' - '--disable-aqua' defaults: run: shell: bash working-directory: tk/unix steps: - name: Checkout Tk uses: actions/checkout@v5 with: path: tk - name: Check out Tcl 9.0 uses: actions/checkout@v5 with: repository: tcltk/tcl ref: core-9-0-branch path: tcl - name: Prepare checked out repositories env: SET_DISPLAY: ${{ contains(matrix.options, '--disable-aqua') }} run: | touch tkStubInit.c mkdir "$HOME/install dir" echo "USE_XVFB=$SET_DISPLAY" >> $GITHUB_ENV working-directory: tk/generic - name: Add X11 (if required) if: ${{ env.USE_XVFB == 'true' }} run: | brew install --cask xquartz sudo /opt/X11/libexec/privileged_startx || true working-directory: . - name: Build Tcl run: | ./configure $CFGOPT --disable-zipfs "--prefix=$HOME/install dir" || { cat config.log echo "::error::Failure during Tcl Configure" exit 1 } make all || { echo "::error::Failure during Tcl Build" exit 1 } make install || { echo "::error::Failure during Tcl Install" exit 1 } working-directory: tcl/unix env: CFGOPT: --enable-symbols=${{ matrix.symbols }} - name: Configure (symbols=${{ matrix.symbols }} ${{matrix.options }}) run: | ./configure $CFGOPT --disable-zipfs "--prefix=$HOME/install dir" --disable-xft || { cat config.log echo "::error::Failure during Configure" exit 1 } env: CFGOPT: --enable-symbols=${{ matrix.symbols }} ${{matrix.options }} - name: Build run: | make all tktest || { echo "::error::Failure during Build" exit 1 } - name: Run Tests run: | if [ $USE_XVFB == true ]; then function runXvfb { PATH=$PATH:/opt/X11/bin Xvfb $1 & XVFB_PID=$! echo Launched Xvfb $1 as process $XVFB_PID >&2 trap "echo killing process $XVFB_PID... >&2; kill $XVFB_PID" 0 export DISPLAY=$1 sleep 2 } else function runXvfb { echo Xvfb not used, this is a --enable-aqua build export TK_NO_STDERR=1 } fi ( runXvfb :0; make test-classic; exit $? ) | tee out-classic.txt || { echo "::error::Failure during Test (classic)" exit 1 } ( runXvfb :0; make test-ttk; exit $? ) | tee out-ttk.txt || { echo "::error::Failure during Test (ttk)" exit 1 } cat out-classic.txt | grep -q "Failed 0" || { echo "::error::Failure in classic test results" exit 1 } cat out-ttk.txt | grep -q "Failed 0" || { echo "::error::Failure in ttk test results" exit 1 } timeout-minutes: 20 - name: Carry out trial installation run: | make install || { cat config.log echo "::error::Failure during Install" exit 1 } tk9.0.3/.github/workflows/onefiledist.yml0000664001000000100000000001654215105057705023506 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmansname: Build Binaries on: push: branches: - "main" - "core-9-0-branch" tags: - "core-**" permissions: contents: read jobs: linux: name: Linux runs-on: ubuntu-22.04 defaults: run: shell: bash env: CC: gcc CFGOPT: --disable-symbols --disable-shared steps: - name: Checkout Tk uses: actions/checkout@v5 with: path: tk - name: Checkout Tcl 9.0 uses: actions/checkout@v5 with: repository: tcltk/tcl ref: core-9-0-branch path: tcl - name: Setup Environment run: | sudo apt-get install libxss-dev libxft-dev touch tcl/generic/tclStubInit.c tcl/generic/tclOOStubInit.c touch tk/generic/tkStubInit.c echo "INST_DIR=$(cd install;pwd)" >> $GITHUB_ENV echo "VER_PATH=$(cd tcl/tools; pwd)/addVerToFile.tcl" >> $GITHUB_ENV working-directory: "." - name: Configure Tcl run: | ./configure $CFGOPT --prefix=$INST_DIR working-directory: tcl/unix - name: Build & Install Tcl run: | make binaries libraries install make shell SCRIPT="$VER_PATH $GITHUB_ENV" working-directory: tcl/unix - name: Configure Tk run: | ./configure $CFGOPT --with-tcl=$INST_DIR/lib --prefix=$INST_DIR working-directory: tk/unix - name: Build & Install Tk run: | make binaries libraries install working-directory: tk/unix # TODO: need the Tk version separately for distro naming below - name: Package run: | cp bin/wish9.0 ${BUILD_NAME} chmod +x ${BUILD_NAME} tar -cf ${BUILD_NAME}.tar ${BUILD_NAME} working-directory: ${{ env.INST_DIR }} env: BUILD_NAME: wish${{ env.TCL_PATCHLEVEL }}_snapshot - name: Upload uses: actions/upload-artifact@v5 with: name: Wish ${{ env.TCL_PATCHLEVEL }} Linux single-file build (snapshot) path: ${{ env.INST_DIR }}/*.tar - name: Describe Installation Zip Contents if: ${{ always() }} run: | unzip -l wish${{ env.TCL_PATCHLEVEL }}_snapshot || true working-directory: ${{ env.INST_DIR }} macos: name: macOS runs-on: macos-15-intel defaults: run: shell: bash env: CC: gcc CFGOPT: --disable-symbols --disable-shared steps: - name: Checkout Tk uses: actions/checkout@v5 with: path: tk - name: Checkout Tcl 9.0 uses: actions/checkout@v5 with: repository: tcltk/tcl ref: core-9-0-branch path: tcl - name: Checkout create-dmg uses: actions/checkout@v5 with: repository: create-dmg/create-dmg ref: v1.2.2 path: create-dmg - name: Prepare run: | mkdir -p install/contents touch tcl/generic/tclStubInit.c tcl/generic/tclOOStubInit.c || true touch tk/generic/tkStubInit.c || true wget https://github.com/culler/macher/releases/download/v1.8/macher sudo cp macher /usr/local/bin sudo chmod a+x /usr/local/bin/macher echo "INST_DIR=$(cd install;pwd)" >> $GITHUB_ENV echo "VER_PATH=$(cd tcl/tools; pwd)/addVerToFile.tcl" >> $GITHUB_ENV echo "CREATE_DMG=$(cd create-dmg;pwd)/create-dmg" >> $GITHUB_ENV echo "CFLAGS=-arch x86_64 -arch arm64" >> $GITHUB_ENV working-directory: "." - name: Configure Tcl run: | ./configure $CFGOPT --prefix=$INST_DIR working-directory: tcl/unix - name: Build & Install Tcl run: | make binaries libraries install make shell SCRIPT="$VER_PATH $GITHUB_ENV" working-directory: tcl/unix - name: Configure Tk run: | ./configure $CFGOPT --with-tcl=$INST_DIR/lib --prefix=$INST_DIR \ --enable-aqua working-directory: tk/unix - name: Build & Install Tk run: | make binaries libraries install working-directory: tk/unix # TODO: need the Tk version separately for distro naming below - name: Package run: | cp ../tk/unix/wish contents/${BUILD_NAME} chmod +x contents/${BUILD_NAME} cat > contents/README.txt <> $GITHUB_ENV echo "VER_PATH=$(cd tcl/tools; pwd)/addVerToFile.tcl" >> $GITHUB_ENV working-directory: "." - name: Configure Tcl run: | ./configure $CFGOPT --prefix=$INST_DIR working-directory: tcl/win - name: Build & Install Tcl run: | make binaries libraries install $INST_DIR/bin/tclsh* $VER_PATH $GITHUB_ENV working-directory: tcl/win - name: Configure Tk run: | ./configure $CFGOPT --with-tcl=$INST_DIR/lib --prefix=$INST_DIR working-directory: tk/win - name: Build & Install Tk run: | make all install echo "TK_BIN=`pwd`/`echo wish*.exe`" >> $GITHUB_ENV working-directory: tk/win # TODO: need the Tk version separately for distro naming below - name: Package run: | cp ${TK_BIN} combined/${BUILD_NAME}.exe working-directory: install env: BUILD_NAME: wish${{ env.TCL_PATCHLEVEL }}_snapshot - name: Upload uses: actions/upload-artifact@v5 with: name: Wish ${{ env.TCL_PATCHLEVEL }} Windows single-file build (snapshot) path: install/combined/wish${{ env.TCL_PATCHLEVEL }}_snapshot.exe tk9.0.3/.github/workflows/win-build.yml0000664001000000100000000001226015105057705023064 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmansname: Windows on: push: branches: - "main" - "core-9-0-branch" tags: - "core-*" permissions: contents: read env: ERROR_ON_FAILURES: 1 jobs: msvc: runs-on: windows-2022 defaults: run: shell: powershell working-directory: tk/win # Using powershell means we need to explicitly stop on failure strategy: matrix: config: - "" - "OPTS=symbols" - "OPTS=static" steps: - name: Checkout Tk uses: actions/checkout@v5 with: path: tk - name: Checkout Tcl 9.0 uses: actions/checkout@v5 with: repository: tcltk/tcl ref: core-9-0-branch path: tcl - name: Init MSVC uses: ilammy/msvc-dev-cmd@v1 - name: Make Install Location working-directory: tcl run: | echo "TCLDIR=`pwd`" >> $GITHUB_ENV cd .. mkdir install cd install echo "INSTALLDIR=`pwd`" >> $GITHUB_ENV - name: Build Tcl (${{ matrix.config }}) run: | &nmake -f makefile.vc release install ${{ matrix.config }} if ($lastexitcode -ne 0) { throw "nmake exit code: $lastexitcode" } working-directory: tcl/win - name: Build Tk (${{ matrix.config }}) run: | &nmake -f makefile.vc all ${{ matrix.config }} if ($lastexitcode -ne 0) { throw "nmake exit code: $lastexitcode" } - name: Build Test Harness (${{ matrix.config }}) run: | &nmake -f makefile.vc tktest ${{ matrix.config }} if ($lastexitcode -ne 0) { throw "nmake exit code: $lastexitcode" } - name: Run Tk Tests (${{ matrix.config }}) run: | nmake -f makefile.vc test-classic ${{ matrix.config }} | tee out-classic.txt || { echo "::error::Failure during Test" exit 1 } nmake -f makefile.vc test-ttk ${{ matrix.config }} | tee out-ttk.txt || { echo "::error::Failure during Test" exit 1 } grep -q "Failed 0" out-classic.txt || { echo "::error::Failure during Test" exit 1 } grep -q "Failed 0" out-ttk.txt || { echo "::error::Failure during Test" exit 1 } env: CI_BUILD_WITH_MSVC: 1 shell: bash timeout-minutes: 10 - name: Build Help (${{ matrix.config }}) run: | &nmake -f makefile.vc htmlhelp ${{ matrix.config }} if ($lastexitcode -ne 0) { throw "nmake exit code: $lastexitcode" } - name: Install (${{ matrix.config }}) run: | &nmake -f makefile.vc install ${{ matrix.config }} if ($lastexitcode -ne 0) { throw "nmake exit code: $lastexitcode" } gcc: runs-on: windows-2022 defaults: run: shell: msys2 {0} working-directory: win strategy: matrix: config: - "" - "--enable-symbols=mem" - "--enable-symbols=all" - "--disable-shared" steps: - name: Install MSYS2 uses: msys2/setup-msys2@v2 with: msystem: MINGW64 install: git mingw-w64-x86_64-toolchain make zip - name: Checkout Tk uses: actions/checkout@v5 - name: Checkout Tcl 9.0 uses: actions/checkout@v5 with: repository: tcltk/tcl ref: core-9-0-branch path: tcl - name: Prepare run: | touch tkStubInit.c touch "${HOME}/forWinDialog-5.12.7" mkdir "${HOME}/install_dir" echo "INSTALL_DIR=${HOME}/install_dir" >> $GITHUB_ENV working-directory: generic - name: Configure and Build Tcl (${{ matrix.config }}) run: | ./configure $CFGOPT "--prefix=$INSTALL_DIR" || { cat config.log echo "::warning::Failure during Tcl Configure" exit 1 } make all install || { echo "::warning::Failure during Tcl Build" exit 1 } echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV env: CFGOPT: --enable-64bit ${{ matrix.config }} working-directory: tcl/win - name: Configure Tk (${{ matrix.config }}) run: | ./configure $CFGOPT "--prefix=$HOME/INSTALL_DIR" "--with-tcl=$TCL_CONFIG_PATH" || { cat config.log echo "::error::Failure during Configure" exit 1 } env: CFGOPT: --enable-64bit ${{ matrix.config }} - name: Build Tk run: | make all install tktest || { echo "::error::Failure during Build" exit 1 } - name: Run Tk Tests run: | make test-classic | tee out-classic.txt make test-ttk | tee out-ttk.txt grep -q "Failed 0" out-classic.txt || { echo "::error::Failure during Test" exit 1 } grep -q "Failed 0" out-ttk.txt || { echo "::error::Failure during Test" exit 1 } timeout-minutes: 10 tk9.0.3/bitmaps/0000755001000000100000000000000015105110233016470 5ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmanstk9.0.3/bitmaps/error.xbm0000644001000000100000000000062715105110232020335 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans#define error_width 17 #define error_height 17 static unsigned char error_bits[] = { 0xf0, 0x0f, 0x00, 0x58, 0x15, 0x00, 0xac, 0x2a, 0x00, 0x16, 0x50, 0x00, 0x2b, 0xa0, 0x00, 0x55, 0x40, 0x01, 0xa3, 0xc0, 0x00, 0x45, 0x41, 0x01, 0x83, 0xc2, 0x00, 0x05, 0x45, 0x01, 0x03, 0xca, 0x00, 0x05, 0x74, 0x01, 0x0a, 0xa8, 0x00, 0x14, 0x58, 0x00, 0xe8, 0x2f, 0x00, 0x50, 0x15, 0x00, 0xa0, 0x0a, 0x00}; tk9.0.3/bitmaps/gray12.xbm0000644001000000100000000000044215105110232020304 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans#define gray12_width 16 #define gray12_height 16 static unsigned char gray12_bits[] = { 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88}; tk9.0.3/bitmaps/gray25.xbm0000644001000000100000000000044215105110232020310 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans#define gray25_width 16 #define gray25_height 16 static unsigned char gray25_bits[] = { 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22}; tk9.0.3/bitmaps/gray50.xbm0000644001000000100000000000044215105110232020306 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans#define gray50_width 16 #define gray50_height 16 static unsigned char gray50_bits[] = { 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa}; tk9.0.3/bitmaps/gray75.xbm0000644001000000100000000000044215105110232020315 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans#define gray75_width 16 #define gray75_height 16 static unsigned char gray75_bits[] = { 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd}; tk9.0.3/bitmaps/hourglass.xbm0000644001000000100000000000075615105110233021217 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans#define hourglass_width 19 #define hourglass_height 21 static unsigned char hourglass_bits[] = { 0xff, 0xff, 0x07, 0x55, 0x55, 0x05, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xc2, 0x0a, 0x03, 0x46, 0x05, 0x01, 0x82, 0x0a, 0x03, 0x06, 0x05, 0x01, 0x02, 0x03, 0x03, 0x86, 0x05, 0x01, 0xc2, 0x0a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0xff, 0xff, 0x07, 0xab, 0xaa, 0x02}; tk9.0.3/bitmaps/info.xbm0000644001000000100000000000032615105110233020134 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans#define info_width 8 #define info_height 21 static unsigned char info_bits[] = { 0x3c, 0x2a, 0x16, 0x2a, 0x14, 0x00, 0x00, 0x3f, 0x15, 0x2e, 0x14, 0x2c, 0x14, 0x2c, 0x14, 0x2c, 0x14, 0x2c, 0xd7, 0xab, 0x55}; tk9.0.3/bitmaps/questhead.xbm0000644001000000100000000000100015105110233021152 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans#define questhead_width 20 #define questhead_height 22 static unsigned char questhead_bits[] = { 0xf8, 0x1f, 0x00, 0xac, 0x2a, 0x00, 0x56, 0x55, 0x00, 0xeb, 0xaf, 0x00, 0xf5, 0x5f, 0x01, 0xfb, 0xbf, 0x00, 0x75, 0x5d, 0x01, 0xfb, 0xbe, 0x02, 0x75, 0x5d, 0x05, 0xab, 0xbe, 0x0a, 0x55, 0x5f, 0x07, 0xab, 0xaf, 0x00, 0xd6, 0x57, 0x01, 0xac, 0xab, 0x00, 0xd8, 0x57, 0x00, 0xb0, 0xaa, 0x00, 0x50, 0x55, 0x00, 0xb0, 0x0b, 0x00, 0xd0, 0x17, 0x00, 0xb0, 0x0b, 0x00, 0x58, 0x15, 0x00, 0xa8, 0x2a, 0x00}; tk9.0.3/bitmaps/question.xbm0000644001000000100000000000113215105110233021044 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans#define question_width 17 #define question_height 27 static unsigned char question_bits[] = { 0xf0, 0x0f, 0x00, 0x58, 0x15, 0x00, 0xac, 0x2a, 0x00, 0x56, 0x55, 0x00, 0x2b, 0xa8, 0x00, 0x15, 0x50, 0x01, 0x0b, 0xa0, 0x00, 0x05, 0x60, 0x01, 0x0b, 0xa0, 0x00, 0x05, 0x60, 0x01, 0x0b, 0xb0, 0x00, 0x00, 0x58, 0x01, 0x00, 0xaf, 0x00, 0x80, 0x55, 0x00, 0xc0, 0x2a, 0x00, 0x40, 0x15, 0x00, 0xc0, 0x02, 0x00, 0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x00, 0x00, 0x00, 0x80, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x00, 0x01, 0x00}; tk9.0.3/bitmaps/warning.xbm0000644001000000100000000000032315105110233020643 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans#define warning_width 6 #define warning_height 19 static unsigned char warning_bits[] = { 0x0c, 0x16, 0x2b, 0x15, 0x2b, 0x15, 0x2b, 0x16, 0x0a, 0x16, 0x0a, 0x16, 0x0a, 0x00, 0x00, 0x1e, 0x0a, 0x16, 0x0a}; tk9.0.3/changes.md0000644001000000100000000002427015105071214016775 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans The source code for Tk is managed by fossil. Tk developers coordinate all changes to the Tk source code at > [Tk Source Code](https://core.tcl-lang.org/tk/) Release Tk 9.0.3 arises from the check-in with tag `core-9-0-3`. Tk 9.0.3 continues the Tk 9.0 series of releases. The Tk 9.0 series does not support Tcl 8.6. The Tk 9.0 series extends the Tcl 9.0 series. To make use of Tk 9.0.3, first a Tcl 9.0 release must be present. As new Tk features are developed, expect them to appear in Tk 9, but not necessarily in Tk 8. Tk patch releases have the primary purpose of delivering bug fixes to the userbase. # Bug fixes - [Pressing Alt- triggers an error popup](https://core.tcl-lang.org/tk/tktview/a30d3e) - [error popup on ttk::scale with invisible trough](https://core.tcl-lang.org/tk/tktview/d25b72) - [loading windows dll's in Cygwin doesn't work with high-entropy-va](https://core.tcl-lang.org/tk/tktview/06892c) - [TIP 604 widget demo: canvas text fill color not specified](https://core.tcl-lang.org/tk/tktview/6cc48b) - [Undefined behavior while touchpad scrolling](https://core.tcl-lang.org/tk/tktview/92e408) - [leak in XCreateBitmapFromData() in ImgGetPhoto()](https://core.tcl-lang.org/tk/tktview/6c4795) - [Add support for Copy/Cut/Paste keys in X11](https://core.tcl-lang.org/tk/tktview/04e173) - [Aqua: compiler warning in tkMacOSXImage.c](https://core.tcl-lang.org/tk/tktview/7f3751) - [tkpWinRopModes[GXnoop] is R2_NOT, should be R2_NOP](https://core.tcl-lang.org/tk/tktview/95da0f) - [image svg: support paint order and fix possible nan race condition](https://core.tcl-lang.org/tk/tktview/b43dbc) - [Windows: install man pages](https://core.tcl-lang.org/tk/tktview/816739) - [Windows: install pkg-config file](https://core.tcl-lang.org/tk/tktview/2c240b) - [Windows: Missing border pixels in alt theme](https://core.tcl-lang.org/tk/tktview/8b725d) - [nanosvg upstream changes: #273, #275: add paint order parsing](https://core.tcl-lang.org/tk/tktview/b43dbc0061) - [Artifacts in a few themed widgets on x11 and aqua](https://core.tcl-lang.org/tk/tktview/265ff2) - [Core dump Tk_GetFontFromObj](https://core.tcl-lang.org/tk/tktview/a80e5f) - [MS-Win canvas arcs with small extent are drawn 360 degrees](https://core.tcl-lang.org/tk/info/6051a9) - [pixel values can report false list lengths](https://core.tcl-lang.org/tk/info/2a0a83) - [Xft text is unusable for 32-bit visual when default visual is 24-bit](https://core.tcl-lang.org/tk/info/c23f79) - [tk print: several issues printing i18n text](https://core.tcl-lang.org/tk/info/4e7a78) - [tk print, canvas: raw smooth not implemented](https://core.tcl-lang.org/tk/info/e10819) - [Aqua: avoid use-after-free during RefocusGrabWindow()](https://core.tcl-lang.org/tk/info/6da885) - [Aqua: ttk::notebook tabs](https://core.tcl-lang.org/tk/info/cf296a) - [Fix crash on exit due to faulty asm code in DllMain](https://core.tcl-lang.org/tk/info/44b34c) Release Tk 9.0.2 arises from the check-in with tag `core-9-0-2`. Tk 9.0.2 continues the Tk 9.0 series of releases. The Tk 9.0 series does not support Tcl 8.6. The Tk 9.0 series extends the Tcl 9.0 series. To make use of Tk 9.0.2, first a Tcl 9.0 release must be present. As new Tk features are developed, expect them to appear in Tk 9, but not necessarily in Tk 8. Tk patch releases have the primary purpose of delivering bug fixes to the userbase. ## Improved widget appearance - [Visible grip element added in ttk::panedwindow sashes of most built-in themes](https://core.tcl-lang.org/tk/tktview/9902d8) # Bug fixes - [inaccurate scrollbar error-message](https://core.tcl-lang.org/tk/tktview/f88118) - [Build tk 9.0.1 failed on macos 10.13](https://core.tcl-lang.org/tk/tktview/cb5d77) - [image svg upstream out of bound read nanosvg#262](https://core.tcl-lang.org/tk/tktview/121786) - [wm iconbitmap does not correctly set the icon pixmap hint on macOS](https://core.tcl-lang.org/tk/tktview/13ac26) - [Backspace crashes 9.0 interpreter on FreeBSD](https://core.tcl-lang.org/tk/tktview/1da19a) - [Bug in the ttk::scale widget of the "default" theme](https://core.tcl-lang.org/tk/tktview/126d07) - [Wrong appearance of the ttk::menubutton indicator of the "xpnative" theme](https://core.tcl-lang.org/tk/tktview/525536) - [English shortcuts for Chinese locale](https://core.tcl-lang.org/tk/tktview/c99266) - [Tk_Get3DBorderColors broken by design](https://core.tcl-lang.org/tk/tktview/517165) - [MS-Win: Incorrect system menu entries for transient toplevels](https://core.tcl-lang.org/tk/tktview/159aa5) - [MS-Win: Withdrawn Tk transient windows can reappear in Windows taskbar preview](https://core.tcl-lang.org/tk/tktview/91d0e9) - [Aqua windows don't always move focus correctly](https://core.tcl-lang.org/tk/tktview/28d33f) - [Cross compiling using x86_64-w64-mingw32-gcc](https://core.tcl-lang.org/tk/tktview/f6d40f) - [BWidget Drag & Drop no longer works on Aqua](https://core.tcl-lang.org/tk/tktview/855ec4) - [tk print command fails with canvas widget](https://core.tcl-lang.org/tk/tktview/d2eac2) - [tk print command fails on windows](https://core.tcl-lang.org/tk/tktview/bb5c3d) - [tk print fails for canvas items with non integer widths](https://core.tcl-lang.org/tk/tktview/7716cb) - [tk print canvas with smooth lines crashes on windows](https://core.tcl-lang.org/tk/tktview/9b23b6) - [Collect utility procs for the Tk test suite](https://core.tcl-lang.org/tk/tktview/718cbc) - [Setting ttk state may change the a variable passed by value](https://core.tcl-lang.org/tk/info/7231bf) - [wm iconbitmap does not support icon files with png images on Windows](https://core.tcl-lang.org/tk/info/17b509) - [block cursor size on a tab is too large](https://core.tcl-lang.org/tk/info/5d0bc3) - [macOS clipboard managers do not notice clipboard changes done by Tk](https://core.tcl-lang.org/tk/info/e94c8b) # Incompatibilities - [The ActiveCodePage element has been removed from the Windows executable manifest for wish](https://core.tcl-lang.org/tips/doc/trunk/tip/716.md) Release Tk 9.0.1 arises from the check-in with tag `core-9-0-1`. Tk 9.0.1 continues the Tk 9.0 series of releases. The Tk 9.0 series does not support Tcl 8.6. The Tk 9.0 series extends the Tcl 9.0 series. To make use of Tk 9.0.1, first a Tcl 9.0 release must be present. As new Tk features are developed, expect them to appear in Tk 9, but not necessarily in Tk 8. Tk patch releases have the primary purpose of delivering bug fixes to the userbase. As the first patch release in the Tk 9.0 series, Tk 9.0.1 also includes a small number of interface changes that complete some incomplete features first delivered in Tk 9.0.0. # Completed 9.0 Features and Interfaces - [TIP #706: Expose three Tk "In Context" functions via stubs table](https://core.tcl-lang.org/tips/doc/trunk/tip/706.md) - [Tilde file syntax not available on 9.0 but used by "~/.Xdefaults"](https://core.tcl-lang.org/tk/tktview/fcfddc) - [leftover use of tilde in filename string](https://core.tcl-lang.org/tk/tktview/767702) # Bug fixes - [Canvas widget handles pixel objects incorrectly in Tk 9.0](https://core.tcl-lang.org/tk/tktview/610a73) - [SIGABRT from Tk_DeleteErrorHandler()](https://core.tcl-lang.org/tk/tktview/f52986) - [build failure on macOS < 10.13](https://core.tcl-lang.org/tk/tktview/d48cbf) - [Two potentially bogus binding scripts for ](https://core.tcl-lang.org/tk/tktview/73c5e3) - [Aqua: canvas items are not always redrawn](https://core.tcl-lang.org/tk/tktview/5869c2) - [Aqua: color rgb values do not behave as expected when appearance is changed](https://core.tcl-lang.org/tk/tktview/01f58b) - [Aqua: winfo rgb . systemLabelColor returns a weird result on aqua](https://core.tcl-lang.org/tk/tktview/23b57a) - [Aqua: background thread became slower](https://core.tcl-lang.org/tk/tktview/547cc6) - [Use of Tcl_Obj vs char * in Widget storage](https://core.tcl-lang.org/tk/tktview/f91aa2) - [cannot build .chm help file (Windows)](https://core.tcl-lang.org/tk/tktview/bb110c) - [Tk initialization overwrites thread specific data](https://core.tcl-lang.org/tk/tktview/bcbf4c) - [File clamTheme.tcl misses code related to the -indicatorforeground option](https://core.tcl-lang.org/tk/tktview/a69fd7) - [Segfault when using menu(button) with the -font option](https://core.tcl-lang.org/tk/tktview/8ce672) - [Bind mechanism vs. GNOME](https://core.tcl-lang.org/tk/tktview/6bdf1a) - [many PIXEL options don't keep their configured value](https://core.tcl-lang.org/tk/tktview/29ba53) - [Menu entry underline does not consider activeborderwidth](https://core.tcl-lang.org/tk/tktview/844c0b) Release Tk 9.0.0 arises from the check-in with tag `core-9-0-0`. Highlighted differences between Tk 9.0 and Tk 8.6 are summarized below, with focus on changes important to programmers using the Tk library and writing Tcl scripts containing Tk commands. ## Many improvements to use of platform features and conventions. - Built-in widgets and themes are scaling-aware. - Improved support of two-finger gestures, where available - The `tk windowingsystem` "aqua" needs macOS 10.9 or later ## New commands and options - `tk sysnotify` — Access to the OS notifications system - `tk systray` — Access to the OS tray facility - `tk print` — Access to the OS printing facility ## Widget options - New `ttk::progressbar` option: **-text** - `$frame ... -backgroundimage $img -tile $bool` - `$menu id`, `$menu add|insert ... ?$id? ...` - `$image get ... -withalpha ...` - All indices now accept the forms **end**, **end-int**, **int+|-int** ## Improved widget appearance - `ttk::notebook` with nondefault tab positions ## Images - Partial SVG support - Read/write access to photo image metadata ## Known bugs - [Inconsistent reporting of child geometry changes to grid container](https://core.tcl-lang.org/tk/tktview/beaa8e) - [slow widget creation if default font is not used](https://core.tcl-lang.org/tk/tktview/8da7af) - [The wm manage command does not work on current macOS versions](https://core.tcl-lang.org/tk/tktview/8a6012) - [Slow processing irregular transparencies](https://core.tcl-lang.org/tk/tktview/919066) - [text's cursor width on 0th column](https://core.tcl-lang.org/tk/tktview/47fbfc) - [text widget breaks graphemes with combining diacritical marks](https://core.tcl-lang.org/tk/tktview/442208) tk9.0.3/compat/0000755001000000100000000000000015105110466016324 5ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmanstk9.0.3/compat/license.terms0000644001000000100000000000433315076161071021032 0ustar ICTAD+Jan.NijtmansICTAD+Jan.NijtmansThis software is copyrighted by the Regents of the University of California, Sun Microsystems, Inc., Scriptics Corporation, ActiveState Corporation, Apple Inc. and other parties. The following terms apply to all files associated with the software unless explicitly disclaimed in individual files. The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No written agreement, license, or royalty fee is required for any of the authorized uses. Modifications to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first page of each file where they apply. IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. GOVERNMENT USE: If you are acquiring this software on behalf of the U.S. government, the Government shall have only "Restricted Rights" in the software and related documentation as defined in the Federal Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you are acquiring the software on behalf of the Department of Defense, the software shall be classified as "Commercial Computer Software" and the Government shall have only "Restricted Rights" as defined in Clause 252.227-7013 (b) (3) of DFARs. Notwithstanding the foregoing, the authors grant the U.S. Government and others acting in its behalf permission to use and distribute the software in accordance with the terms specified in this license. tk9.0.3/doc/0000755001000000100000000000000015105110705015602 5ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmanstk9.0.3/doc/3DBorder.30000644001000000100000000003577315105057705017323 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1993 The Regents of the University of California. '\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_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 .SH SYNOPSIS .nf \fB#include \fR Tk_3DBorder \fBTk_Alloc3DBorderFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp \fBTk_ClipDrawableToRect\fR(\fIdisplay, drawable, x, y, width, height\fR) .sp \fBTk_DrawHighlightBorder\fR(\fItkwin, fgGC, bgGC, highlightWidth, drawable\fR) .sp Tk_3DBorder \fBTk_Get3DBorder\fR(\fIinterp, tkwin, colorName\fR) .sp \fBTk_Get3DBorderColors\fR(\fIborder, bgColorPtr, darkColorPtr, lightColorPtr\fR) .sp Tk_3DBorder \fBTk_Get3DBorderFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_Draw3DRectangle\fR(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fR) .sp \fBTk_Fill3DRectangle\fR(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fR) .sp \fBTk_Draw3DPolygon\fR(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fR) .sp \fBTk_Fill3DPolygon\fR(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fR) .sp \fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fR) .sp \fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fR) .sp \fBTk_SetBackgroundFromBorder\fR(\fItkwin, border\fR) .sp const char * \fBTk_NameOf3DBorder\fR(\fIborder\fR) .sp XColor * \fBTk_3DBorderColor\fR(\fIborder\fR) .sp GC * \fBTk_3DBorderGC\fR(\fItkwin, border, which\fR) .sp \fBTk_Free3DBorderFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_Free3DBorder\fR(\fIborder\fR) .fi .SH ARGUMENTS .AS "Tk_3DBorder" borderWidth .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window (for all procedures except \fBTk_Get3DBorder\fR, must be the window for which the border was allocated). .AP Tcl_Obj *objPtr in Pointer to value whose value describes color corresponding to background (flat areas). Illuminated edges will be brighter than this and shadowed edges will be darker than this. .AP "const char" *colorName in Same as \fIobjPtr\fR except value is supplied as a string rather than a value. .AP Drawable drawable in X token for window or pixmap; indicates where graphics are to be drawn. Must either be the X window for \fItkwin\fR or a pixmap with the same screen and depth as \fItkwin\fR. .AP Tk_3DBorder border in Token for border previously allocated in call to \fBTk_Get3DBorder\fR. .AP int x in X-coordinate of upper-left corner of rectangle describing border or bevel, in pixels. .AP int y in Y-coordinate of upper-left corner of rectangle describing border or bevel, in pixels. .AP int width in Width of rectangle describing border or bevel, in pixels. .AP int height in Height of rectangle describing border or bevel, in pixels. .AP int borderWidth in Width of border in pixels. Positive means border is inside rectangle given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means border is outside rectangle. .AP int highlightWidth in Width of ring around the outside of the widget if the widget has received the input focus. .AP int relief in Indicates 3-D position of interior of value relative to exterior; should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR (may also be \fBTK_RELIEF_FLAT\fR for \fBTk_Fill3DRectangle\fR). .AP XPoint *pointPtr in Pointer to array of points describing the set of vertices in a polygon. The polygon need not be closed (it will be closed automatically if it is not). .AP int numPoints in Number of points at \fI*pointPtr\fR. .AP int polyBorderWidth in Width of border in pixels. If positive, border is drawn to left of trajectory given by \fIpointPtr\fR; if negative, border is drawn to right of trajectory. If \fIleftRelief\fR is \fBTK_RELIEF_GROOVE\fR or \fBTK_RELIEF_RIDGE\fR then the border is centered on the trajectory. .AP int leftRelief in Height of left side of polygon's path relative to right. \fBTK_RELIEF_RAISED\fR means left side should appear higher and \fBTK_RELIEF_SUNKEN\fR means right side should appear higher; \fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean the obvious things. For \fBTk_Fill3DPolygon\fR, \fBTK_RELIEF_FLAT\fR may also be specified to indicate no difference in height. .AP int leftBevel in Non-zero means this bevel forms the left side of the value; zero means it forms the right side. .AP int leftIn in Non-zero means that the left edge of the horizontal bevel angles in, so that the bottom of the edge is farther to the right than the top. Zero means the edge angles out, so that the bottom is farther to the left than the top. .AP int rightIn in Non-zero means that the right edge of the horizontal bevel angles in, so that the bottom of the edge is farther to the left than the top. Zero means the edge angles out, so that the bottom is farther to the right than the top. .AP int topBevel in Non-zero means this bevel forms the top side of the value; zero means it forms the bottom side. .AP int which in Specifies which of the border's graphics contexts is desired. Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR. .AP XColor *bgColorPtr out Pointer to location in which to store the background color of the given border. .AP XColor *darkColorPtr out Pointer to location in which to store the color for darker areas of the given border. .AP XColor *lightColorPtr out Pointer to location in which to store the color for lighter areas of the given border. .AP GC fgGC in Foreground X graphics context. .AP GC fgGC in Background X graphics context. .BE .SH DESCRIPTION .PP These procedures provide facilities for drawing window borders in a way that produces a three-dimensional appearance. \fBTk_Alloc3DBorderFromObj\fR allocates colors and Pixmaps needed to draw a border in the window given by the \fItkwin\fR argument. The value of \fIobjPtr\fR is a standard Tk color name that determines the border colors. The color indicated by \fIobjPtr\fR will not actually be used in the border; it indicates the background color for the window (i.e. a color for flat surfaces). The illuminated portions of the border will appear brighter than indicated by \fIobjPtr\fR, and the shadowed portions of the border will appear darker than \fIobjPtr\fR. .PP \fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls to \fBTk_Draw3DRectangle\fR. If an error occurs in allocating information for the border (e.g. a bogus color name was given) then NULL is returned and an error message is left as the result of interpreter \fIinterp\fR. If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR and \fItkwin\fR. .PP \fBTk_ClipDrawableToRect\fR will clip all drawing into the drawable \fId\fR to the given rectangle. If \fIwidth\fR or \fIheight\fR are negative, reset to no clipping. Subsequent drawing into \fId\fR is offset and clipped as specified. The function is only used when \fBTK_NO_DOUBLE_BUFFERING\fR is specified at compile time. .PP \fBTk_DrawHighlightBorder\fR draws a rectangular ring around the outside of a widget to indicate that it has received the input focus. On the Macintosh, this puts a 1 pixel border in the bgGC color between the widget and the focus ring, except in the case where highlightWidth is 0 or 1, in which case the border is left out. For proper Mac L&F, use highlightWidth of 3. .PP \fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except that the color is specified with a string instead of a value. This prevents \fBTk_Get3DBorder\fR from caching the return value, so \fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR. .PP \fBTk_Get3DBorderColors\fR returns the used colors of the given border. .PP \fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given the window and color name used to create the border. \fBTk_Get3DBorderFromObj\fR does not actually create the border; it must already have been created with a previous call to \fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. The return value is cached in \fIobjPtr\fR, which speeds up future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR and \fItkwin\fR. .PP Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be invoked to draw the border. The \fItkwin\fR argument specifies the window for which the border was allocated, and \fIdrawable\fR specifies a window or pixmap in which the border is to be drawn. \fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it must refer to a compatible pixmap or window: one associated with the same screen and with the same depth as \fItkwin\fR. The \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR arguments define the bounding box of the border region within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and \fIwidth\fR and \fIheight\fR are the dimensions of the window), and \fIborderWidth\fR specifies the number of pixels actually occupied by the border. The \fIrelief\fR argument indicates which of several three-dimensional effects is desired: \fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should appear raised relative to the exterior of the rectangle, and \fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed. \fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean that there should appear to be a groove or ridge around the exterior of the rectangle. .PP \fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except that it first fills the rectangular area with the background color (one corresponding to the color used to create \fIborder\fR). Then it calls \fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of the rectangular area. The argument \fIrelief\fR indicates the desired effect (\fBTK_RELIEF_FLAT\fR means no border should be drawn; all that happens is to fill the rectangle with the background color). .PP The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex shapes with a three-dimensional appearance. The \fIpointPtr\fR and \fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR indicates how wide the border should be (and on which side of the trajectory to draw it), and \fIleftRelief\fR indicates which side of the trajectory should appear raised. \fBTk_Draw3DPolygon\fR draws a border around the given trajectory using the colors from \fIborder\fR to produce a three-dimensional appearance. If the trajectory is non-self-intersecting, the appearance will be a raised or sunken polygon shape. The trajectory may be self-intersecting, although it's not clear how useful this is. .PP \fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what \fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR: it fills the polygonal area with the background color from \fIborder\fR, then calls \fBTk_Draw3DPolygon\fR to draw a border around the area (unless \fIleftRelief\fR is \fBTK_RELIEF_FLAT\fR; in this case no border is drawn). .PP The procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fR provide lower-level drawing primitives that are used by procedures such as \fBTk_Draw3DRectangle\fR. These procedures are also useful in their own right for drawing rectilinear border shapes. \fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as the left or right side of a rectangle, and \fBTk_3DHorizontalBevel\fR draws a horizontal beveled edge, such as the top or bottom of a rectangle. Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR arguments that describe the rectangular area of the beveled edge (e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR). The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the position of the border relative to the .QW inside of the value, and \fIrelief\fR indicates the relief of the inside of the value relative to the outside. \fBTk_3DVerticalBevel\fR just draws a rectangular region. \fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate mitered corners; it should be called after \fBTk_3DVerticalBevel\fR (otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering in the corner). The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fR describe the mitering at the corners; a value of 1 means that the bottom edge of the trapezoid will be shorter than the top, 0 means it will be longer. For example, to draw a rectangular border the top bevel should be drawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and the bottom bevel should be drawn with 0 for both arguments. .PP The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background pixel and/or pixmap of \fItkwin\fR to produce a result compatible with \fIborder\fR. For color displays, the resulting background will just be the color specified when \fIborder\fR was created; for monochrome displays, the resulting background will be a light stipple pattern, in order to distinguish the background from the illuminated portion of the border. .PP Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR will return the color name that was used to create the border. .PP The procedure \fBTk_3DBorderColor\fR returns the XColor structure that will be used for flat surfaces drawn for its \fIborder\fR argument by procedures like \fBTk_Fill3DRectangle\fR. The return value corresponds to the color name that was used to create the border. The XColor, and its associated pixel value, will remain allocated as long as \fIborder\fR exists. .PP The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts that are used to draw the border. The argument \fIwhich\fR selects which one of the three possible GC's: \fBTK_3D_FLAT_GC\fR returns the context used for flat surfaces, \fBTK_3D_LIGHT_GC\fR returns the context for light shadows, and \fBTK_3D_DARK_GC\fR returns the context for dark shadows. .PP When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR or \fBTk_Free3DBorder\fR should be called to release the resources associated with it. For \fBTk_Free3DBorderFromObj\fR the border to release is specified with the window and color name used to create the border; for \fBTk_Free3DBorder\fR the border to release is specified with the Tk_3DBorder token for the border. There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or \fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. .SH KEYWORDS 3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect tk9.0.3/doc/AddOption.30000644001000000100000000000412215105057705017560 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tk_AddOption 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_AddOption \- Add an option to the option database .SH SYNOPSIS .nf \fB#include \fR .sp void \fBTk_AddOption\fR(\fItkwin, name, value, priority\fR) .sp Tcl_Obj * \fBTk_GetSystemDefault\fR(\fItkwin, dbName, className\fR) .fi .SH ARGUMENTS .AP Tk_Window tkwin in Token for window. .AP "const char" *name in Multi-element name of option. .AP "const char" *value in Value of option. .AP "const char" *dbName in The option database name. .AP "const char" *className in The name of the option class. .AP int priority in Overall priority level to use for option. .BE .SH DESCRIPTION .PP \fBTk_AddOption\fR is invoked to add an option to the database associated with \fItkwin\fR's main window. \fIName\fR contains the option being specified and consists of names and/or classes separated by asterisks or dots, in the usual X format. \fIValue\fR contains the text string to associate with \fIname\fR; this value will be returned in calls to \fBTk_GetOption\fR. \fIPriority\fR specifies the priority of the value; when options are queried using \fBTk_GetOption\fR, the value with the highest priority is returned. \fIPriority\fR must be between 0 and \fBTK_MAX_PRIO\fR (100). Some common priority values are: .IP \fBTK_WIDGET_DEFAULT_PRIO\fR (20) Used for default values hard-coded into widgets. .IP \fBTK_STARTUP_FILE_PRIO\fR (40) Used for options specified in application-specific startup files. .IP \fBTK_USER_DEFAULT_PRIO\fR (60) Used for options specified in user-specific defaults files, such as \fB.Xdefaults\fR, resource databases loaded into the X server, or user-specific startup files. .IP \fBTK_INTERACTIVE_PRIO\fR (80) Used for options specified interactively after the application starts running. .PP \fBTk_GetSystemDefault\fR returns a Tcl_Obj* with the string identifying a configuration option matching the given \fIdbname\fR and \fIclassName\fR. Returns NULL if there are no system defaults that match this pair. .SH KEYWORDS class, name, option, add tk9.0.3/doc/bell.n0000644001000000100000000000220415076161054016707 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" Copyright (c) 2000 Ajuba Solutions. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH bell n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME bell \- Ring a display's bell .SH SYNOPSIS \fBbell \fR?\fB\-displayof \fIwindow\fR? ?\fB\-nice\fR? .BE .SH DESCRIPTION .PP This command rings the bell on the display for \fIwindow\fR and returns an empty string. If the \fB\-displayof\fR option is omitted, the display of the application's main window is used by default. The command uses the current bell-related settings for the display, which may be modified with programs such as \fBxset\fR. .PP If \fB\-nice\fR is not specified, this command also resets the screen saver for the screen. Some screen savers will ignore this, but others will reset so that the screen becomes visible again. .SH KEYWORDS beep, bell, ring '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/bind.n0000644001000000100000000010143015105057705016706 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" Copyright (c) 1998 Scriptics Corporation. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH bind n 8.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME bind \- Arrange for X events to invoke Tcl scripts .SH SYNOPSIS \fBbind\fI tag\fR ?\fIsequence\fR? ?\fB+\fR??\fIscript\fR? .BE .SH "INTRODUCTION" .PP The \fBbind\fR command associates Tcl scripts with X events. If all three arguments are specified, \fBbind\fR will arrange for \fIscript\fR (a Tcl script called the .QW "binding script") to be evaluated whenever the event(s) given by \fIsequence\fR occur in the window(s) identified by \fItag\fR. If \fIscript\fR is prefixed with a .QW + , then it is appended to any existing binding for \fIsequence\fR; otherwise \fIscript\fR replaces any existing binding. If \fIscript\fR is an empty string then the current binding for \fIsequence\fR is destroyed, leaving \fIsequence\fR unbound. In all of the cases where a \fIscript\fR argument is provided, \fBbind\fR returns an empty string. .PP If \fIsequence\fR is specified without a \fIscript\fR, then the script currently bound to \fIsequence\fR is returned, or an empty string is returned if there is no binding for \fIsequence\fR. If neither \fIsequence\fR nor \fIscript\fR is specified, then the return value is a list whose elements are all the sequences for which there exist bindings for \fItag\fR. .PP The \fItag\fR argument determines which window(s) the binding applies to. If \fItag\fR begins with a dot, as in \fB.a.b.c\fR, then it must be the path name for a window; otherwise it may be an arbitrary string. Each window has an associated list of tags, and a binding applies to a particular window if its tag is among those specified for the window. Although the \fBbindtags\fR command may be used to assign an arbitrary set of binding tags to a window, the default binding tags provide the following behavior: .IP \(bu 3 If a tag is the name of an internal window the binding applies to that window. .IP \(bu 3 If the tag is the name of a class of widgets, such as \fBButton\fR, the binding applies to all widgets in that class. .IP \(bu 3 If the tag is the name of a toplevel window the binding applies to the toplevel window and all its internal windows. .IP \(bu 3 If \fItag\fR has the value \fBall\fR, the binding applies to all windows in the application. .SH "EVENT PATTERNS" .PP The \fIsequence\fR argument specifies a sequence of one or more event patterns, with optional white space between the patterns. Each event pattern may take one of three forms. In the simplest case it is a single printing ASCII character, such as \fBa\fR or \fB[\fR. The character may not be a space character or the character \fB<\fR. This form of pattern matches a \fBKey\fR event for the particular character. The second form of pattern is longer but more general. It has the following syntax: .CS \fB<\fImodifier\-modifier\-type\-detail\fB>\fR .CE The entire event pattern is surrounded by angle brackets. Inside the angle brackets are zero or more modifiers, an event type, and an extra piece of information (\fIdetail\fR) identifying a particular button or keysym. Any of the fields may be omitted, as long as at least one of \fItype\fR and \fIdetail\fR is present. The fields must be separated by white space or dashes. .PP The third form of pattern is used to specify a user-defined, named virtual event. It has the following syntax: .CS \fB<<\fIname\fB>>\fR .CE The entire virtual event pattern is surrounded by double angle brackets. Inside the angle brackets is the user-defined name of the virtual event. Modifiers, such as \fBShift\fR or \fBControl\fR, may not be combined with a virtual event to modify it. Bindings on a virtual event may be created before the virtual event is defined, and if the definition of a virtual event changes dynamically, all windows bound to that virtual event will respond immediately to the new definition. .PP Some widgets (e.g. \fBmenu\fR and \fBtext\fR) issue virtual events when their internal state is updated in some ways. Please see the manual page for each widget for details. .SS "MODIFIERS" .PP Modifiers consist of any of the following values: .DS .ta 6c \fBControl\fR \fBMod1\fR, \fBM1\fR, \fBCommand\fR \fBAlt\fR \fBMod2\fR, \fBM2\fR, \fBOption\fR \fBShift\fR \fBMod3\fR, \fBM3\fR, \fBNum\fR \fBLock\fR \fBMod4\fR, \fBM4\fR, \fBFn\fR \fBExtended\fR \fBMod5\fR, \fBM5\fR \fBButton1\fR, \fBB1\fR \fBMeta\fR, \fBM\fR \fBButton2\fR, \fBB2\fR \fBDouble\fR \fBButton3\fR, \fBB3\fR \fBTriple\fR \fBButton4\fR, \fBB4\fR \fBQuadruple\fR \fBButton5\fR, \fBB5\fR .DE Where more than one value is listed, separated by commas, the values are equivalent. Most of the modifiers have the obvious X meanings. For example, \fBButton1\fR requires that button 1 be depressed when the event occurs. For a binding to match a given event, the modifiers in the event must include all of those specified in the event pattern. An event may also contain additional modifiers not specified in the binding. For example, if button 1 is pressed while the shift and control keys are down, the pattern \fB\fR will match the event, but \fB\fR will not. If no modifiers are specified, then any combination of modifiers may be present in the event. .PP \fBMeta\fR and \fBM\fR refer to whichever of the \fBM1\fR through \fBM5\fR modifiers is associated with the Meta key(s) on the keyboard (keysyms \fBMeta_R\fR and \fBMeta_L\fR). If there are no Meta keys, or if they are not associated with any modifiers, then \fBMeta\fR and \fBM\fR will not match any events. Similarly, the \fBAlt\fR modifier refers to whichever modifier is associated with the alt key(s) on the keyboard (keysyms \fBAlt_L\fR and \fBAlt_R\fR). .PP The \fBDouble\fR, \fBTriple\fR and \fBQuadruple\fR modifiers are a convenience for specifying double mouse clicks and other repeated events. They cause a particular event pattern to be repeated 2, 3 or 4 times, and also place a time and space requirement on the sequence: for a sequence of events to match a \fBDouble\fR, \fBTriple\fR or \fBQuadruple\fR pattern, all of the events must occur close together in time and without substantial mouse motion in between. For example, \fB\fR is equivalent to \fB\fR with the extra time and space requirement. .PP The \fBCommand\fR, \fBOption\fR, \fBNum\fR and \fBFn\fRmodifiers are equivalents of \fBMod1\fR up to \fBMod4\fR; they correspond to Macintosh-specific modifier keys. .PP The \fBExtended\fR modifier is, at present, specific to Windows. It appears on events that are associated with the keys on the .QW "extended keyboard" . On a US keyboard, the extended keys include the \fBAlt\fR and \fBControl\fR keys at the right of the keyboard, the cursor keys in the cluster to the left of the numeric pad, the \fBNumLock\fR key, the \fBBreak\fR key, the \fBPrintScreen\fR key, and the \fB/\fR and \fBEnter\fR keys in the numeric keypad. .SS "EVENT TYPES" .PP The \fItype\fR field may be any of the standard X event types, with a few extra abbreviations. The \fItype\fR field will also accept a couple non-standard X event types that were added to better support the Macintosh and Windows platforms. Below is a list of all the valid types; where two names appear together, they are synonyms. .DS .ta \w'\fBButton, ButtonPress\0\0\0\fR'u +\w'\fBKey, KeyPress\0\0\0\fR'u \fBActivate\fR \fBDestroy\fR \fBMap\fR \fBButton\fR, \fBButtonPress\fR \fBEnter\fR \fBMapRequest\fR \fBButtonRelease\fR \fBExpose\fR \fBMotion\fR \fBCirculate\fR \fBFocusIn\fR \fBMouseWheel\fR \fBTouchpadScroll\fR \fBCirculateRequest\fR \fBFocusOut\fR \fBProperty\fR \fBColormap\fR \fBGravity\fR \fBReparent\fR \fBConfigure\fR \fBKey\fR, \fBKeyPress\fR \fBResizeRequest\fR \fBConfigureRequest\fR \fBKeyRelease\fR \fBUnmap\fR \fBCreate\fR \fBLeave\fR \fBVisibility\fR \fBDeactivate\fR .DE Most of the above events have the same fields and behaviors as events in the X Windowing system. You can find more detailed descriptions of these events in any X window programming book. A couple of the events are extensions to the X event system to support features unique to the Macintosh and Windows platforms. We provide a little more detail on these events here. These include: .IP "\fBActivate\fR, \fBDeactivate\fR" 5 These two events are sent to every sub-window of a toplevel when they change state. In addition to the focus Window, the Macintosh platform and Windows platforms have a notion of an active window (which often has but is not required to have the focus). On the Macintosh, widgets in the active window have a different appearance than widgets in deactive windows. The \fBActivate\fR event is sent to all the sub-windows in a toplevel when it changes from being deactive to active. Likewise, the \fBDeactive\fR event is sent when the window's state changes from active to deactive. There are no useful percent substitutions you would make when binding to these events. .IP \fBMouseWheel\fR 5 Many contemporary mice include a mouse wheel, which is used for scrolling documents without using the scrollbars. By rolling the wheel, the system will generate \fBMouseWheel\fR events that the application can use to scroll. The event is routed to the window currently under the mouse pointer. When the event is received you can use the \fB%D\fR substitution to get the \fIdelta\fR field for the event, which is an integer value describing how the mouse wheel has moved. The smallest value for which the system will report is defined by the OS. The sign of the value determines which direction your widget should scroll. Positive values should scroll up and negative values should scroll down. .RS .PP Horizontal scrolling uses \fBShift-MouseWheel\fR events, with positive \fB%D\fR \fIdelta\fR substitution indicating left scrolling and negative right scrolling. Horizontal scrolling events are generated tilt wheels on some mice. Horizontal scrolling can also be emulated by holding Shift and scrolling vertically. .RE .IP "\fBTouchpadScroll\fR" 5 On some platforms (currently Windows and macOS) there is support for high-resolution scrolling devices, such as touchpads. This is provided via \fBTouchpadScroll\fR events. These events store two 16 bit delta values in the integer provided by the \fB%D\fR substitution. The \fIX\fR delta is in the high order 16 bits and the \fIY\fR delta is in the low order 16 bits. These values can be unpacked by using the tk::PreciseScrollDeltas utility procedure. For example: .CS lassign [tk::PreciseScrollDeltas %D] deltaX deltaY .CE The \fB$#\fR substitution is a counter for \fBTouchpadScroll\fR events which can be used by widgets that only support scrolling by units to ignore some portion of the events. .IP "\fBKeyPress\fR, \fBKeyRelease\fR" 5 The \fBKeyPress\fR and \fBKeyRelease\fR events are generated whenever a key is pressed or released. \fBKeyPress\fR and \fBKeyRelease\fR .IP "\fBKey\fR, \fBKeyRelease\fR" 5 The \fBKey\fR and \fBKeyRelease\fR events are generated whenever a key is pressed or released. \fBKey\fR and \fBKeyRelease\fR events are sent to the window which currently has the keyboard focus. .IP "\fBButton\fR, \fBButtonRelease\fR, \fBMotion\fR" 5 The \fBButton\fR and \fBButtonRelease\fR events are generated when the user presses or releases a mouse button. \fBMotion\fR events are generated whenever the pointer is moved. \fBButton\fR, \fBButtonRelease\fR, and \fBMotion\fR events are normally sent to the window containing the pointer. .RS .PP When a mouse button is pressed, the window containing the pointer automatically obtains a temporary pointer grab. Subsequent \fBButton\fR, \fBButtonRelease\fR, and \fBMotion\fR events will be sent to that window, regardless of which window contains the pointer, until all buttons have been released. .RE .IP \fBConfigure\fR 5 A \fBConfigure\fR event is sent to a window whenever its size, position, or border width changes, and sometimes when it has changed position in the stacking order. .IP "\fBMap\fR, \fBUnmap\fR" 5 The \fBMap\fR and \fBUnmap\fR events are generated whenever the mapping state of a window changes. .RS .PP Windows are created in the unmapped state. Top-level windows become mapped when they transition to the \fBnormal\fR state, and are unmapped in the \fBwithdrawn\fR and \fBiconic\fR states. Other windows become mapped when they are placed under control of a geometry manager (for example \fBpack\fR or \fBgrid\fR). .PP A window is \fIviewable\fR only if it and all of its ancestors are mapped. Note that geometry managers typically do not map their children until they have been mapped themselves, and unmap all children when they become unmapped; hence in Tk \fBMap\fR and \fBUnmap\fR events indicate whether or not a window is viewable. .RE .IP \fBVisibility\fR 5 A window is said to be \fIobscured\fR when another window above it in the stacking order fully or partially overlaps it. \fBVisibility\fR events are generated whenever a window's obscurity state changes; the \fIstate\fR field (\fB%s\fR) specifies the new state. .IP \fBExpose\fR 5 An \fBExpose\fR event is generated whenever all or part of a window should be redrawn (for example, when a window is first mapped or if it becomes unobscured). It is normally not necessary for client applications to handle \fBExpose\fR events, since Tk handles them internally. .IP \fBDestroy\fR 5 A \fBDestroy\fR event is delivered to a window when it is destroyed. .RS .PP When the \fBDestroy\fR event is delivered to a widget, it is in a .QW half-dead state: the widget still exists, but operations that involve it may return invalid results, or return an error. .RE .IP "\fBFocusIn\fR, \fBFocusOut\fR" 5 The \fBFocusIn\fR and \fBFocusOut\fR events are generated whenever the keyboard focus changes. A \fBFocusOut\fR event is sent to the old focus window, and a \fBFocusIn\fR event is sent to the new one. .RS .PP In addition, if the old and new focus windows do not share a common parent, .QW "virtual crossing" focus events are sent to the intermediate windows in the hierarchy. Thus a \fBFocusIn\fR event indicates that the target window or one of its descendants has acquired the focus, and a \fBFocusOut\fR event indicates that the focus has been changed to a window outside the target window's hierarchy. .PP The keyboard focus may be changed explicitly by a call to \fBfocus\fR, or implicitly by the window manager. .RE .IP "\fBEnter\fR, \fBLeave\fR" 5 An \fBEnter\fR event is sent to a window when the pointer enters that window, and a \fBLeave\fR event is sent when the pointer leaves it. .RS .PP If there is a pointer grab in effect, \fBEnter\fR and \fBLeave\fR events are only delivered to the window owning the grab. .PP In addition, when the pointer moves between two windows, \fBEnter\fR and \fBLeave\fR .QW "virtual crossing" events are sent to intermediate windows in the hierarchy in the same manner as for \fBFocusIn\fR and \fBFocusOut\fR events. .RE .IP \fBProperty\fR A \fBProperty\fR event is sent to a window whenever an X property belonging to that window is changed or deleted. \fBProperty\fR events are not normally delivered to Tk applications as they are handled by the Tk core. .IP \fBColormap\fR A \fBColormap\fR event is generated whenever the colormap associated with a window has been changed, installed, or uninstalled. .RS .PP Widgets may be assigned a private colormap by specifying a \fB\-colormap\fR option; the window manager is responsible for installing and uninstalling colormaps as necessary. .PP Note that Tk provides no useful details for this event type. .RE '\" The following events were added in TIP#47 .IP "\fBMapRequest\fR, \fBCirculateRequest\fR, \fBResizeRequest\fR, \fBConfigureRequest\fR, \fBCreate\fR" 5 These events are not normally delivered to Tk applications. They are included for completeness, to make it possible to write X11 window managers in Tk. (These events are only delivered when a client has selected \fBSubstructureRedirectMask\fR on a window; the Tk core does not use this mask.) .IP "\fBGravity\fR, \fBReparent\fR, \fBCirculate\fR" 5 The events \fBGravity\fR and \fBReparent\fR are not normally delivered to Tk applications. They are included for completeness. .RS .PP A \fBCirculate\fR event indicates that the window has moved to the top or to the bottom of the stacking order as a result of an \fBXCirculateSubwindows\fR protocol request. Note that the stacking order may be changed for other reasons which do not generate a \fBCirculate\fR event, and that Tk does not use \fBXCirculateSubwindows()\fR internally. This event type is included only for completeness; there is no reliable way to track changes to a window's position in the stacking order. .RE .SS "EVENT DETAILS" .PP The last part of a long event specification is \fIdetail\fR. In the case of a \fBButton\fR or \fBButtonRelease\fR event, it is the number of a button (1\-9). If a button number is given, then only an event on that particular button will match; if no button number is given, then an event on any button will match. Note: giving a specific button number is different than specifying a button modifier; in the first case, it refers to a button being pressed or released, while in the second it refers to some other button that is already depressed when the matching event occurs. If a button number is given then \fItype\fR may be omitted: if will default to \fBButton\fR. For example, the specifier \fB<1>\fR is equivalent to \fB\fR. .PP If the event type is \fBKey\fR or \fBKeyRelease\fR, then \fIdetail\fR may be specified in the form of an X keysym. Keysyms are textual specifications for particular keys on the keyboard; they include all the alphanumeric ASCII characters (e.g. .QW a is the keysym for the ASCII character .QW a ), plus descriptions for non-alphanumeric characters .PQ comma "is the keysym for the comma character" , plus descriptions for all the non-ASCII keys on the keyboard (e.g. .QW Shift_L is the keysym for the left shift key, and .QW F1 is the keysym for the F1 function key, if it exists). The complete list of keysyms is not presented here; it is available in other X documentation and may vary from system to system. If necessary, you can use the \fB%K\fR notation described below to print out the keysym name for a particular key. If a keysym \fIdetail\fR is given, then the \fItype\fR field may be omitted; it will default to \fBKey\fR. For example, \fB\fR is equivalent to \fB\fR. .SH "BINDING SCRIPTS AND SUBSTITUTIONS" .PP The \fIscript\fR argument to \fBbind\fR is a Tcl script, called the .QW "binding script", which will be executed whenever the given event sequence occurs. \fICommand\fR will be executed in the same interpreter that the \fBbind\fR command was executed in, and it will run at global level (only global variables will be accessible). If \fIscript\fR contains any \fB%\fR characters, then the script will not be executed directly. Instead, a new script will be generated by replacing each \fB%\fR, and the character following it, with information from the current event. The replacement depends on the character following the \fB%\fR, as defined in the list below. Unless otherwise indicated, the replacement string is the decimal value of the given field from the current event. Some of the substitutions are only valid for certain types of events; if they are used for other types of events the value substituted is undefined. .IP \fB%%\fR 5 Replaced with a single percent. .IP \fB%#\fR 5 The number of the last client request processed by the server (the \fIserial\fR field from the event). Valid for all event types. .IP \fB%a\fR 5 The \fIabove\fR field from the event, formatted as a hexadecimal number. Valid only for \fBConfigure\fR events. Indicates the sibling window immediately below the receiving window in the stacking order, or \fB0\fR if the receiving window is at the bottom. .IP \fB%b\fR 5 The number of the button that was pressed or released. Valid only for \fBButton\fR and \fBButtonRelease\fR events. .IP \fB%c\fR 5 The \fIcount\fR field from the event. Valid only for \fBExpose\fR events. Indicates that there are \fIcount\fR pending \fBExpose\fR events which have not yet been delivered to the window. .IP \fB%d\fR 5 The \fIdetail\fR or \fIuser_data\fR field from the event. The \fB%d\fR is replaced by a string identifying the detail. For \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events, the string will be one of the following: .RS .DS .ta 6c \fBNotifyAncestor\fR \fBNotifyNonlinearVirtual\fR \fBNotifyDetailNone\fR \fBNotifyPointer\fR \fBNotifyInferior\fR \fBNotifyPointerRoot\fR \fBNotifyNonlinear\fR \fBNotifyVirtual\fR .DE For \fBConfigureRequest\fR events, the string will be one of: .DS .ta 6c \fBAbove\fR \fBOpposite\fR \fBBelow\fR \fBNone\fR \fBBottomIf\fR \fBTopIf\fR .DE For virtual events, the string will be whatever value is stored in the \fIuser_data\fR field when the event was created (typically with \fBevent generate\fR), or the empty string if the field is NULL. Virtual events corresponding to key sequence presses (see \fBevent add\fR for details) set the \fIuser_data\fR to NULL. For events other than these, the substituted string is undefined. .RE .IP \fB%f\fR 5 The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR). Valid only for \fBEnter\fR and \fBLeave\fR events. \fB1\fR if the receiving window is the focus window or a descendant of the focus window, \fB0\fR otherwise. .IP \fB%h\fR 5 The \fIheight\fR field from the event. Valid for the \fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR, \fBResizeRequest\fR, and \fBExpose\fR events. Indicates the new or requested height of the window. .IP \fB%i\fR 5 The \fIwindow\fR field from the event, represented as a hexadecimal integer. Valid for all event types. .IP \fB%k\fR 5 The \fIkeycode\fR field from the event. Valid only for \fBKey\fR and \fBKeyRelease\fR events. .IP \fB%m\fR 5 The \fImode\fR field from the event. The substituted string is one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or \fBNotifyWhileGrabbed\fR. Valid only for \fBEnter\fR, \fBFocusIn\fR, \fBFocusOut\fR, and \fBLeave\fR events. .IP \fB%o\fR 5 The \fIoverride_redirect\fR field from the event. Valid only for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. .IP \fB%p\fR 5 The \fIplace\fR field from the event, substituted as one of the strings \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid only for \fBCirculate\fR and \fBCirculateRequest\fR events. .IP \fB%s\fR 5 The \fIstate\fR field from the event. For \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBKey\fR, \fBKeyRelease\fR, \fBLeave\fR, and \fBMotion\fR events, a decimal string is substituted. For \fBVisibility\fR, one of the strings \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, and \fBVisibilityFullyObscured\fR is substituted. For \fBProperty\fR events, substituted with either the string \fBNewValue\fR (indicating that the property has been created or modified) or \fBDelete\fR (indicating that the property has been removed). .IP \fB%t\fR 5 The \fItime\fR field from the event. This is the X server timestamp (typically the time since the last server reset) in milliseconds, when the event occurred. Valid for most events. .IP \fB%w\fR 5 The \fIwidth\fR field from the event. Indicates the new or requested width of the window. Valid only for \fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR, \fBResizeRequest\fR, and \fBExpose\fR events. .IP "\fB%x\fR, \fB%y\fR" 5 The \fIx\fR and \fIy\fR fields from the event. For \fBButton\fR, \fBButtonRelease\fR, \fBMotion\fR, \fBKey\fR, \fBKeyRelease\fR, and \fBMouseWheel\fR events, \fB%x\fR and \fB%y\fR indicate the position of the mouse pointer relative to the receiving window. For key events on the Macintosh these are the coordinates of the mouse at the moment when an X11 KeyEvent is sent to Tk, which could be slightly later than the time of the physical press or release. For \fBEnter\fR and \fBLeave\fR events, the position where the mouse pointer crossed the window, relative to the receiving window. For \fBConfigure\fR and \fBCreate\fR requests, the \fIx\fR and \fIy\fR coordinates of the window relative to its parent window. .IP \fB%A\fR 5 Substitutes the UNICODE character corresponding to the event, or the empty string if the event does not correspond to a UNICODE character (e.g. the shift key was pressed). On X11, \fBXmbLookupString\fR (or \fBXLookupString\fR when input method support is turned off) does all the work of translating from the event to a UNICODE character. On X11, valid only for \fBKey\fR event. On Windows and macOS/aqua, valid only for \fBKey\fR and \fBKeyRelease\fR events. .IP \fB%B\fR 5 The \fIborder_width\fR field from the event. Valid only for \fBConfigure\fR, \fBConfigureRequest\fR, and \fBCreate\fR events. .IP \fB%D\fR 5 This reports the \fIdelta\fR value of a \fBMouseWheel\fR event. The \fIdelta\fR value represents the rotation units the mouse wheel has been moved. The sign of the value represents the direction the mouse wheel was scrolled. .IP \fB%E\fR 5 The \fIsend_event\fR field from the event. Valid for all event types. \fB0\fR indicates that this is a .QW normal event, \fB1\fR indicates that it is a .QW synthetic event generated by \fBSendEvent\fR. .IP \fB%K\fR 5 The keysym corresponding to the event, substituted as a textual string. Valid only for \fBKey\fR and \fBKeyRelease\fR events. .IP \fB%M\fR 5 The number of script-based binding patterns matched so far for the event. Valid for all event types. .IP \fB%N\fR 5 The keysym corresponding to the event, substituted as a decimal number. Valid only for \fBKey\fR and \fBKeyRelease\fR events. .IP \fB%P\fR 5 The name of the property being updated or deleted (which may be converted to an XAtom using \fBwinfo atom\fR.) Valid only for \fBProperty\fR events. .IP \fB%R\fR 5 The \fIroot\fR window identifier from the event. Valid only for events containing a \fIroot\fR field. .IP \fB%S\fR 5 The \fIsubwindow\fR window identifier from the event, formatted as a hexadecimal number. Valid only for events containing a \fIsubwindow\fR field. .IP \fB%T\fR 5 The \fItype\fR field from the event. Valid for all event types. .IP \fB%W\fR 5 The path name of the window to which the event was reported (the \fIwindow\fR field from the event). Valid for all event types. .IP "\fB%X\fR, \fB%Y\fR" 5 The \fIx_root\fR and \fIy_root\fR fields from the event. If a virtual-root window manager is being used then the substituted values are the corresponding x-coordinate and y-coordinate in the virtual root. Valid only for \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBKey\fR, \fBKeyRelease\fR, \fBLeave\fR and \fBMotion\fR events. Same meaning as \fB%x\fR and \fB%y\fR, except relative to the (virtual) root window. .LP The replacement string for a %-replacement is formatted as a proper Tcl list element. This means that spaces or special characters such as \fB$\fR and \fB{\fR may be preceded by backslashes. This guarantees that the string will be passed through the Tcl parser when the binding script is evaluated. Most replacements are numbers or well-defined strings such as \fBAbove\fR; for these replacements no special formatting is ever necessary. The most common case where reformatting occurs is for the \fB%A\fR substitution. For example, if \fIscript\fR is .CS \fBinsert\0%A\fR .CE and the character typed is an open square bracket, then the script actually executed will be .CS \fBinsert\0\e[\fR .CE This will cause the \fBinsert\fR to receive the original replacement string (open square bracket) as its first argument. If the extra backslash had not been added, Tcl would not have been able to parse the script correctly. .SH "MULTIPLE MATCHES" .PP It is possible for several bindings to match a given X event. If the bindings are associated with different \fItag\fR's, then each of the bindings will be executed, in order. By default, a binding for the widget will be executed first, followed by a class binding, a binding for its toplevel, and an \fBall\fR binding. The \fBbindtags\fR command may be used to change this order for a particular window or to associate additional binding tags with the window. .PP The \fBcontinue\fR and \fBbreak\fR commands may be used inside a binding script to control the processing of matching scripts. If \fBcontinue\fR is invoked within a binding script, then this binding script, including all other .QW + appended scripts, is terminated but Tk will continue processing binding scripts associated with other \fItag\fR's. If the \fBbreak\fR command is invoked within a binding script, then that script terminates and no other scripts will be invoked for the event. .PP Within a script called from the binding script, \fBreturn\fR \fB\-code ok\fR may be used to continue processing (including .QW + appended scripts), or \fBreturn\fR \fB\-code break\fR may be used to stop processing all other binding scripts. .PP If more than one binding matches a particular event and they have the same \fItag\fR, then the most specific binding is chosen and its script is evaluated. The following tests are applied, in order, to determine which of several matching sequences is more specific: .RS .IP (a) an event pattern that specifies a specific button or key is more specific than one that does not; .IP (b) a sequence with the most highest-ordered patterns (in term of highest repetition count) is more specific than a sequence with less highest-ordered patterns; .IP (c) if the modifiers specified in one pattern are a subset of the modifiers in another pattern, then the pattern with more modifiers is more specific; .IP (d) a virtual event whose physical pattern matches the sequence is less specific than the same physical pattern that is not associated with a virtual event; .IP (e) given a sequence that matches two or more virtual events, one of the virtual events will be chosen, but the order is undefined. .RE .PP If the matching sequences contain more than one event, then tests (c)\-(e) are applied in order from the most recent event to the least recent event in the sequences. If these tests fail to determine a winner, then the most recently registered sequence is the winner. .PP If there are two (or more) virtual events that are both triggered by the same sequence, and both of those virtual events are bound to the same window tag, then only one of the virtual events will be triggered, and it will be picked at random: .CS event add <> event add <> event add <> \fBbind\fR Entry <> {puts Paste} \fBbind\fR Entry <> {puts Scroll} .CE If the user types Control\-y, the \fB<>\fR binding will be invoked, but if the user presses button 2 then one of either the \fB<>\fR or the \fB<>\fR bindings will be invoked, but exactly which one gets invoked is undefined. .PP If an X event does not match any of the existing bindings, then the event is ignored. An unbound event is not considered to be an error. .SH "MULTI-EVENT SEQUENCES AND IGNORED EVENTS" .PP When a \fIsequence\fR specified in a \fBbind\fR command contains more than one event pattern, then its script is executed whenever the recent events (leading up to and including the current event) match the given sequence. This means, for example, that if button 1 is clicked repeatedly the sequence \fB\fR will match each button press but the first. If extraneous events that would prevent a match occur in the middle of an event sequence then the extraneous events are ignored unless they are \fBKey\fR or \fBButton\fR events. For example, \fB\fR will match a sequence of presses of button 1, even though there will be \fBButtonRelease\fR events (and possibly \fBMotion\fR events) between the \fBButton\fR events. Furthermore, a \fBKey\fR event may be preceded by any number of other \fBKey\fR events for modifier keys without the modifier keys preventing a match. For example, the event sequence \fBaB\fR will match a press of the \fBa\fR key, a release of the \fBa\fR key, a press of the \fBShift\fR key, and a press of the \fBb\fR key: the press of \fBShift\fR is ignored because it is a modifier key. Finally, if several \fBMotion\fR events occur in a row, only the last one is used for purposes of matching binding sequences. .SH "ERRORS" .PP If an error occurs in executing the script for a binding then the \fBbgerror\fR mechanism is used to report the error. The \fBbgerror\fR command will be executed at global level (outside the context of any Tcl procedure). .SH "EXAMPLES" .PP Arrange for a string describing the motion of the mouse to be printed out when the mouse is double-clicked: .CS \fBbind\fR . { puts "hi from (%x,%y)" } .CE .PP A little GUI that displays what the keysym name of the last key pressed is: .CS set keysym "Press any key" pack [label .l -textvariable keysym -padx 2m -pady 1m] \fBbind\fR . { set keysym "You pressed %K" } .CE .SH "SEE ALSO" bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n) .SH KEYWORDS binding, event '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/BindTable.30000644001000000100000000001501315105057705017524 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateBindingTable 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events .SH SYNOPSIS .nf \fB#include \fR .sp Tk_BindingTable \fBTk_CreateBindingTable\fR(\fIinterp\fR) .sp \fBTk_DeleteBindingTable\fR(\fIbindingTable\fR) .sp unsigned long \fBTk_CreateBinding\fR(\fIinterp, bindingTable, object, eventString, script, append\fR) .sp int \fBTk_DeleteBinding\fR(\fIinterp, bindingTable, object, eventString\fR) .sp const char * \fBTk_GetBinding\fR(\fIinterp, bindingTable, object, eventString\fR) .sp \fBTk_GetAllBindings\fR(\fIinterp, bindingTable, object\fR) .sp \fBTk_DeleteAllBindings\fR(\fIbindingTable, object\fR) .sp \fBTk_BindEvent\fR(\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\fR) .fi .SH ARGUMENTS .AS Tk_BindingTable bindingTable .AP Tcl_Interp *interp in Interpreter to use when invoking bindings in binding table. Also used for returning results and errors from binding procedures. .AP Tk_BindingTable bindingTable in Token for binding table; must have been returned by some previous call to \fBTk_CreateBindingTable\fR. .AP "void *" object in Identifies object with which binding is associated. .AP "const char" *eventString in String describing event sequence. .AP "const char" *script in Tcl script to invoke when binding triggers. .AP int append in Non-zero means append \fIscript\fR to existing script for binding, if any; zero means replace existing script with new one. .AP XEvent *eventPtr in X event to match against bindings in \fIbindingTable\fR. .AP Tk_Window tkwin in Identifier for any window on the display where the event occurred. Used to find display-related information such as key maps. .AP Tcl_Size numObjects in Number of object identifiers pointed to by \fIobjectPtr\fR. .AP "void **" objectPtr in Points to an array of object identifiers: bindings will be considered for each of these objects in order from first to last. .BE .SH DESCRIPTION .PP These procedures provide a general-purpose mechanism for creating and invoking bindings. Bindings are organized in terms of \fIbinding tables\fR. A binding table consists of a collection of bindings plus a history of recent events. Within a binding table, bindings are associated with \fIobjects\fR. The meaning of an object is defined by clients of the binding package. For example, Tk keeps uses one binding table to hold all of the bindings created by the \fBbind\fR command. For this table, objects are pointers to strings such as window names, class names, or other binding tags such as \fBall\fR. Tk also keeps a separate binding table for each canvas widget, which manages bindings created by the canvas's \fBbind\fR widget command; within this table, an object is either a pointer to the internal structure for a canvas item or a Tk_Uid identifying a tag. .PP The procedure \fBTk_CreateBindingTable\fR creates a new binding table and associates \fIinterp\fR with it (when bindings in the table are invoked, the scripts will be evaluated in \fIinterp\fR). \fBTk_CreateBindingTable\fR returns a token for the table, which must be used in calls to other procedures such as \fBTk_CreateBinding\fR or \fBTk_BindEvent\fR. .PP \fBTk_DeleteBindingTable\fR frees all of the state associated with a binding table. Once it returns the caller should not use the \fIbindingTable\fR token again. .PP \fBTk_CreateBinding\fR adds a new binding to an existing table. The \fIobject\fR argument identifies the object with which the binding is to be associated, and it may be any one-word value. Typically it is a pointer to a string or data structure. The \fIeventString\fR argument identifies the event or sequence of events for the binding; see the documentation for the \fBbind\fR command for a description of its format. \fIscript\fR is the Tcl script to be evaluated when the binding triggers. \fIappend\fR indicates what to do if there already exists a binding for \fIobject\fR and \fIeventString\fR: if \fIappend\fR is zero then \fIscript\fR replaces the old script; if \fIappend\fR is non-zero then the new script is appended to the old one. \fBTk_CreateBinding\fR returns an X event mask for all the events associated with the bindings. This information may be useful to invoke \fBXSelectInput\fR to select relevant events, or to disallow the use of certain events in bindings. If an error occurred while creating the binding (e.g., \fIeventString\fR refers to a non-existent event), then 0 is returned and an error message is left as the result of interpreter \fIinterp\fR. .PP \fBTk_DeleteBinding\fR removes from \fIbindingTable\fR the binding given by \fIobject\fR and \fIeventString\fR, if such a binding exists. \fBTk_DeleteBinding\fR always returns \fBTCL_OK\fR. In some cases it may reset the interpreter result to the default empty value. .PP \fBTk_GetBinding\fR returns a pointer to the script associated with \fIeventString\fR and \fIobject\fR in \fIbindingTable\fR. If no such binding exists then NULL is returned and an error message is left as the result of interpreter \fIinterp\fR. .PP \fBTk_GetAllBindings\fR returns in \fIinterp\fR's result a list of all the event strings for which there are bindings in \fIbindingTable\fR associated with \fIobject\fR. If there are no bindings for \fIobject\fR, the result will be an empty string. .PP \fBTk_DeleteAllBindings\fR deletes all of the bindings in \fIbindingTable\fR that are associated with \fIobject\fR. .PP \fBTk_BindEvent\fR is called to process an event. It makes a copy of the event in an internal history list associated with the binding table, then it checks for bindings that match the event. \fBTk_BindEvent\fR processes each of the objects pointed to by \fIobjectPtr\fR in turn. For each object, it finds all the bindings that match the current event history, selects the most specific binding using the priority mechanism described in the documentation for \fBbind\fR, and invokes the script for that binding. If there are no matching bindings for a particular object, then the object is skipped. \fBTk_BindEvent\fR continues through all of the objects, handling exceptions such as errors, \fBbreak\fR, and \fBcontinue\fR as described in the documentation for \fBbind\fR. .SH KEYWORDS binding, event, object, script tk9.0.3/doc/bindtags.n0000644001000000100000000000765015076161055017577 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH bindtags n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME bindtags \- Determine which bindings apply to a window, and order of evaluation .SH SYNOPSIS \fBbindtags \fIwindow \fR?\fItagList\fR? .BE .SH DESCRIPTION .PP When a binding is created with the \fBbind\fR command, it is associated either with a particular window such as \fB.a.b.c\fR, a class name such as \fBButton\fR, the keyword \fBall\fR, or any other string. All of these forms are called \fIbinding tags\fR. Each window contains a list of binding tags that determine how events are processed for the window. When an event occurs in a window, it is applied to each of the window's tags in order: for each tag, the most specific binding that matches the given tag and event is executed. See the \fBbind\fR command for more information on the matching process. .PP By default, each window has four binding tags consisting of the name of the window, the window's class name, the name of the window's nearest toplevel ancestor, and \fBall\fR, in that order. Toplevel windows have only three tags by default, since the toplevel name is the same as that of the window. The \fBbindtags\fR command allows the binding tags for a window to be read and modified. .PP If \fBbindtags\fR is invoked with only one argument, then the current set of binding tags for \fIwindow\fR is returned as a list. If the \fItagList\fR argument is specified to \fBbindtags\fR, then it must be a proper list; the tags for \fIwindow\fR are changed to the elements of the list. The elements of \fItagList\fR may be arbitrary strings; however, any tag starting with a dot is treated as the name of a window; if no window by that name exists at the time an event is processed, then the tag is ignored for that event. The order of the elements in \fItagList\fR determines the order in which binding scripts are executed in response to events. For example, the command .CS \fBbindtags .b {all . Button .b}\fR .CE reverses the order in which binding scripts will be evaluated for a button named \fB.b\fR so that \fBall\fR bindings are invoked first, following by bindings for \fB.b\fR's toplevel .PQ . "" , followed by class bindings, followed by bindings for \fB.b\fR. If \fItagList\fR is an empty list then the binding tags for \fIwindow\fR are returned to the default state described above. .PP The \fBbindtags\fR command may be used to introduce arbitrary additional binding tags for a window, or to remove standard tags. For example, the command .CS \fBbindtags .b {.b TrickyButton . all}\fR .CE replaces the \fBButton\fR tag for \fB.b\fR with \fBTrickyButton\fR. This means that the default widget bindings for buttons, which are associated with the \fBButton\fR tag, will no longer apply to \fB.b\fR, but any bindings associated with \fBTrickyButton\fR (perhaps some new button behavior) will apply. .SH EXAMPLE .PP If you have a set of nested \fBframe\fR widgets and you want events sent to a \fBbutton\fR widget to also be delivered to all the widgets up to the current \fBtoplevel\fR (in contrast to Tk's default behavior, where events are not delivered to those intermediate windows) to make it easier to have accelerators that are only active for part of a window, you could use a helper procedure like this to help set things up: .CS proc setupBindtagsForTreeDelivery {widget} { set tags [list $widget [winfo class $widget]] set w $widget set t [winfo toplevel $w] while {$w ne $t} { set w [winfo parent $w] lappend tags $w } lappend tags all \fBbindtags\fR $widget $tags } .CE .SH "SEE ALSO" bind(n) .SH KEYWORDS binding, event, tag '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/bitmap.n0000644001000000100000000001063015105057705017247 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH bitmap n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME bitmap \- Images that display two colors .SH SYNOPSIS .nf \fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR? \fIimageName \fBcget\fI option\fR \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? .fi .BE .SH DESCRIPTION .PP A bitmap is an image whose pixels can display either of two colors or be transparent. A bitmap image is defined by four things: a background color, a foreground color, and two bitmaps, called the \fIsource\fR and the \fImask\fR. Each of the bitmaps specifies 0/1 values for a rectangular array of pixels, and the two bitmaps must have the same dimensions. For pixels where the mask is zero, the image displays nothing, producing a transparent effect. For other pixels, the image displays the foreground color if the source data is one and the background color if the source data is zero. .SH "CREATING BITMAPS" .PP Like all images, bitmaps are created using the \fBimage create\fR command. Bitmaps support the following \fIoptions\fR: .\" OPTION: -background .TP \fB\-background \fIcolor\fR . Specifies a background color for the image in any of the standard ways accepted by Tk. If this option is set to an empty string then the background pixels will be transparent. This effect is achieved by using the source bitmap as the mask bitmap, ignoring any \fB\-maskdata\fR or \fB\-maskfile\fR options. .\" OPTION: -data .TP \fB\-data \fIstring\fR . Specifies the contents of the source bitmap as a string. The string must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). If both the \fB\-data\fR and \fB\-file\fR options are specified, the \fB\-data\fR option takes precedence. .\" OPTION: -file .TP \fB\-file \fIname\fR . \fIname\fR gives the name of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). .\" OPTION: -foreground .TP \fB\-foreground \fIcolor\fR . Specifies a foreground color for the image in any of the standard ways accepted by Tk. .\" OPTION: -maskdata .TP \fB\-maskdata \fIstring\fR . Specifies the contents of the mask as a string. The string must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). If both the \fB\-maskdata\fR and \fB\-maskfile\fR options are specified, the \fB\-maskdata\fR option takes precedence. .\" OPTION: -maskfile .TP \fB\-maskfile \fIname\fR . \fIname\fR gives the name of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the \fBbitmap\fR program). .SH "IMAGE COMMAND" .PP When a bitmap image is created, Tk also creates a new command whose name is the same as the image. This command may be used to invoke various operations on the image. It has the following general form: .CS \fIimageName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for bitmap images: .\" METHOD: cget .TP \fIimageName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBimage create\fR \fBbitmap\fR command. .\" METHOD: configure .TP \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options for the image. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBimage create\fR \fBbitmap\fR command. .SH KEYWORDS bitmap, image '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/busy.n0000644001000000100000000002437515105057705016770 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1993-1998 Lucent Technologies, Inc. '\" Copyright (c) 2008 Jos Decoster '\" '\" Permission to use, copy, modify, and distribute this software and its '\" documentation for any purpose and without fee is hereby granted, provided '\" that the above copyright notice appear in all copies and that both that '\" the copyright notice and warranty disclaimer appear in supporting '\" documentation, and that the names of Lucent Technologies any of their '\" entities not be used in advertising or publicity pertaining to '\" distribution of the software without specific, written prior permission. '\" '\" Lucent Technologies disclaims all warranties with regard to this software, '\" including all implied warranties of merchantability and fitness. In no '\" event shall Lucent Technologies be liable for any special, indirect or '\" consequential damages or any damages whatsoever resulting from loss of '\" use, data or profits, whether in an action of contract, negligence or '\" other tortuous action, arising out of or in connection with the use or '\" performance of this software. '\" '\" BLT::busy command created by George Howlett. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH busy n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME busy \- Make Tk widgets busy, temporarily blocking user interactions .SH SYNOPSIS .nf \fBtk busy\fI window \fR?\fIoptions\fR? \fBtk busy busywindow \fIwindow\fR \fBtk busy hold\fI window \fR?\fIoptions\fR? \fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... \fBtk busy forget\fI window \fR?\fIwindow \fR?... \fBtk busy current\fR ?\fIpattern\fR? \fBtk busy status \fIwindow\fR .fi .BE .SH DESCRIPTION .PP The \fBtk busy\fR command provides a simple means to block mouse pointer events from Tk widgets, while overriding the widget's cursor with a configurable busy cursor. Note this command does not prevent keyboard events from being sent to the widgets made busy. .SH INTRODUCTION .PP There are many times in applications where you want to temporarily restrict what actions the user can take. For example, an application could have a .QW Run button that when pressed causes some processing to occur. However, while the application is busy processing, you probably don't want the user to be able to click the .QW Run button again. You may also want restrict the user from other tasks such as clicking a .QW Print button. .PP The \fBtk busy\fR command lets you make Tk widgets busy. This means that user interactions such as button clicks, moving the mouse, typing at the keyboard, etc.\0are ignored by the widget. You can set a special cursor (like a watch) that overrides the widget's normal cursor, providing feedback that the application (widget) is temporarily busy. .PP When a widget is made busy, the widget and all of its descendants will ignore pointer events. It's easy to make an entire panel of widgets busy. You can simply make the toplevel widget (such as .QW . ) busy. This is easier and far much more efficient than recursively traversing the widget hierarchy, disabling each widget and re-configuring its cursor. .PP Often, the \fBtk busy\fR command can be used instead of Tk's \fBgrab\fR command. Unlike \fBgrab\fR which restricts all user interactions to one widget, with the \fBtk busy\fR command you can have more than one widget active (for example, a .QW Cancel dialog and a .QW Help button). .SS EXAMPLE .PP You can make several widgets busy by simply making its ancestor widget busy using the \fBhold\fR operation. .PP .CS frame .top button .top.button; canvas .top.canvas pack .top.button .top.canvas pack .top # . . . \fBtk busy\fR hold .top update .CE .PP All the widgets within \fB.top\fR (including \fB.top\fR) are now busy. Using \fBupdate\fR insures that \fBtk busy\fR command will take effect before any other user events can occur. .PP When the application is no longer busy processing, you can allow user interactions again and free any resources it allocated by the \fBforget\fR operation. .PP .CS \fBtk busy\fR forget .top .CE .PP The busy window has a configurable cursor. You can change the busy cursor using the \fBconfigure\fR operation. .PP .CS \fBtk busy\fR configure .top -cursor "watch" .CE .PP Destroying the widget will also clean up any resources allocated by the \fBtk busy\fR command. .PP .SH OPERATIONS .PP The following operations are available for the \fBtk busy\fR command: .TP \fBtk busy \fIwindow\fR ?\fIoption value\fR?... . Shortcut for \fBtk busy hold\fR command. .\" METHOD: busywindow .TP \fBtk busy busywindow \fIwindow\fR . Returns the pathname of the busy window (i.e. the transparent window shielding the window appearing busy) created by the \fBtk busy hold\fR command for \fIwindow\fR, or the empty string if \fIwindow\fR is not busy. .\" METHOD: cget .TP \fBtk busy cget \fIwindow option\fR . Queries the \fBtk busy\fR command configuration options for \fIwindow\fR. \fIWindow\fR must be the path name of a widget previously made busy by the \fBhold\fR operation. The command returns the present value of the specified \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBhold\fR operation. .\" METHOD: configure .TP \fBtk busy configure \fIwindow\fR ?\fIoption value\fR?... . Queries or modifies the \fBtk busy\fR command configuration options for \fIwindow\fR. \fIWindow\fR must be the path name of a widget previously made busy by the \fBhold\fR operation. If no options are specified, a list describing all of the available options for \fIwindow\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list) is returned. If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns the empty string. \fIOption\fR may have any of the values accepted by the \fBhold\fR operation. .RS .PP Please note that the option database is referenced through \fIwindow\fR. For example, if the widget \fB.frame\fR is to be made busy, the busy cursor can be specified for it by either \fBoption\fR command: .PP .CS option add *frame.busyCursor gumby option add *Frame.BusyCursor gumby .CE .RE .\" METHOD: current .TP \fBtk busy current \fR?\fIpattern\fR? . Returns the pathnames of all widgets that are currently busy. If a \fIpattern\fR is given, only the path names of busy widgets matching \fIpattern\fR are returned. .\" METHOD: forget .TP \fBtk busy forget \fIwindow\fR ?\fIwindow\fR?... . Releases resources allocated by the \fBtk busy\fR command for \fIwindow\fR, including the transparent window. User events will again be received by \fIwindow\fR. Resources are also released when \fIwindow\fR is destroyed. \fIWindow\fR must be the name of a widget specified in the \fBhold\fR operation, otherwise an error is reported. .\" METHOD: hold .TP \fBtk busy hold \fIwindow\fR ?\fIoption value\fR?... . Makes the specified \fIwindow\fR (and its descendants in the Tk window hierarchy) appear busy. \fIWindow\fR must be a valid path name of a Tk widget. A transparent window is put in front of the specified window. This transparent window is mapped the next time idle tasks are processed, and the specified window and its descendants will be blocked from user interactions. Normally \fBupdate\fR should be called immediately afterward to insure that the hold operation is in effect before the application starts its processing. The command returns the pathname of the busy window that was created (i.e. the transparent window shielding the window appearing busy). The following configuration options are valid: .RS .\" OPTION: -cursor .TP \fB\-cursor \fIcursorName\fR . Specifies the cursor to be displayed when the widget is made busy. \fICursorName\fR can be in any form accepted by \fBTk_GetCursor\fR. The default cursor is \fBwait\fR on Windows and \fBwatch\fR on other platforms. .RE .\" METHOD: status .TP \fBtk busy status \fIwindow\fR . Returns the status of a widget \fIwindow\fR. If \fIwindow\fR presently can not receive user interactions, \fB1\fR is returned, otherwise \fB0\fR. .SH "EVENT HANDLING" .SS BINDINGS .PP The event blocking feature is implemented by creating and mapping a transparent window that completely covers the widget. When the busy window is mapped, it invisibly shields the widget and its hierarchy from all events that may be sent. Like Tk widgets, busy windows have widget names in the Tk window hierarchy. This means that you can use the \fBbind\fR command to handle events in the busy window: .PP .CS \fBtk busy\fR hold .frame.canvas bind [\fBtk busy\fR busywindow .frame.canvas] { ... } .CE .PP or .CS set busyWin [\fBtk busy\fR hold .frame.canvas] bind $busyWin { ... } .CE .SS "ENTER/LEAVE EVENTS" .PP Mapping and unmapping busy windows generates Enter/Leave events for all widgets they cover. Please note this if you are tracking Enter/Leave events in widgets. .SS "KEYBOARD EVENTS" .PP When a widget is made busy, the widget is prevented from gaining the keyboard focus by a user clicking on it by the busy window. But if the widget already had focus, it still may receive keyboard events. The widget can also still receive focus through keyboard traversal. To prevent this, you must move focus to another window and make sure the focus can not go back to the widgets made busy (e.g. but restricting focus to a cancel button). .PP .CS pack [frame .frame] pack [text .frame.text] \fBtk busy\fR hold .frame pack [button .cancel -text "Cancel" -command exit] focus .cancel bind .cancel {break} bind .cancel {break} update .CE .PP The above example moves the focus from .frame immediately after invoking the \fBhold\fR so that no keyboard events will be sent to \fB.frame\fR or any of its descendants. It also makes sure it's not possible to leave button \fB.cancel\fR using the keyboard. .SH PORTABILITY .PP Note that the \fBtk busy\fR command does not currently have any effect on macOS when Tk is built using Aqua support. .SH "SEE ALSO" grab(n) .SH KEYWORDS busy, keyboard events, pointer events, window '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/button.n0000644001000000100000000002156315076161055017316 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH button n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME button \- Create and manipulate 'button' action widgets .SH SYNOPSIS \fBbutton\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-font \-relief \-activeforeground \-foreground \-repeatdelay \-anchor \-highlightbackground \-repeatinterval \-background \-highlightcolor \-takefocus \-bitmap \-highlightthickness \-text \-borderwidth \-image \-textvariable \-compound \-justify \-underline \-cursor \-padx \-wraplength \-disabledforeground \-pady .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command Specifies a Tcl command to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. .OP \-default default Default Specifies one of three states for the default ring: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In active state, the button is drawn with the platform specific appearance for a default button. In normal state, the button is drawn with the platform specific appearance for a non-default button, leaving enough space to draw the default button appearance. The normal and active states will result in buttons of the same size. In disabled state, the button is drawn with the non-default button appearance without leaving space for the default appearance. The disabled state may result in a smaller button than the active state. .OP \-height height Height Specifies a desired height for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); for text it is in lines of text. If this option is not specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it. .OP \-overrelief overRelief OverRelief Specifies an alternative relief for the button, to be used when the mouse cursor is over the widget. This option can be used to make toolbar buttons, by configuring \fB\-relief flat \-overrelief raised\fR. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the button. The empty string is the default value. .OP \-state state State Specifies one of three states for the button: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the button is displayed using the \fB\-foreground\fR and \fB\-background\fR options. The active state is typically used when the pointer is over the button. In active state the button is displayed using the \fB\-activeforeground\fR and \fB\-activebackground\fR options. Disabled state means that the button should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the \fB\-disabledforeground\fR and \fB\-background\fR options determine how the button is displayed. .OP \-width width Width Specifies a desired width for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR). For a text button (no image or with \fB\-compound none\fR) then the width specifies how much space in characters to allocate for the text label. If the width is negative then this specifies a minimum width. If this option is not specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it. .BE .SH DESCRIPTION .PP The \fBbutton\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a button widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the button such as its colors, font, text, and initial relief. The \fBbutton\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A button is a widget that displays a textual string, bitmap or image. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the \fB\-wraplength\fR option) and one of the characters may optionally be underlined using the \fB\-underline\fR option. It can display itself in either of three different ways, according to the \fB\-state\fR option; it can be made to appear raised, sunken, or flat; and it can be made to flash. When a user invokes the button (by pressing mouse button 1 with the cursor over the button), then the Tcl command specified in the \fB\-command\fR option is invoked. .SH "WIDGET COMMAND" .PP The \fBbutton\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for button widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBbutton\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBbutton\fR command. .\" METHOD: flash .TP \fIpathName \fBflash\fR . Flash the button. This is accomplished by redisplaying the button several times, alternating between the configured activebackground and background colors. At the end of the flash the button is left in the same normal/active state as when the command was invoked. This command is ignored if the button's state is \fBdisabled\fR. .\" METHOD: invoke .TP \fIpathName \fBinvoke\fR . Invoke the Tcl command associated with the button, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the button. This command is ignored if the button's state is \fBdisabled\fR. .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for buttons that give them default behavior: .IP [1] A button activates whenever the mouse passes over it and deactivates whenever the mouse leaves the button. Under Windows, this binding is only active when mouse button 1 has been pressed over the button. .IP [2] A button's relief is changed to sunken whenever mouse button 1 is pressed over the button, and the relief is restored to its original value when button 1 is later released. .IP [3] If mouse button 1 is pressed over a button and later released over the button, the button is invoked. However, if the mouse is not over the button when button 1 is released, then no invocation occurs. .IP [4] When a button has the input focus, the space key causes the button to be invoked. .PP If the button's state is \fBdisabled\fR then none of the above actions occur: the button is completely non-responsive. .PP The behavior of buttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "PLATFORM NOTES" .PP On Aqua/macOS, some configuration options are ignored for the purpose of drawing of the widget because they would otherwise conflict with platform guidelines. The \fBconfigure\fR and \fBcget\fR subcommands can still manipulate the values, but do not cause any variation to the look of the widget. The options affected notably include \fB\-background\fR and \fB\-relief\fR. .SH EXAMPLES .PP This is the classic Tk .QW "Hello, World!" demonstration: .PP .CS \fBbutton\fR .b -text "Hello, World!" -command exit pack .b .CE .PP This example demonstrates how to handle button accelerators: .PP .CS \fBbutton\fR .b1 -text Hello -underline 0 \fBbutton\fR .b2 -text World -underline 0 bind . {.b1 flash; .b1 invoke} bind . {.b2 flash; .b2 invoke} pack .b1 .b2 .CE .SH "SEE ALSO" ttk::button(n) .SH KEYWORDS button, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/canvas.n0000644001000000100000000025267315105057705017265 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" Copyright (c) 1997-1999 Scriptics Corporation. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH canvas n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME canvas \- Create and manipulate 'canvas' hypergraphics drawing surface widgets .SH SYNOPSIS \fBcanvas\fI pathName \fR?\fIoptions\fR? .SO \-background \-borderwidth \-cursor \-highlightbackground \-highlightcolor \-highlightthickness \-insertbackground \-insertborderwidth \-insertofftime \-insertontime \-insertwidth \-relief \-selectbackground \-selectborderwidth \-selectforeground \-takefocus \-xscrollcommand \-yscrollcommand .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-closeenough closeEnough CloseEnough Specifies a floating-point value indicating how close the mouse cursor must be to an item before it is considered to be .QW inside the item. Defaults to 1.0. .OP \-confine confine Confine Specifies a boolean value that indicates whether or not it should be allowable to set the canvas's view outside the region defined by the \fBscrollRegion\fR argument. Defaults to true, which means that the view will be constrained within the scroll region. .OP \-height height Height Specifies a desired window height that the canvas widget should request from its geometry manager. The value may be specified in any of the forms described in the \fBCOORDINATES\fR section below. .OP \-scrollregion scrollRegion ScrollRegion Specifies a list with four coordinates describing the left, top, right, and bottom coordinates of a rectangular region. This region is used for scrolling purposes and is considered to be the boundary of the information in the canvas. Each of the coordinates may be specified in any of the forms given in the \fBCOORDINATES\fR section below. .OP \-state state State Modifies the default state of the canvas where \fIstate\fR may be set to one of: \fBnormal\fR, \fBdisabled\fR, or \fBhidden\fR. Individual canvas objects all have their own state option which may override the default state. Many options can take separate specifications such that the appearance of the item can be different in different situations. The options that start with \fBactive\fR control the appearance when the mouse pointer is over it, while the option starting with \fBdisabled\fR controls the appearance when the state is disabled. Canvas items which are \fBdisabled\fR will not react to canvas bindings. .OP \-width width width Specifies a desired window width that the canvas widget should request from its geometry manager. The value may be specified in any of the forms described in the \fBCOORDINATES\fR section below. .OP \-xscrollincrement xScrollIncrement ScrollIncrement Specifies an increment for horizontal scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the horizontal view in the window will be constrained so that the canvas x coordinate at the left edge of the window is always an even multiple of \fBxScrollIncrement\fR; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be \fBxScrollIncrement\fR. If the value of this option is negative or zero, then horizontal scrolling is unconstrained. .OP \-yscrollincrement yScrollIncrement ScrollIncrement Specifies an increment for vertical scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the vertical view in the window will be constrained so that the canvas y coordinate at the top edge of the window is always an even multiple of \fByScrollIncrement\fR; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be \fByScrollIncrement\fR. If the value of this option is negative or zero, then vertical scrolling is unconstrained. .BE .SH INTRODUCTION .PP The \fBcanvas\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a canvas widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the canvas such as its colors and 3-D relief. The \fBcanvas\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP Canvas widgets implement structured graphics. A canvas displays any number of \fIitems\fR, which may be things like rectangles, circles, lines, and text. Items may be manipulated (e.g. moved or re-colored) and commands may be associated with items in much the same way that the \fBbind\fR command allows commands to be bound to widgets. For example, a particular command may be associated with the event so that the command is invoked whenever button 1 is pressed with the mouse cursor over an item. This means that items in a canvas can have behaviors defined by the Tcl scripts bound to them. .SH "DISPLAY LIST" .PP The items in a canvas are ordered for purposes of display, with the first item in the display list being displayed first, followed by the next item in the list, and so on. Items later in the display list obscure those that are earlier in the display list and are sometimes referred to as being .QW "on top" of earlier items. When a new item is created it is placed at the end of the display list, on top of everything else. Widget commands may be used to re-arrange the order of the display list. .PP Window items are an exception to the above rules. The underlying window systems require them always to be drawn on top of other items. In addition, the stacking order of window items is not affected by any of the canvas widget commands; you must use the Tk \fBraise\fR command and \fBlower\fR command instead. .SH "ITEM IDS AND TAGS" .PP Items in a canvas widget may be named in either of two ways: by id or by tag. Each item has a unique identifying number, which is assigned to that item when it is created. The id of an item never changes and id numbers are never re-used within the lifetime of a canvas widget. .PP Each item may also have any number of \fItags\fR associated with it. A tag is just a string of characters, and it may take any form except that of an integer. For example, .QW x123 is OK but .QW 123 is not. The same tag may be associated with many different items. This is commonly done to group items in various interesting ways; for example, all selected items might be given the tag .QW selected . .PP The tag \fBall\fR is implicitly associated with every item in the canvas; it may be used to invoke operations on all the items in the canvas. .PP The tag \fBcurrent\fR is managed automatically by Tk; it applies to the \fIcurrent item\fR, which is the topmost item whose drawn area covers the position of the mouse cursor (different item types interpret this in varying ways; see the individual item type documentation for details). If the mouse is not in the canvas widget or is not over an item, then no item has the \fBcurrent\fR tag. .PP When specifying items in canvas widget commands, if the specifier is an integer then it is assumed to refer to the single item with that id. If the specifier is not an integer, then it is assumed to refer to all of the items in the canvas that have a tag matching the specifier. The symbol \fItagOrId\fR is used below to indicate that an argument specifies either an id that selects a single item or a tag that selects zero or more items. .PP \fItagOrId\fR may contain a logical expressions of tags by using operators: .QW \fB&&\fR , .QW \fB||\fR , .QW \fB^\fR , .QW \fB!\fR , and parenthesized subexpressions. For example: .CS .c find withtag {(a&&!b)||(!a&&b)} .CE or equivalently: .CS .c find withtag {a^b} .CE will find only those items with either .QW a or .QW b tags, but not both. .PP Some widget commands only operate on a single item at a time; if \fItagOrId\fR is specified in a way that names multiple items, then the normal behavior is for the command to use the first (lowest) of these items in the display list that is suitable for the command. Exceptions are noted in the widget command descriptions below. .SH "COORDINATES" .PP All coordinates related to canvases are stored as floating-point numbers. Coordinates and distances are specified in screen units, which are floating-point numbers optionally followed by one of several letters. If no letter is supplied then the distance is in pixels. If the letter is \fBm\fR then the distance is in millimeters on the screen; if it is \fBc\fR then the distance is in centimeters; \fBi\fR means inches, and \fBp\fR means printers points (1/72 inch). Larger y-coordinates refer to points lower on the screen; larger x-coordinates refer to points farther to the right. Coordinates can be specified either as an even number of parameters, or as a single list parameter containing an even number of x and y coordinate values. .SS TRANSFORMATIONS .PP Normally the origin of the canvas coordinate system is at the upper-left corner of the window containing the canvas. It is possible to adjust the origin of the canvas coordinate system relative to the origin of the window using the \fBxview\fR and \fByview\fR widget commands; this is typically used for scrolling. Canvases do not support scaling or rotation of the canvas coordinate system relative to the window coordinate system. .PP Individual items may be moved, scaled .VS "9.0, TIP164" or rotated .VE "9.0, TIP164" using widget commands described below. .PP Note that the default origin of the canvas's visible area is coincident with the origin for the whole window as that makes bindings using the mouse position easier to work with; you only need to use the \fBcanvasx\fR and \fBcanvasy\fR widget commands if you adjust the origin of the visible area. However, this also means that any focus ring (as controlled by the \fB\-highlightthickness\fR option) and window border (as controlled by the \fB\-borderwidth\fR option) must be taken into account before you get to the visible area of the canvas. .SH "INDICES" .PP Text items support the notion of an \fIindex\fR for identifying particular positions within the item. In a similar fashion, line and polygon items support \fIindex\fR for identifying, inserting and deleting subsets of their coordinates. Indices are used for commands such as inserting or deleting a range of characters or coordinates, and setting the insertion cursor position. An index may be specified in any of a number of ways, and different types of items may support different forms for specifying indices. Text items support the following forms for an index; if you define new types of text-like items, it would be advisable to support as many of these forms as practical. Note that it is possible to refer to the character just after the last one in the text item; this is necessary for such tasks as inserting new text at the end of the item. Lines and Polygons do not support the insertion cursor and the selection. Their indices are supposed to be even always, because coordinates always appear in pairs. .IP \fInumber\fR 10 A decimal number giving the position of the desired character within the text item. 0 refers to the first character, 1 to the next character, and so on. If indexes are odd for lines and polygons, they will be automatically decremented by one. A negative number is treated as if it were zero, and a number greater than the length of the text item is treated as if it were equal to the length of the text item. For polygons, negative numbers or numbers greater than the length of the coordinate list will be adjusted by adding or subtracting the length until the result is between zero and the length, inclusive. .IP \fBend\fR 10 Refers to the character or coordinate just after the last one in the item (same as the number of characters or coordinates in the item). .IP \fBinsert\fR 10 Refers to the character just before which the insertion cursor is drawn in this item. Not valid for lines and polygons. .IP \fBsel.first\fR 10 Refers to the first selected character in the item. If the selection is not in this item then this form is illegal. .IP \fBsel.last\fR 10 Refers to the last selected character in the item. If the selection is not in this item then this form is illegal. .IP \fB@\fIx,y\fR 10 Refers to the character or coordinate at the point given by \fIx\fR and \fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinate system of the canvas. If \fIx\fR and \fIy\fR lie outside the coordinates covered by the text item, then they refer to the first or last character in the line that is closest to the given point. .SH "DASH PATTERNS" .PP Many items support the notion of a dash pattern for outlines. .PP The first possible syntax is a list of integers. Each element represents the number of pixels of a line segment. Only the odd segments are drawn using the .QW outline color. The other segments are drawn transparent. .PP The second possible syntax is a character list containing only 5 possible characters .QW "\fB.,-_ \fR" . The space can be used to enlarge the space between other line elements, and cannot occur as the first position in the string. Some examples: .PP .CS \-dash . \(-> \-dash {2 4} \-dash - \(-> \-dash {6 4} \-dash -. \(-> \-dash {6 4 2 4} \-dash -.. \(-> \-dash {6 4 2 4 2 4} \-dash {. } \(-> \-dash {2 8} \-dash , \(-> \-dash {4 4} .CE .PP The main difference of this syntax with the previous is that it is shape-conserving. This means that all values in the dash list will be multiplied by the line width before display. This assures that .QW . will always be displayed as a dot and .QW - always as a dash regardless of the line width. .PP On systems which support only a limited set of dash patterns, the dash pattern will be displayed as the closest dash pattern that is available. For example, on Windows only the first 4 of the above examples are available. The last 2 examples will be displayed identically to the first one. .SH "WIDGET COMMAND" .PP The \fBcanvas\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following widget commands are possible for canvas widgets: .\" METHOD: addtag .TP \fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg ...\fR? . For each item that meets the constraints specified by \fIsearchSpec\fR and the \fIarg\fRs, add \fItag\fR to the list of tags associated with the item if it is not already present on that list. It is possible that no items will satisfy the constraints given by \fIsearchSpec\fR and \fIarg\fRs, in which case the command has no effect. This command returns an empty string as result. \fISearchSpec\fR and \fIarg\fR's may take any of the following forms: .RS .IP "\fBabove \fItagOrId\fR" Selects the item just after (above) the one given by \fItagOrId\fR in the display list. If \fItagOrId\fR denotes more than one item, then the last (topmost) of these items in the display list is used. .IP \fBall\fR Selects all the items in the canvas. .IP "\fBbelow \fItagOrId\fR" Selects the item just before (below) the one given by \fItagOrId\fR in the display list. If \fItagOrId\fR denotes more than one item, then the first (lowest) of these items in the display list is used. .IP "\fBclosest \fIx y \fR?\fIhalo\fR? ?\fIstart\fR?" Selects the item closest to the point given by \fIx\fR and \fIy\fR. If more than one item is at the same closest distance (e.g. two items overlap the point), then the top-most of these items (the last one in the display list) is used. If \fIhalo\fR is specified, then it must be a non-negative value. Any item closer than \fIhalo\fR to the point is considered to overlap it. The \fIstart\fR argument may be used to step circularly through all the closest items. If \fIstart\fR is specified, it names an item using a tag or id (if by tag, it selects the first item in the display list with the given tag). Instead of selecting the topmost closest item, this form will select the topmost closest item that is below \fIstart\fR in the display list; if no such item exists, then the selection behaves as if the \fIstart\fR argument had not been specified. .IP "\fBenclosed\fI x1 y1 x2 y2\fR" Selects all the items completely enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. \fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be no greater than \fIy2\fR. .IP "\fBoverlapping\fI x1 y1 x2 y2\fR" Selects all the items that overlap or are enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. \fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be no greater than \fIy2\fR. .IP "\fBwithtag \fItagOrId\fR" Selects all the items given by \fItagOrId\fR. .RE .\" METHOD: bbox .TP \fIpathName \fBbbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR? . Returns a list with four elements giving an approximate bounding box for all the items named by the \fItagOrId\fR arguments. The list has the form .QW "\fIx1 y1 x2 y2\fR" such that the drawn areas of all the named elements are within the region bounded by \fIx1\fR on the left, \fIx2\fR on the right, \fIy1\fR on the top, and \fIy2\fR on the bottom. The return value may overestimate the actual bounding box by a few pixels. If no items match any of the \fItagOrId\fR arguments or if the matching items have empty bounding boxes (i.e. they have nothing to display) then an empty string is returned. .\" METHOD: bind .TP \fIpathName \fBbind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR? . This command associates \fIcommand\fR with all the items given by \fItagOrId\fR such that whenever the event sequence given by \fIsequence\fR occurs for one of the items the command will be invoked. This widget command is similar to the \fBbind\fR command except that it operates on items in a canvas rather than entire widgets. See the \fBbind\fR manual entry for complete details on the syntax of \fIsequence\fR and the substitutions performed on \fIcommand\fR before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same \fIsequence\fR and \fItagOrId\fR (if the first character of \fIcommand\fR is .QW + then \fIcommand\fR augments an existing binding rather than replacing it). In this case the return value is an empty string. If \fIcommand\fR is omitted then the command returns the \fIcommand\fR associated with \fItagOrId\fR and \fIsequence\fR (an error occurs if there is no such binding). If both \fIcommand\fR and \fIsequence\fR are omitted then the command returns a list of all the sequences for which bindings have been defined for \fItagOrId\fR. .RS .PP The only events for which bindings may be specified are those related to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, \fBButton\fR, \fBMotion\fR, and \fBKey\fR) or virtual events. The handling of events in canvases uses the current item defined in \fBITEM IDS AND TAGS\fR above. \fBEnter\fR and \fBLeave\fR events trigger for an item when it becomes the current item or ceases to be the current item; note that these events are different than \fBEnter\fR and \fBLeave\fR events for windows. Mouse-related events are directed to the current item, if any. Keyboard-related events are directed to the focus item, if any (see the \fBfocus\fR widget command below for more on this). If a virtual event is used in a binding, that binding can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event. .PP It is possible for multiple bindings to match a particular event. This could occur, for example, if one binding is associated with the item's id and another is associated with one of the item's tags. When this occurs, all of the matching bindings are invoked. A binding associated with the \fBall\fR tag is invoked first, followed by one binding for each of the item's tags (in order), followed by a binding associated with the item's id. If there are multiple matching bindings for a single tag, then only the most specific binding is invoked. A \fBcontinue\fR command in a binding script terminates that script, and a \fBbreak\fR command terminates that script and skips any remaining scripts for the event, just as for the \fBbind\fR command. .PP If bindings have been created for a canvas window using the \fBbind\fR command, then they are invoked in addition to bindings created for the canvas's items using the \fBbind\fR widget command. The bindings for items will be invoked before any of the bindings for the window as a whole. .RE .\" METHOD: canvasx .TP \fIpathName \fBcanvasx \fIscreenx\fR ?\fIgridspacing\fR? . Given a window x-coordinate in the canvas \fIscreenx\fR, this command returns the canvas x-coordinate that is displayed at that location. If \fIgridspacing\fR is specified, then the canvas coordinate is rounded to the nearest multiple of \fIgridspacing\fR units. .\" METHOD: canvasy .TP \fIpathName \fBcanvasy \fIscreeny\fR ?\fIgridspacing\fR? . Given a window y-coordinate in the canvas \fIscreeny\fR this command returns the canvas y-coordinate that is displayed at that location. If \fIgridspacing\fR is specified, then the canvas coordinate is rounded to the nearest multiple of \fIgridspacing\fR units. .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBcanvas\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBcanvas\fR command. .\" METHOD: coords .TP \fIpathName \fBcoords \fItagOrId \fR?\fIx0 y0 ...\fR? .TP \fIpathName \fBcoords \fItagOrId \fR?\fIcoordList\fR? . Query or modify the coordinates that define an item. If no coordinates are specified, this command returns a list whose elements are the coordinates of the item named by \fItagOrId\fR. If coordinates are specified, then they replace the current coordinates for the named item. If \fItagOrId\fR refers to multiple items, then the first one in the display list is used. .RS .PP Note that for rectangles, ovals and arcs the returned list of coordinates has a fixed order, namely the left, top, right and bottom coordinates, which may not be the order originally given. Also the coordinates are always returned in screen units with no units (that is, in pixels). So if the original coordinates were specified for instance in centimeters or inches, the returned values will nevertheless be in pixels. .RE .\" METHOD: create .TP \fIpathName \fBcreate \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR? .TP \fIpathName \fBcreate \fItype coordList \fR?\fIoption value ...\fR? . Create a new item in \fIpathName\fR of type \fItype\fR. The exact format of the arguments after \fItype\fR depends on \fItype\fR, but usually they consist of the coordinates for one or more points, followed by specifications for zero or more item options. See the subsections on individual item types below for more on the syntax of this command. This command returns the id for the new item. .\" METHOD: dchars .TP \fIpathName \fBdchars \fItagOrId first \fR?\fIlast\fR? . For each item given by \fItagOrId\fR, delete the characters, or coordinates, in the range given by \fIfirst\fR and \fIlast\fR, inclusive. If some of the items given by \fItagOrId\fR do not support indexing operations then they ignore this operation. Text items interpret \fIfirst\fR and \fIlast\fR as indices to a character, line and polygon items interpret them as indices to a coordinate (an x,y pair). Indices are described in \fBINDICES\fR above. If \fIlast\fR is omitted, it defaults to \fIfirst\fR. This command returns an empty string. .\" METHOD: delete .TP \fIpathName \fBdelete \fR?\fItagOrId tagOrId ...\fR? . Delete each of the items given by each \fItagOrId\fR, and return an empty string. .\" METHOD: dtag .TP \fIpathName \fBdtag \fItagOrId \fR?\fItagToDelete\fR? . For each of the items given by \fItagOrId\fR, delete the tag given by \fItagToDelete\fR from the list of those associated with the item. If an item does not have the tag \fItagToDelete\fR then the item is unaffected by the command. If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR. This command returns an empty string. .\" METHOD: find .TP \fIpathName \fBfind \fIsearchCommand \fR?\fIarg ...\fR? . This command returns a list consisting of all the items that meet the constraints specified by \fIsearchCommand\fR and \fIarg\fR's. \fISearchCommand\fR and \fIargs\fR have any of the forms accepted by the \fBaddtag\fR command. The items are returned in stacking order, with the lowest item first. .\" METHOD: focus .TP \fIpathName \fBfocus \fR?\fItagOrId\fR? . Set the keyboard focus for the canvas widget to the item given by \fItagOrId\fR. If \fItagOrId\fR refers to several items, then the focus is set to the first such item in the display list that supports the insertion cursor. If \fItagOrId\fR does not refer to any items, or if none of them support the insertion cursor, then the focus is not changed. If \fItagOrId\fR is an empty string, then the focus item is reset so that no item has the focus. If \fItagOrId\fR is not specified then the command returns the id for the item that currently has the focus, or an empty string if no item has the focus. .RS .PP Once the focus has been set to an item, the item will display the insertion cursor and all keyboard events will be directed to that item. The focus item within a canvas and the focus window on the screen (set with the \fBfocus\fR command) are totally independent: a given item does not actually have the input focus unless (a) its canvas is the focus window and (b) the item is the focus item within the canvas. In most cases it is advisable to follow the \fBfocus\fR widget command with the \fBfocus\fR command to set the focus window to the canvas (if it was not there already). .RE .\" METHOD: gettags .TP \fIpathName \fBgettags\fI tagOrId\fR . Return a list whose elements are the tags associated with the item given by \fItagOrId\fR. If \fItagOrId\fR refers to more than one item, then the tags are returned from the first such item in the display list. If \fItagOrId\fR does not refer to any items, or if the item contains no tags, then an empty string is returned. .\" METHOD: icursor .TP \fIpathName \fBicursor \fItagOrId index\fR . Set the position of the insertion cursor for the item(s) given by \fItagOrId\fR to just before the character whose position is given by \fIindex\fR. If some or all of the items given by \fItagOrId\fR do not support an insertion cursor then this command has no effect on them. See \fBINDICES\fR above for a description of the legal forms for \fIindex\fR. .RS .PP Note that the insertion cursor is only displayed in an item if that item currently has the keyboard focus (see the \fBfocus\fR widget command, above), but the cursor position may be set even when the item does not have the focus. .PP This command returns an empty string. .RE .\" METHOD: image .TP \fIpathName \fBimage \fIimagename\fR ?\fIsubsample\fR? ?\fIzoom\fR? . Draw the canvas into the Tk photo image named \fIimagename\fR. If a \fB\-scrollregion\fR has been defined then this will be the boundaries of the canvas region drawn and the final size of the photo image. Otherwise the widget width and height with an origin of 0,0 will be the size of the canvas region drawn and the final size of the photo image. Optionally an integer \fIsubsample\fR factor may be given and the photo image will be reduced in size. .RS .PP In addition to the \fIsubsample\fR an integer \fIzoom\fR factor can also be given and the photo image will be enlarged. The image background will be filled with the canvas background colour. The canvas widget does not need to be mapped for this widget command to work, but at least one of it's ancestors must be mapped. .PP This command returns an empty string. .RE .\" METHOD: imove .TP \fIpathName \fBimove \fItagOrId index x y\fR . This command causes the \fIindex\fR'th coordinate of each of the items indicated by \fItagOrId\fR to be relocated to the location (\fIx\fR,\fIy\fR). Each item interprets \fIindex\fR independently according to the rules described in \fBINDICES\fR above. Out of the standard set of items, only line and polygon items may have their coordinates relocated this way. .\" METHOD: index .TP \fIpathName \fBindex \fItagOrId index\fR . This command returns a decimal string giving the numerical index within \fItagOrId\fR corresponding to \fIindex\fR. \fIIndex\fR gives a textual description of the desired position as described in \fBINDICES\fR above. Text items interpret \fIindex\fR as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). The return value is guaranteed to lie between 0 and the number of characters, or coordinates, within the item, inclusive. If \fItagOrId\fR refers to multiple items, then the index is processed in the first of these items that supports indexing operations (in display list order). .\" METHOD: insert .TP \fIpathName \fBinsert \fItagOrId beforeThis string\fR . For each of the items given by \fItagOrId\fR, if the item supports text or coordinate, insertion then \fIstring\fR is inserted into the item's text just before the character, or coordinate, whose index is \fIbeforeThis\fR. Text items interpret \fIbeforeThis\fR as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). For lines and polygons the \fIstring\fR must be a valid coordinate sequence. .RS .PP See \fBINDICES\fR above for information about the forms allowed for \fIbeforeThis\fR. .PP This command returns an empty string. .RE .\" METHOD: itemcget .TP \fIpathName \fBitemcget\fI tagOrId option\fR . Returns the current value of the configuration option for the item given by \fItagOrId\fR whose name is \fIoption\fR. This command is similar to the \fBcget\fR widget command except that it applies to a particular item rather than the widget as a whole. \fIOption\fR may have any of the values accepted by the \fBcreate\fR widget command when the item was created. If \fItagOrId\fR is a tag that refers to more than one item, the first (lowest) such item is used. .\" METHOD: itemconfigure .TP \fIpathName \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? . This command is similar to the \fBconfigure\fR widget command except that it modifies item-specific options for the items given by \fItagOrId\fR instead of modifying options for the overall canvas widget. If no \fIoption\fR is specified, returns a list describing all of the available options for the first item given by \fItagOrId\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s) in each of the items given by \fItagOrId\fR; in this case the command returns an empty string. The \fIoption\fRs and \fIvalue\fRs are the same as those permissible in the \fBcreate\fR widget command when the item(s) were created; see the sections describing individual item types below for details on the legal options. .\" METHOD: lower .TP \fIpathName \fBlower \fItagOrId \fR?\fIbelowThis\fR? . Move all of the items given by \fItagOrId\fR to a new position in the display list just before the item given by \fIbelowThis\fR. If \fItagOrId\fR refers to more than one item then all are moved but the relative order of the moved items will not be changed. \fIBelowThis\fR is a tag or id; if it refers to more than one item then the first (lowest) of these items in the display list is used as the destination location for the moved items. Note that this command has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the \fBraise\fR command and \fBlower\fR command, not the \fBraise\fR widget command and \fBlower\fR widget command for canvases. This command returns an empty string. .\" METHOD: move .TP \fIpathName \fBmove \fItagOrId xAmount yAmount\fR . Move each of the items given by \fItagOrId\fR in the canvas coordinate space by adding \fIxAmount\fR to the x-coordinate of each point associated with the item and \fIyAmount\fR to the y-coordinate of each point associated with the item. This command returns an empty string. .\" METHOD: moveto .TP \fIpathName \fBmoveto \fItagOrId xPos yPos\fR . Move the items given by \fItagOrId\fR in the canvas coordinate space so that the first coordinate pair (the upper-left corner of the bounding box) of the first item (the lowest in the display list) with tag \fItagOrId\fR is located at position (\fIxPos\fR,\fIyPos\fR). \fIxPos\fR and \fIyPos\fR may be the empty string, in which case the corresponding coordinate will be unchanged. All items matching \fItagOrId\fR remain in the same positions relative to each other. This command returns an empty string. .\" METHOD: postscript .TP \fIpathName \fBpostscript \fR?\fIoption value option value ...\fR? . Generate a Postscript representation for part or all of the canvas. If the \fB\-file\fR option is specified then the Postscript is written to a file and an empty string is returned; otherwise the Postscript is returned as the result of the command. If the interpreter that owns the canvas is marked as safe, the operation will fail because safe interpreters are not allowed to write files. If the \fB\-channel\fR option is specified, the argument denotes the name of a channel already opened for writing. The Postscript is written to that channel, and the channel is left open for further writing at the end of the operation. The Postscript is created in Encapsulated Postscript form using version 3.0 of the Document Structuring Conventions. Note: by default Postscript is only generated for information that appears in the canvas's window on the screen. If the canvas is freshly created it may still have its initial size of 1x1 pixel so nothing will appear in the Postscript. To get around this problem either invoke the \fBupdate\fR command to wait for the canvas window to reach its final size, or else use the \fB\-width\fR and \fB\-height\fR options to specify the area of the canvas to print. The \fIoption\fR\-\fIvalue\fR argument pairs provide additional information to control the generation of Postscript. The following options are supported: .RS .\" OPTION: -channel .TP \fB\-channel \fIchannelName\fR . Specifies the name of the channel to which to write the Postscript. If this option and the \fB\-file\fR option are not specified then the Postscript is returned as the result of the command. .\" OPTION: -colormap .TP \fB\-colormap \fIvarName\fR . \fIVarName\fR must be the name of an array variable that specifies a color mapping to use in the Postscript. Each element of \fIvarName\fR must consist of Postscript code to set a particular color value (e.g. .QW "\fB1.0 1.0 0.0 setrgbcolor\fR" ). When outputting color information in the Postscript, Tk checks to see if there is an element of \fIvarName\fR with the same name as the color. If so, Tk uses the value of the element as the Postscript command to set the color. .RS .PP If this option has not been specified, or if there is no entry in \fIvarName\fR for a given color, then Tk uses the red, green, and blue intensities from the X color. .RE .\" OPTION: -colormode .TP \fB\-colormode \fImode\fR . Specifies how to output color information. \fIMode\fR must be either \fBcolor\fR (for full color output), \fBgray\fR (convert all colors to their gray-scale equivalents) or \fBmono\fR (convert all colors to black or white). .\" OPTION: -file .TP \fB\-file \fIfileName\fR . Specifies the name of the file in which to write the Postscript. If this option and the \fB\-channel\fR option are not specified then the Postscript is returned as the result of the command. .\" OPTION: -fontmap .TP \fB\-fontmap \fIvarName\fR . \fIVarName\fR must be the name of an array variable that specifies a font mapping to use in the Postscript. Each element of \fIvarName\fR must consist of a Tcl list with two elements, which are the name and point size of a Postscript font. When outputting Postscript commands for a particular font, Tk checks to see if \fIvarName\fR contains an element with the same name as the font. If there is such an element, then the font information contained in that element is used in the Postscript. Otherwise Tk attempts to guess what Postscript font to use. Tk's guesses generally only work for well-known fonts such as Times and Helvetica and Courier, and only if the X font name does not omit any dashes up through the point size. .RS .PP For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-*\fR will work but \fB*Courier\-Bold\-R\-Normal*120*\fR will not; Tk needs the dashes to parse the font name). .RE .\" OPTION: -height .TP \fB\-height \fIsize\fR . Specifies the height of the area of the canvas to print. Defaults to the height of the canvas window. .\" OPTION: -pageanchor .TP \fB\-pageanchor \fIanchor\fR . Specifies which point of the printed area of the canvas should appear over the positioning point on the page (which is given by the \fB\-pagex\fR and \fB\-pagey\fR options). .RS .PP For example, \fB\-pageanchor n\fR means that the top center of the area of the canvas being printed (as it appears in the canvas window) should be over the positioning point. Defaults to \fBcenter\fR. .RE .\" OPTION: -pageheight .TP \fB\-pageheight \fIsize\fR . Specifies that the Postscript should be scaled in both x and y so that the printed area is \fIsize\fR high on the Postscript page. \fISize\fR consists of a floating-point number followed by \fBc\fR for centimeters, \fBi\fR for inches, \fBm\fR for millimeters, or \fBp\fR or nothing for printer's points (1/72 inch). Defaults to the height of the printed area on the screen. If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling is not implemented). .\" OPTION: -pagewidth .TP \fB\-pagewidth \fIsize\fR . Specifies that the Postscript should be scaled in both x and y so that the printed area is \fIsize\fR wide on the Postscript page. \fISize\fR has the same form as for \fB\-pageheight\fR. Defaults to the width of the printed area on the screen. If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling is not implemented). .\" OPTION: -pagex .TP \fB\-pagex \fIposition\fR . \fIPosition\fR gives the x-coordinate of the positioning point on the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. Used in conjunction with the \fB\-pagey\fR and \fB\-pageanchor\fR options to determine where the printed area appears on the Postscript page. Defaults to the center of the page. .\" OPTION: -pagey .TP \fB\-pagey \fIposition\fR . \fIPosition\fR gives the y-coordinate of the positioning point on the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. Used in conjunction with the \fB\-pagex\fR and \fB\-pageanchor\fR options to determine where the printed area appears on the Postscript page. Defaults to the center of the page. .\" OPTION: -rotate .TP \fB\-rotate \fIboolean\fR . \fIBoolean\fR specifies whether the printed area is to be rotated 90 degrees. In non-rotated output the x-axis of the printed area runs along the short dimension of the page .PQ portrait " orientation" ; in rotated output the x-axis runs along the long dimension of the page .PQ landscape " orientation" . Defaults to non-rotated. .\" OPTION: -width .TP \fB\-width \fIsize\fR . Specifies the width of the area of the canvas to print. Defaults to the width of the canvas window. .\" OPTION: -x .TP \fB\-x \fIposition\fR . Specifies the x-coordinate of the left edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the left edge of the window. .\" OPTION: -y .TP \fB\-y \fIposition\fR . Specifies the y-coordinate of the top edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the top edge of the window. .RE .\" METHOD: raise .TP \fIpathName \fBraise \fItagOrId \fR?\fIaboveThis\fR? . Move all of the items given by \fItagOrId\fR to a new position in the display list just after the item given by \fIaboveThis\fR. If \fItagOrId\fR refers to more than one item then all are moved but the relative order of the moved items will not be changed. \fIAboveThis\fR is a tag or id; if it refers to more than one item then the last (topmost) of these items in the display list is used as the destination location for the moved items. This command returns an empty string. .RS .PP Note this this command has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the \fBraise\fR command and \fBlower\fR command, not the \fBraise\fR widget command and \fBlower\fR widget command for canvases. .RE .\" METHOD: rchars .TP \fIpathName \fBrchars \fItagOrId first last string\fR . This command causes the text or coordinates between \fIfirst\fR and \fIlast\fR for each of the items indicated by \fItagOrId\fR to be replaced by \fIstring\fR. Each item interprets \fIfirst\fR and \fIlast\fR independently according to the rules described in \fBINDICES\fR above. Out of the standard set of items, text items support this operation by altering their text as directed, and line and polygon items support this operation by altering their coordinate list (in which case \fIstring\fR should be a list of coordinates to use as a replacement). The other items ignore this operation. .\" METHOD: rotate .TP \fIpathName \fBrotate \fItagOrId xOrigin yOrigin angle\fR .VS "9.0, TIP164" Rotate the coordinates of all of the items given by \fItagOrId\fR in canvas coordinate space. \fIXOrigin\fR and \fIyOrigin\fR identify the origin for the rotation operation and \fIangle\fR identifies the amount to rotate the coordinates anticlockwise, in degrees. (Negative values rotate clockwise.) This command returns an empty string. .RS .PP Implementation note: not all item types work the same with rotations. In particular,\fB bitmap\fR,\fB image\fR,\fB text\fR and\fB window\fR items only rotate their anchor points and do not rotate the items themselves about those points, and the \fBarc\fR, \fBoval\fR and \fBrectangle\fR types rotate about a computed center point instead of moving the bounding box coordinates directly. .PP Some items (currently \fBarc\fR and\fB text\fR) have angles in their options; this command \fIdoes not\fR affect those options. .RE .VE "9.0, TIP164" .\" METHOD: scale .TP \fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR . Rescale the coordinates of all of the items given by \fItagOrId\fR in canvas coordinate space. \fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling operation and \fIxScale\fR and \fIyScale\fR identify the scale factors for x- and y-coordinates, respectively (a scale factor of 1.0 implies no change to that coordinate). For each of the points defining each item, the x-coordinate is adjusted to change the distance from \fIxOrigin\fR by a factor of \fIxScale\fR. Similarly, each y-coordinate is adjusted to change the distance from \fIyOrigin\fR by a factor of \fIyScale\fR. This command returns an empty string. .RS .PP Note that some items have only a single pair of coordinates (e.g., text, images and windows) and so scaling of them by this command can only move them around. .RE .\" METHOD: scan .TP \fIpathName \fBscan\fI option args\fR . This command is used to implement scanning on canvases. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx y\fR . Records \fIx\fR and \fIy\fR and the canvas's current view; used in conjunction with later \fBscan dragto\fR commands. Typically this command is associated with a mouse button press in the widget and \fIx\fR and \fIy\fR are the coordinates of the mouse. It returns an empty string. .TP \fIpathName \fBscan dragto \fIx y ?gain?\fR . This command computes the difference between its \fIx\fR and \fIy\fR arguments (which are typically mouse coordinates) and the \fIx\fR and \fIy\fR arguments to the last \fBscan mark\fR command for the widget. It then adjusts the view by \fIgain\fR times the difference in coordinates, where \fIgain\fR defaults to 10. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the canvas at high speed through its window. The return value is an empty string. .RE .\" METHOD: select .TP \fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR? . Manipulates the selection in one of several ways, depending on \fIoption\fR. The command may take any of the forms described below. In all of the descriptions below, \fItagOrId\fR must refer to an item that supports indexing and selection; if it refers to multiple items then the first of these that supports indexing and the selection is used. \fIIndex\fR gives a textual description of a position within \fItagOrId\fR, as described in \fBINDICES\fR above. .RS .TP \fIpathName \fBselect adjust \fItagOrId index\fR . Locate the end of the selection in \fItagOrId\fR nearest to the character given by \fIindex\fR, and adjust that end of the selection to be at \fIindex\fR (i.e. including but not going beyond \fIindex\fR). The other end of the selection is made the anchor point for future \fBselect to\fR commands. If the selection is not currently in \fItagOrId\fR then this command behaves the same as the \fBselect to\fR widget command. Returns an empty string. .TP \fIpathName \fBselect clear\fR . Clear the selection if it is in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. .TP \fIpathName \fBselect from \fItagOrId index\fR . Set the selection anchor point for the widget to be just before the character given by \fIindex\fR in the item given by \fItagOrId\fR. This command does not change the selection; it just sets the fixed end of the selection for future \fBselect to\fR commands. Returns an empty string. .TP \fIpathName \fBselect item\fR . Returns the id of the selected item, if the selection is in an item in this canvas. If the selection is not in this canvas then an empty string is returned. .TP \fIpathName \fBselect to \fItagOrId index\fR . Set the selection to consist of those characters of \fItagOrId\fR between the selection anchor point and \fIindex\fR. The new selection will include the character given by \fIindex\fR; it will include the character given by the anchor point only if \fIindex\fR is greater than or equal to the anchor point. The anchor point is determined by the most recent \fBselect adjust\fR or \fBselect from\fR command for this widget. If the selection anchor point for the widget is not currently in \fItagOrId\fR, then it is set to the same character given by \fIindex\fR. Returns an empty string. .RE .\" METHOD: type .TP \fIpathName \fBtype\fI tagOrId\fR . Returns the type of the item given by \fItagOrId\fR, such as \fBrectangle\fR or \fBtext\fR. If \fItagOrId\fR refers to more than one item, then the type of the first item in the display list is returned. If \fItagOrId\fR does not refer to any items at all then an empty string is returned. .\" METHOD: xview .TP \fIpathName \fBxview \fR?\fIargs\fR? . This command is used to query and change the horizontal position of the information displayed in the canvas's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR . Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the canvas's area (as defined by the \fB\-scrollregion\fR option) is off-screen to the left, the middle 40% is visible in the window, and 40% of the canvas is off-screen to the right. These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP \fIpathName \fBxview moveto\fI fraction\fR . Adjusts the view in the window so that \fIfraction\fR of the total width of the canvas is off-screen to the left. \fIFraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR . This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then it is converted to an integer, rounded away from 0. \fIWhat\fR must be either \fBpages\fR or \fBunits\fR or an abbreviation of one of these. If \fIwhat is \fBpages\fR then the view adjusts in units of nine-tenths the window's width. If \fInumber\fR is negative then information farther to the left becomes visible; if it is positive then information farther to the right becomes visible. If \fIwhat\fR is \fBunits\fR, the view adjusts left or right in units of the \fBxScrollIncrement\fR option, if it is greater than zero, or in units of one-tenth the window's width otherwise. .RE .\" METHOD: yview .TP \fIpathName \fByview ?\fIargs\fR? . This command is used to query and change the vertical position of the information displayed in the canvas's window. It can take any of the following forms: .RS .TP \fIpathName \fByview\fR . Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the vertical span that is visible in the window. For example, if the first element is .6 and the second element is 1.0, the lowest 40% of the canvas's area (as defined by the \fB\-scrollregion\fR option) is visible in the window. These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR option. .TP \fIpathName \fByview moveto\fI fraction\fR . Adjusts the view in the window so that \fIfraction\fR of the canvas's area is off-screen to the top. \fIFraction\fR is a fraction between 0 and 1. .TP \fIpathName \fByview scroll \fInumber what\fR . This command adjusts the view in the window up or down according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then it is converted to an integer, rounded away from 0. \fIWhat\fR must be either \fBpages\fR or \fBunits\fR. If \fIwhat\fR is \fBpages\fR then the view adjusts in units of nine-tenths the window's height. If \fInumber\fR is negative then higher information becomes visible; if it is positive then lower information becomes visible. If \fIwhat\fR is \fBunits\fR, the view adjusts up or down in units of the \fByScrollIncrement\fR option, if it is greater than zero, or in units of one-tenth the window's height otherwise. .RE .SH "OVERVIEW OF ITEM TYPES" .PP The sections below describe the various types of items supported by canvas widgets. Each item type is characterized by two things: first, the form of the \fBcreate\fR command used to create instances of the type; and second, a set of configuration options for items of that type, which may be used in the \fBcreate\fR and \fBitemconfigure\fR widget commands. Most items do not support indexing or selection or the commands related to them, such as \fBindex\fR and \fBinsert\fR. Where items do support these facilities, it is noted explicitly in the descriptions below. At present, text, line and polygon items provide this support. For lines and polygons the indexing facility is used to manipulate the coordinates of the item. .SS "COMMON ITEM OPTIONS" .PP Many items share a common set of options. These options are explained here, and then referred to be each widget type for brevity. .\" OPTION: -anchor .TP \fB\-anchor \fIanchorPos\fR . \fIAnchorPos\fR tells how to position the item relative to the positioning point for the item; it may have any of the forms accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR is \fBcenter\fR then the item is centered on the point; if \fIanchorPos\fR is \fBn\fR then the item will be drawn so that its top center point is at the positioning point. This option defaults to \fBcenter\fR. .\" OPTION: -dash .TP \fB\-dash \fIpattern\fR .\" OPTION: -activedash .TP \fB\-activedash \fIpattern\fR .\" OPTION: -disableddash .TP \fB\-disableddash \fIpattern\fR . These options specify dash patterns for the normal, active state, and disabled state of an item. \fIpattern\fR may have any of the forms accepted by \fBTk_GetDash\fR. If the dash options are omitted then the default is a solid outline. See \fBDASH PATTERNS\fR for more information. .\" OPTION: -dashoffset .TP \fB\-dashoffset \fIoffset\fR . The starting \fIoffset\fR in pixels into the pattern provided by the \fB\-dash\fR option. \fB\-dashoffset\fR is ignored if there is no \fB\-dash\fR pattern. The \fIoffset\fR may have any of the forms described in the \fBCOORDINATES\fR section above. .\" OPTION: -fill .TP \fB\-fill \fIcolor\fR .\" OPTION: -activefill .TP \fB\-activefill \fIcolor\fR .\" OPTION: -disabledfill .TP \fB\-disabledfill \fIcolor\fR . These options specify the color to be used to fill item's area. in its normal, active, and disabled states. The even-odd fill rule is used. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. For the line item, it specifies the color of the line drawn. For the text item, it specifies the foreground color of the text. If \fIcolor\fR is an empty string (the default for all canvas items except line and text), then the item will not be filled. .\" OPTION: -outline .TP \fB\-outline \fIcolor\fR .\" OPTION: -activeoutline .TP \fB\-activeoutline \fIcolor\fR .\" OPTION: -disabledoutline .TP \fB\-disabledoutline \fIcolor\fR . These options specify the color that should be used to draw the outline of the item in its normal, active and disabled states. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR is specified as an empty string then no outline is drawn for the item. .\" OPTION: -offset .TP \fB\-offset \fIoffset\fR . Specifies the offset of stipples. The offset value can be of the form \fBx,y\fR or \fIside\fR, where side can be \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. In the first case the origin is the origin of the toplevel of the current window. For the canvas itself and canvas objects the origin is the canvas origin, but putting \fB#\fR in front of the coordinate pair indicates using the toplevel origin instead. For canvas objects, the \fB\-offset\fR option is used for stippling as well. For the line and polygon canvas items you can also specify an index as argument, which connects the stipple origin to one of the coordinate points of the line/polygon. Note that stipple offsets are \fIonly supported on X11\fR; they are silently ignored on other platforms. .\" OPTION: -outlinestipple .TP \fB\-outlinestipple \fIbitmap\fR .\" OPTION: -activeoutlinestipple .TP \fB\-activeoutlinestipple \fIbitmap\fR .\" OPTION: -disabledoutlinestipple .TP \fB\-disabledoutlinestipple \fIbitmap\fR . These options specify stipple patterns that should be used to draw the outline of the item in its normal, active and disabled states. Indicates that the outline for the item should be drawn with a stipple pattern; \fIbitmap\fR specifies the stipple pattern to use, in any of the forms accepted by \fBTk_GetBitmap\fR. If the \fB\-outline\fR option has not been specified then this option has no effect. If \fIbitmap\fR is an empty string (the default), then the outline is drawn in a solid fashion. \fINote that stipples are not well supported on platforms that do not use X11 as their drawing API.\fR .\" OPTION: -outlineoffset .TP \fB\-outlineoffset \fIoffset\fR . Specifies the offset of the stipple pattern used for outlines, in the same way that the \fB\-outline\fR option controls fill stipples. (See the \fB\-outline\fR option for a description of the syntax of \fIoffset\fR.) .\" OPTION: -stipple .TP \fB\-stipple \fIbitmap\fR .\" OPTION: -activestipple .TP \fB\-activestipple \fIbitmap\fR .\" OPTION: -disabledstipple .TP \fB\-disabledstipple \fIbitmap\fR . These options specify stipple patterns that should be used to fill the item in its normal, active and disabled states. \fIbitmap\fR specifies the stipple pattern to use, in any of the forms accepted by \fBTk_GetBitmap\fR. If the \fB\-fill\fR option has not been specified then this option has no effect. If \fIbitmap\fR is an empty string (the default), then filling is done in a solid fashion. For the text item, it affects the actual text. \fINote that stipples are not well supported on platforms that do not use X11 as their drawing API.\fR .\" OPTION: -state .TP \fB\-state \fIstate\fR . This allows an item to override the canvas widget's global \fIstate\fR option. It takes the same values: \fInormal\fR, \fIdisabled\fR or \fIhidden\fR. .\" OPTION: -tags .TP \fB\-tags \fItagList\fR . Specifies a set of tags to apply to the item. \fITagList\fR consists of a list of tag names, which replace any existing tags for the item. \fITagList\fR may be an empty list. .\" OPTION: -width .TP \fB\-width \fIoutlineWidth\fR .\" OPTION: -activewidth .TP \fB\-activewidth \fIoutlineWidth\fR .\" OPTION: -disabledwidth .TP \fB\-disabledwidth \fIoutlineWidth\fR . These options specify the width of the outline to be drawn around the item's region, in its normal, active and disabled states. \fIoutlineWidth\fR may be in any of the forms described in the \fBCOORDINATES\fR section above. If the \fB\-outline\fR option has been specified as an empty string then this option has no effect. This option defaults to 1.0. For arcs, wide outlines will be drawn centered on the edges of the arc's region. .SH "STANDARD ITEM TYPES" .SS "ARC ITEMS" .PP Items of type \fBarc\fR appear on the display as arc-shaped regions. An arc is a section of an oval delimited by two angles (specified by either the \fB\-start\fR and \fB\-extent\fR options or the \fB\-height\fR option) and displayed in one of several ways (specified by the \fB\-style\fR option). Arcs are created with widget commands of the following form: .CS \fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR? \fIpathName \fBcreate arc \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give the coordinates of two diagonally opposite corners of a rectangular region enclosing the oval that defines the arc (except when \fB\-height\fR is specified - see below). . After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. An arc item becomes the current item when the mouse pointer is over any part that is painted or (when fully transparent) that would be painted if both the \fB\-fill\fR and \fB\-outline\fR options were non-empty. .PP The following standard options are supported by arcs: .DS .ta 3i \fB\-dash\fR \fB\-activedash\fR \fB\-disableddash\fR \fB\-dashoffset\fR \fB\-fill\fR \fB\-activefill\fR \fB\-disabledfill\fR \fB\-offset\fR \fB\-outline\fR \fB\-activeoutline\fR \fB\-disabledoutline\fR \fB\-outlineoffset\fR \fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR \fB\-disabledoutlinestipple\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE The following extra options are supported for arcs: .\" OPTION: -extent .TP \fB\-extent \fIdegrees\fR . Specifies the size of the angular range occupied by the arc. The arc's range extends for \fIdegrees\fR degrees counter-clockwise from the starting angle given by the \fB\-start\fR option. \fIDegrees\fR may be negative. If it is greater than 360 or less than \-360, then \fIdegrees\fR modulo 360 is used as the extent. .\" OPTION: -start .TP \fB\-start \fIdegrees\fR . Specifies the beginning of the angular range occupied by the arc. \fIDegrees\fR is given in units of degrees measured counter-clockwise from the 3-o'clock position; it may be either positive or negative. .\" OPTION: -height .TP \fB\-height \fIdistance\fR . Provides a shortcut for creating a circular arc segment by defining the distance of the mid-point of the arc from its chord. When this option is used the coordinates are interpreted as the start and end coordinates of the chord, and the options \fB\-start\fR and \fB\-extent\fR are ignored. The value of \fIdistance\fR has the following meaning: .RS .PP .RS \fIdistance\fR > 0 creates a clockwise arc .br \fIdistance\fR < 0 creates an counter-clockwise arc .br \fIdistance\fR = 0 creates an arc as if this option had not been specified .RE .PP If you want the arc to have a specific radius, \fIr\fR, use the formula: .PP .RS \fIdistance\fR = \fIr\fR \(+- sqrt(\fIr\fR**2 - (chordLength / 2)**2) .RE .PP choosing the minus sign for the minor arc and the plus sign for the major arc. .PP Note that \fBitemcget \-height\fR always returns 0 so that introspection code can be kept simple. .RE .\" OPTION: -style .TP \fB\-style \fItype\fR . Specifies how to draw the arc. If \fItype\fR is \fBpieslice\fR (the default) then the arc's region is defined by a section of the oval's perimeter plus two line segments, one between the center of the oval and each end of the perimeter section. If \fItype\fR is \fBchord\fR then the arc's region is defined by a section of the oval's perimeter plus a single line segment connecting the two end points of the perimeter section. If \fItype\fR is \fBarc\fR then the arc's region consists of a section of the perimeter alone. In this last case the \fB\-fill\fR option is ignored. .SS "BITMAP ITEMS" .PP Items of type \fBbitmap\fR appear on the display as images with two colors, foreground and background. Bitmaps are created with widget commands of the following form: .CS \fIpathName \fBcreate bitmap \fIx y \fR?\fIoption value ...\fR? \fIpathName \fBcreate bitmap \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two elements) specify the coordinates of a point used to position the bitmap on the display, as controlled by the \fB\-anchor\fR option. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. A bitmap item becomes the current item when the mouse pointer is over any part of its bounding box. .PP The following standard options are supported by bitmaps: .DS .ta 3i \fB\-anchor\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for bitmaps: .\" OPTION: -background .TP \fB\-background \fIcolor\fR .\" OPTION: -activebackground .TP \fB\-activebackground \fIcolor\fR .\" OPTION: -disabledbackground .TP \fB\-disabledbackground \fIcolor\fR . Specifies the color to use for each of the bitmap's .QW 0 valued pixels in its normal, active and disabled states. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. If this option is not specified, or if it is specified as an empty string, then nothing is displayed where the bitmap pixels are 0; this produces a transparent effect. .\" OPTION: -bitmap .TP \fB\-bitmap \fIbitmap\fR .\" OPTION: -activebitmap .TP \fB\-activebitmap \fIbitmap\fR .\" OPTION: -disabledbitmap .TP \fB\-disabledbitmap \fIbitmap\fR . These options specify the bitmaps to display in the item in its normal, active and disabled states. \fIBitmap\fR may have any of the forms accepted by \fBTk_GetBitmap\fR. .\" OPTION: -foreground .TP \fB\-foreground \fIcolor\fR .\" OPTION: -activeforeground .TP \fB\-activeforeground \fIcolor\fR .\" OPTION: -disabledforeground .TP \fB\-disabledforeground \fIcolor\fR . These options specify the color to use for each of the bitmap's .QW 1 valued pixels in its normal, active and disabled states. \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. .SS "IMAGE ITEMS" .PP Items of type \fBimage\fR are used to display images on a canvas. Images are created with widget commands of the following form: .CS \fIpathName \fBcreate image \fIx y \fR?\fIoption value ...\fR? \fIpathName \fBcreate image \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a point used to position the image on the display, as controlled by the \fB\-anchor\fR option. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. An image item becomes the current item when the mouse pointer is over any part of its bounding box. .PP The following standard options are supported by images: .DS .ta 3i \fB\-anchor\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for images: .\" OPTION: -image .TP \fB\-image \fIname\fR .\" OPTION: -activeimage .TP \fB\-activeimage \fIname\fR .\" OPTION: -disabledimage .TP \fB\-disabledimage \fIname\fR . Specifies the name of the images to display in the item in is normal, active and disabled states. This image must have been created previously with the \fBimage create\fR command. .SS "LINE ITEMS" .PP Items of type \fBline\fR appear on the display as one or more connected line segments or curves. Line items support coordinate indexing operations using the \fBdchars\fR, \fBindex\fR and \fBinsert\fR widget commands. Lines are created with widget commands of the following form: .CS \fIpathName \fBcreate line \fIx1 y1... xn yn \fR?\fIoption value ...\fR? \fIpathName \fBcreate line \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR through \fIyn\fR or \fIcoordList\fR give the coordinates for a series of two or more points that describe a series of connected line segments. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. A line item is the current item whenever the mouse pointer is over any segment of the line, whether drawn or not and whether or not the line is smoothed. .PP The following standard options are supported by lines: .DS .ta 3i \fB\-dash\fR \fB\-activedash\fR \fB\-disableddash\fR \fB\-dashoffset\fR \fB\-fill\fR \fB\-activefill\fR \fB\-disabledfill\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE The following extra options are supported for lines: .\" OPTION: -arrow .TP \fB\-arrow \fIwhere\fR . Indicates whether or not arrowheads are to be drawn at one or both ends of the line. \fIWhere\fR must have one of the values \fBnone\fR (for no arrowheads), \fBfirst\fR (for an arrowhead at the first point of the line), \fBlast\fR (for an arrowhead at the last point of the line), or \fBboth\fR (for arrowheads at both ends). This option defaults to \fBnone\fR. When requested to draw an arrowhead, Tk internally adjusts the corresponding line end point so that the rendered line ends at the neck of the arrowhead rather than at its tip so that the line doesn't extend past the edge of the arrowhead. This may trigger a \fBLeave\fR event if the mouse is hovering this line end. Conversely, when removing an arrowhead Tk adjusts the corresponding line point the other way round, which may trigger an \fBEnter\fR event. .\" OPTION: -arrowshape .TP \fB\-arrowshape \fIshape\fR . This option indicates how to draw arrowheads. The \fIshape\fR argument must be a list with three elements, each specifying a distance in any of the forms described in the \fBCOORDINATES\fR section above. The first element of the list gives the distance along the line from the neck of the arrowhead to its tip. The second element gives the distance along the line from the trailing points of the arrowhead to the tip, and the third element gives the distance from the outside edge of the line to the trailing points. If this option is not specified then Tk picks a .QW reasonable shape. .\" OPTION: -capstyle .TP \fB\-capstyle \fIstyle\fR . Specifies the ways in which caps are to be drawn at the endpoints of the line. \fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR (\fBbutt\fR, \fBprojecting\fR, or \fBround\fR). If this option is not specified then it defaults to \fBbutt\fR. Where arrowheads are drawn the cap style is ignored. .\" OPTION: -joinstyle .TP \fB\-joinstyle \fIstyle\fR . Specifies the ways in which joints are to be drawn at the vertices of the line. \fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR (\fBbevel\fR, \fBmiter\fR, or \fBround\fR). If this option is not specified then it defaults to \fBround\fR. If the line only contains two points then this option is irrelevant. .\" OPTION: -smooth .TP \fB\-smooth \fIsmoothMethod\fR . \fIsmoothMethod\fR must have one of the forms accepted by \fBTcl_GetBoolean\fR or a line smoothing method. Only \fBtrue\fR and \fBraw\fR are supported in the core (with \fBbezier\fR being an alias for \fBtrue\fR), but more can be added at runtime. If a boolean false value or empty string is given, no smoothing is applied. A boolean truth value assumes \fBtrue\fR smoothing. If the smoothing method is \fBtrue\fR, this indicates that the line should be drawn as a curve, rendered as a set of quadratic splines: one spline is drawn for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated within a curve by duplicating the end-points of the desired line segment. If the smoothing method is \fBraw\fR, this indicates that the line should also be drawn as a curve but where the list of coordinates is such that the first coordinate pair (and every third coordinate pair thereafter) is a knot point on a cubic Bezier curve, and the other coordinates are control points on the cubic Bezier curve. Straight line segments can be generated within a curve by making control points equal to their neighbouring knot points. If the last point is a control point and not a knot point, the point is repeated (one or two times) so that it also becomes a knot point. .\" OPTION: -splinesteps .TP \fB\-splinesteps \fInumber\fR . Specifies the degree of smoothness desired for curves: each spline will be approximated with \fInumber\fR line segments. This option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR. .SS "OVAL ITEMS" .PP Items of type \fBoval\fR appear as circular or oval regions on the display. Each oval may have an outline, a fill, or both. Ovals are created with widget commands of the following form: .CS \fIpathName \fBcreate oval \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR? \fIpathName \fBcreate oval \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give the coordinates of two diagonally opposite corners of a rectangular region enclosing the oval. The oval will include the top and left edges of the rectangle not the lower or right edges. If the region is square then the resulting oval is circular; otherwise it is elongated in shape. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. An oval item becomes the current item when the mouse pointer is over any part that is painted or (when fully transparent) that would be painted if both the \fB\-fill\fR and \fB\-outline\fR options were non-empty. .PP The following standard options are supported by ovals: .DS .ta 3i \fB\-dash\fR \fB\-activedash\fR \fB\-disableddash\fR \fB\-dashoffset\fR \fB\-fill\fR \fB\-activefill\fR \fB\-disabledfill\fR \fB\-offset\fR \fB\-outline\fR \fB\-activeoutline\fR \fB\-disabledoutline\fR \fB\-outlineoffset\fR \fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR \fB\-disabledoutlinestipple\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE There are no oval-specific options. .SS "POLYGON ITEMS" .PP Items of type \fBpolygon\fR appear as polygonal or curved filled regions on the display. Polygon items support coordinate indexing operations using the \fBdchars\fR, \fBindex\fR and \fBinsert\fR widget commands. Polygons are created with widget commands of the following form: .CS \fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value ...\fR? \fIpathName \fBcreate polygon \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR through \fIyn\fR or \fIcoordList\fR specify the coordinates for three or more points that define a polygon. The first point should not be repeated as the last to close the shape; Tk will automatically close the periphery between the first and last points. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. A polygon item is the current item whenever the mouse pointer is over any part of the polygon, whether drawn or not and whether or not the outline is smoothed. .PP The following standard options are supported by polygons: .DS .ta 3i \fB\-dash\fR \fB\-activedash\fR \fB\-disableddash\fR \fB\-dashoffset\fR \fB\-fill\fR \fB\-activefill\fR \fB\-disabledfill\fR \fB\-offset\fR \fB\-outline\fR \fB\-activeoutline\fR \fB\-disabledoutline\fR \fB\-outlineoffset\fR \fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR \fB\-disabledoutlinestipple\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE The following extra options are supported for polygons: .\" OPTION: -joinstyle .TP \fB\-joinstyle \fIstyle\fR . Specifies the ways in which joints are to be drawn at the vertices of the outline. \fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR (\fBbevel\fR, \fBmiter\fR, or \fBround\fR). If this option is not specified then it defaults to \fBround\fR. .\" OPTION: -smooth .TP \fB\-smooth \fIboolean\fR . \fIBoolean\fR must have one of the forms accepted by \fBTcl_GetBoolean\fR or a line smoothing method. Only \fBtrue\fR and \fBraw\fR are supported in the core (with \fBbezier\fR being an alias for \fBtrue\fR), but more can be added at runtime. If a boolean false value or empty string is given, no smoothing is applied. A boolean truth value assumes \fBtrue\fR smoothing. If the smoothing method is \fBtrue\fR, this indicates that the polygon should be drawn as a curve, rendered as a set of quadratic splines: one spline is drawn for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated within a curve by duplicating the end-points of the desired line segment. If the smoothing method is \fBraw\fR, this indicates that the polygon should also be drawn as a curve but where the list of coordinates is such that the first coordinate pair (and every third coordinate pair thereafter) is a knot point on a cubic Bezier curve, and the other coordinates are control points on the cubic Bezier curve. Straight line segments can be generated within a curve by making control points equal to their neighbouring knot points. If the last point is not the second point of a pair of control points, the point is repeated (one or two times) so that it also becomes the second point of a pair of control points (the associated knot point will be the first control point). .\" OPTION: -splinesteps .TP \fB\-splinesteps \fInumber\fR . Specifies the degree of smoothness desired for curves: each spline will be approximated with \fInumber\fR line segments. This option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR. .PP Polygon items are different from other items such as rectangles, ovals and arcs in that interior points are considered to be .QW inside a polygon (e.g. for purposes of the \fBfind closest\fR and \fBfind overlapping\fR widget commands) even if it is not filled. For most other item types, an interior point is considered to be inside the item only if the item is filled or if it has neither a fill nor an outline. If you would like an unfilled polygon whose interior points are not considered to be inside the polygon, use a line item instead. .SS "RECTANGLE ITEMS" .PP Items of type \fBrectangle\fR appear as rectangular regions on the display. Each rectangle may have an outline, a fill, or both. Rectangles are created with widget commands of the following form: .CS \fIpathName \fBcreate rectangle \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR? \fIpathName \fBcreate rectangle \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR (which must have four elements) give the coordinates of two diagonally opposite corners of the rectangle (the rectangle will include its upper and left edges but not its lower or right edges). After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. A rectangle item becomes the current item when the mouse pointer is over any part that is painted or (when fully transparent) that would be painted if both the \fB\-fill\fR and \fB\-outline\fR options were non-empty. .PP The following standard options are supported by rectangles: .DS .ta 3i \fB\-dash\fR \fB\-activedash\fR \fB\-disableddash\fR \fB\-dashoffset\fR \fB\-fill\fR \fB\-activefill\fR \fB\-disabledfill\fR \fB\-offset\fR \fB\-outline\fR \fB\-activeoutline\fR \fB\-disabledoutline\fR \fB\-outlineoffset\fR \fB\-outlinestipple\fR \fB\-activeoutlinestipple\fR \fB\-disabledoutlinestipple\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR \fB\-width\fR \fB\-activewidth\fR \fB\-disabledwidth\fR .DE There are no rectangle-specific options. .SS "TEXT ITEMS" .PP A text item displays a string of characters on the screen in one or more lines. Text items support indexing, editing and selection through the \fBdchars\fR widget command, the \fBfocus\fR widget command, the \fBicursor\fR widget command, the \fBindex\fR widget command, the \fBinsert\fR widget command, and the \fBselect\fR widget command. Text items are created with widget commands of the following form: .CS \fIpathName \fBcreate text \fIx y \fR?\fIoption value ...\fR? \fIpathName \fBcreate text \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two elements) specify the coordinates of a point used to position the text on the display (see the options below for more information on how text is displayed). After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. A text item becomes the current item when the mouse pointer is over any part of its bounding box. .PP The following standard options are supported by text items: .DS .ta 3i \fB\-anchor\fR \fB\-fill\fR \fB\-activefill\fR \fB\-disabledfill\fR \fB\-stipple\fR \fB\-activestipple\fR \fB\-disabledstipple\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for text items: .\" OPTION: -angle .TP \fB\-angle \fIrotationDegrees\fR . \fIRotationDegrees\fR tells how many degrees to rotate the text anticlockwise about the positioning point for the text; it may have any floating-point value from 0.0 to 360.0. For example, if \fIrotationDegrees\fR is \fB90\fR, then the text will be drawn vertically from bottom to top. This option defaults to \fB0.0\fR. .\" OPTION: -font .TP \fB\-font \fIfontName\fR . Specifies the font to use for the text item. \fIFontName\fR may be any string acceptable to \fBTk_GetFont\fR. If this option is not specified, it defaults to a system-dependent font. .\" OPTION: -justify .TP \fB\-justify \fIhow\fR . Specifies how to justify the text within its bounding region. \fIHow\fR must be one of the values \fBleft\fR, \fBright\fR, or \fBcenter\fR. This option will only matter if the text is displayed as multiple lines. If the option is omitted, it defaults to \fBleft\fR. .\" OPTION: -text .TP \fB\-text \fIstring\fR . \fIString\fR specifies the characters to be displayed in the text item. Newline characters cause line breaks. The characters in the item may also be changed with the \fBinsert\fR and \fBdelete\fR widget commands. This option defaults to an empty string. .\" OPTION: -underline .TP \fB\-underline \fInumber\fR . Specifies the integer index of a character within the text to be underlined. 0 corresponds to the first character of the text displayed, 1 to the next character, and so on. \-1 means that no underline should be drawn (if the whole text item is to be underlined, the appropriate font should be used instead). .\" OPTION: -width .TP \fB\-width \fIlineLength\fR . Specifies a maximum line length for the text, in any of the forms described in the \fBCOORDINATES\fR section above. If this option is zero (the default) the text is broken into lines only at newline characters. However, if this option is non-zero then any line that would be longer than \fIlineLength\fR is broken just before a space character to make the line shorter than \fIlineLength\fR; the space character is treated as if it were a newline character. .SS "WINDOW ITEMS" .PP Items of type \fBwindow\fR cause a particular window to be displayed at a given position on the canvas. Window items are created with widget commands of the following form: .CS \fIpathName \fBcreate window \fIx y \fR?\fIoption value ...\fR? \fIpathName \fBcreate window \fIcoordList\fR ?\fIoption value ...\fR? .CE The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two elements) specify the coordinates of a point used to position the window on the display, as controlled by the \fB\-anchor\fR option. After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. Theoretically, a window item becomes the current item when the mouse pointer is over any part of its bounding box, but in practice this typically does not happen because the mouse pointer ceases to be over the canvas at that point. .PP The following standard options are supported by window items: .DS .ta 3i \fB\-anchor\fR \fB\-state\fR \fB\-tags\fR .DE The following extra options are supported for window items: .\" OPTION: -height .TP \fB\-height \fIpixels\fR . Specifies the height to assign to the item's window. \fIPixels\fR may have any of the forms described in the \fBCOORDINATES\fR section above. If this option is not specified, or if it is specified as zero, then the window is given whatever height it requests internally. .\" OPTION: -width .TP \fB\-width \fIpixels\fR . Specifies the width to assign to the item's window. \fIPixels\fR may have any of the forms described in the \fBCOORDINATES\fR section above. If this option is not specified, or if it is specified as zero, then the window is given whatever width it requests internally. .\" OPTION: -window .TP \fB\-window \fIpathName\fR . Specifies the window to associate with this item. The window specified by \fIpathName\fR must either be a child of the canvas widget or a child of some ancestor of the canvas widget. \fIPathName\fR may not refer to a top-level window. .PP Note that, due to restrictions in the ways that windows are managed, it is not possible to draw other graphical items (such as lines and images) on top of window items. A window item always obscures any graphics that overlap it, regardless of their order in the display list. Also note that window items, unlike other canvas items, are not clipped for display by their containing canvas's border, and are instead clipped by the parent widget of the window specified by the \fB\-window\fR option; when the parent widget is the canvas, this means that the window item can overlap the canvas's border. .SH "APPLICATION-DEFINED ITEM TYPES" .PP It is possible for individual applications to define new item types for canvas widgets using C code. See the documentation for \fBTk_CreateItemType\fR. .SH BINDINGS .PP In the current implementation, new canvases are not given any default behavior: you will have to execute explicit Tcl commands to give the canvas its behavior. .SH CREDITS .PP Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's \fIezd\fR program. \fIEzd\fR provides structured graphics in a Scheme environment and preceded canvases by a year or two. Its simple mechanisms for placing and animating graphical objects inspired the functions of canvases. .SH "SEE ALSO" bind(n), font(n), image(n), scrollbar(n) .SH KEYWORDS canvas, widget '\" Local Variables: '\" mode: nroff '\" fill-column: 78 '\" End: tk9.0.3/doc/CanvPsY.30000644001000000100000000001132615105057705017226 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CanvasPs 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple \- utility procedures for generating Postscript for canvases .SH SYNOPSIS .nf \fB#include \fR .sp double \fBTk_CanvasPsY\fR(\fIcanvas, canvasY\fR) .sp int \fBTk_CanvasPsBitmap\fR(\fIinterp, canvas, bitmap, x, y, width, height\fR) .sp int \fBTk_CanvasPsColor\fR(\fIinterp, canvas, colorPtr\fR) .sp int \fBTk_CanvasPsFont\fR(\fIinterp, canvas, tkFont\fR) .sp \fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR) .sp int \fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR) .fi .SH ARGUMENTS .AS Tcl_Size "numPoints" .AP Tk_Canvas canvas in A token that identifies a canvas widget for which Postscript is being generated. .AP double canvasY in Y-coordinate in the space of the canvas. .AP Tcl_Interp *interp in/out A Tcl interpreter; Postscript is appended to its result, or the result may be replaced with an error message. .AP Pixmap bitmap in Bitmap to use for generating Postscript. .AP int x in X-coordinate within \fIbitmap\fR of left edge of region to output. .AP int y in Y-coordinate within \fIbitmap\fR of top edge of region to output. .AP "int" width in Width of region of bitmap to output, in pixels. .AP "int" height in Height of region of bitmap to output, in pixels. .AP XColor *colorPtr in Information about color value to set in Postscript. .AP Tk_Font tkFont in Font for which Postscript is to be generated. .AP double *coordPtr in Pointer to an array of coordinates for one or more points specified in canvas coordinates. The order of values in \fIcoordPtr\fR is x1, y1, x2, y2, x3, y3, and so on. .AP Tcl_Size numPoints in Number of points at \fIcoordPtr\fR. .BE .SH DESCRIPTION .PP These procedures are called by canvas type managers to carry out common functions related to generating Postscript. Most of the procedures take a \fIcanvas\fR argument, which refers to a canvas widget for which Postscript is being generated. .PP \fBTk_CanvasPsY\fR takes as argument a y-coordinate in the space of a canvas and returns the value that should be used for that point in the Postscript currently being generated for \fIcanvas\fR. Y coordinates require transformation because Postscript uses an origin at the lower-left corner whereas X uses an origin at the upper-left corner. Canvas x coordinates can be used directly in Postscript without transformation. .PP \fBTk_CanvasPsBitmap\fR generates Postscript to describe a region of a bitmap. The Postscript is generated in proper image data format for Postscript, i.e., as data between angle brackets, one bit per pixel. The Postscript is appended to the result of interpreter \fIinterp\fR and \fBTCL_OK\fR is returned unless an error occurs, in which case \fBTCL_ERROR\fR is returned and the interpreter result is overwritten with an error message. .PP \fBTk_CanvasPsColor\fR generates Postscript to set the current color to correspond to its \fIcolorPtr\fR argument, taking into account any color map specified in the \fBpostscript\fR command. It appends the Postscript to the interpreter \fIinterp\fR's result and returns \fBTCL_OK\fR unless an error occurs, in which case \fBTCL_ERROR\fR is returned and the interpreter's result is overwritten with an error message. .PP \fBTk_CanvasPsFont\fR generates Postscript that sets the current font to match \fItkFont\fR as closely as possible. \fBTk_CanvasPsFont\fR takes into account any font map specified in the \fBpostscript\fR command, and it does the best it can at mapping X fonts to Postscript fonts. It appends the Postscript to interpreter \fIinterp\fR's result and returns \fBTCL_OK\fR unless an error occurs, in which case \fBTCL_ERROR\fR is returned and the interpreter's result is overwritten with an error message. .PP \fBTk_CanvasPsPath\fR generates Postscript to set the current path to the set of points given by \fIcoordPtr\fR and \fInumPoints\fR. It appends the resulting Postscript to the result of interpreter \fIinterp\fR. .PP \fBTk_CanvasPsStipple\fR generates Postscript that will fill the current path in stippled fashion. It uses \fIbitmap\fR as the stipple pattern and the current Postscript color; ones in the stipple bitmap are drawn in the current color, and zeroes are not drawn at all. The Postscript is appended to interpreter \fIinterp\fR's result and \fBTCL_OK\fR is returned, unless an error occurs, in which case \fBTCL_ERROR\fR is returned and the interpreter's result is overwritten with an error message. .SH KEYWORDS bitmap, canvas, color, font, path, Postscript, stipple tk9.0.3/doc/CanvTkwin.30000644001000000100000000001452315105057705017611 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Window \fBTk_CanvasTkwin\fR(\fIcanvas\fR) .sp int \fBTk_CanvasGetCoord\fR(\fIinterp, canvas, string, doublePtr\fR) .sp \fBTk_CanvasDrawableCoords\fR(\fIcanvas, x, y, drawableXPtr, drawableYPtr\fR) .sp \fBTk_CanvasSetStippleOrigin\fR(\fIcanvas, gc\fR) .sp \fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR) .sp \fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR) .sp Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR; .sp Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR; .fi .SH ARGUMENTS .AS Tk_ItemType *drawableXPtr .AP Tk_Canvas canvas in A token that identifies a canvas widget. .AP Tcl_Interp *interp in/out Interpreter to use for error reporting. .AP "const char" *string in Textual description of a canvas coordinate. .AP double *doublePtr out Points to place to store a converted coordinate. .AP double x in An x coordinate in the space of the canvas. .AP double y in A y coordinate in the space of the canvas. .AP short *drawableXPtr out Pointer to a location in which to store an x coordinate in the space of the drawable currently being used to redisplay the canvas. .AP short *drawableYPtr out Pointer to a location in which to store a y coordinate in the space of the drawable currently being used to redisplay the canvas. .AP GC gc out Graphics context to modify. .AP short *screenXPtr out Points to a location in which to store the screen coordinate in the canvas window that corresponds to \fIx\fR. .AP short *screenYPtr out Points to a location in which to store the screen coordinate in the canvas window that corresponds to \fIy\fR. .AP int x1 in Left edge of the region that needs redisplay. Only pixels at or to the right of this coordinate need to be redisplayed. .AP int y1 in Top edge of the region that needs redisplay. Only pixels at or below this coordinate need to be redisplayed. .AP int x2 in Right edge of the region that needs redisplay. Only pixels to the left of this coordinate need to be redisplayed. .AP int y2 in Bottom edge of the region that needs redisplay. Only pixels above this coordinate need to be redisplayed. .BE .SH DESCRIPTION .PP These procedures are called by canvas type managers to perform various utility functions. .PP \fBTk_CanvasTkwin\fR returns the Tk_Window associated with a particular canvas. .PP \fBTk_CanvasGetCoord\fR translates a string specification of a coordinate (such as \fB2p\fR or \fB1.6c\fR) into a double-precision canvas coordinate. If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR stores the corresponding canvas coordinate at *\fIdoublePtr\fR and returns \fBTCL_OK\fR. Otherwise it stores an error message in the interpreter result and returns \fBTCL_ERROR\fR. .PP \fBTk_CanvasDrawableCoords\fR is called by type managers during redisplay to compute where to draw things. Given \fIx\fR and \fIy\fR coordinates in the space of the canvas, \fBTk_CanvasDrawableCoords\fR computes the corresponding pixel in the drawable that is currently being used for redisplay; it returns those coordinates in *\fIdrawableXPtr\fR and *\fIdrawableYPtr\fR. This procedure should not be invoked except during redisplay. .PP \fBTk_CanvasSetStippleOrigin\fR is also used during redisplay. It sets the stipple origin in \fIgc\fR so that stipples drawn with \fIgc\fR in the current offscreen pixmap will line up with stipples drawn with origin (0,0) in the canvas's actual window. \fBTk_CanvasSetStippleOrigin\fR is needed in order to guarantee that stipple patterns line up properly when the canvas is redisplayed in small pieces. Redisplays are carried out in double-buffered fashion where a piece of the canvas is redrawn in an offscreen pixmap and then copied back onto the screen. In this approach the stipple origins in graphics contexts need to be adjusted during each redisplay to compensate for the position of the off-screen pixmap relative to the window. If an item is being drawn with stipples, its type manager typically calls \fBTk_CanvasSetStippleOrigin\fR just before using \fIgc\fR to draw something; after it is finished drawing, the type manager calls \fBXSetTSOrigin\fR to restore the origin in \fIgc\fR back to (0,0) (the restore is needed because graphics contexts are shared, so they cannot be modified permanently). .PP \fBTk_CanvasWindowCoords\fR is similar to \fBTk_CanvasDrawableCoords\fR except that it returns coordinates in the canvas's window on the screen, instead of coordinates in an off-screen pixmap. .PP \fBTk_CanvasEventuallyRedraw\fR may be invoked by a type manager to inform Tk that a portion of a canvas needs to be redrawn. The \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR arguments specify the region that needs to be redrawn, in canvas coordinates. Type managers rarely need to invoke \fBTk_CanvasEventuallyRedraw\fR, since Tk can normally figure out when an item has changed and make the redisplay request on its behalf (this happens, for example whenever Tk calls a \fIconfigureProc\fR or \fIscaleProc\fR). The only time that a type manager needs to call \fBTk_CanvasEventuallyRedraw\fR is if an item has changed on its own without being invoked through one of the procedures in its Tk_ItemType; this could happen, for example, in an image item if the image is modified using image commands. .PP \fBTk_CanvasTagsParseProc\fR and \fBTk_CanvasTagsPrintProc\fR are procedures that handle the \fB\-tags\fR option for canvas items. The code of a canvas type manager will not call these procedures directly, but will use their addresses to create a \fBTk_CustomOption\fR structure for the \fB\-tags\fR option. The code typically looks like this: .PP .CS static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, Tk_CanvasTagsPrintProc, NULL }; static const Tk_ConfigSpec configSpecs[] = { ... {TK_CONFIG_CUSTOM, "-tags", NULL, NULL, NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, ... }; .CE .SH KEYWORDS canvas, focus, item type, redisplay, selection, type manager tk9.0.3/doc/CanvTxtInfo.30000644001000000100000000001026615105057705020110 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CanvasTextInfo 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CanvasTextInfo \- additional information for managing text items in canvases .SH SYNOPSIS .nf \fB#include \fR .sp Tk_CanvasTextInfo * \fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR) .fi .SH ARGUMENTS .AS Tk_Canvas canvas .AP Tk_Canvas canvas in A token that identifies a particular canvas widget. .BE .SH DESCRIPTION .PP Textual canvas items are somewhat more complicated to manage than other items, due to things like the selection and the input focus. \fBTk_CanvasGetTextInfo\fR may be invoked by a type manager to obtain additional information needed for items that display text. The return value from \fBTk_CanvasGetTextInfo\fR is a pointer to a structure that is shared between Tk and all the items that display text. The structure has the following form: .CS typedef struct { Tk_3DBorder \fIselBorder\fR; int \fIselBorderWidth\fR; XColor *\fIselFgColorPtr\fR; Tk_Item *\fIselItemPtr\fR; Tcl_Size \fIselectFirst\fR; Tcl_Size \fIselectLast\fR; Tk_Item *\fIanchorItemPtr\fR; Tcl_Size \fIselectAnchor\fR; Tk_3DBorder \fIinsertBorder\fR; int \fIinsertWidth\fR; int \fIinsertBorderWidth\fR; Tk_Item *\fIfocusItemPtr\fR; int \fIgotFocus\fR; int \fIcursorOn\fR; } \fBTk_CanvasTextInfo\fR; .CE The \fBselBorder\fR field identifies a Tk_3DBorder that should be used for drawing the background under selected text. \fIselBorderWidth\fR gives the width of the raised border around selected text, in pixels. \fIselFgColorPtr\fR points to an XColor that describes the foreground color to be used when drawing selected text. \fIselItemPtr\fR points to the item that is currently selected, or NULL if there is no item selected or if the canvas does not have the selection. \fIselectFirst\fR and \fIselectLast\fR give the indices of the first and last selected characters in \fIselItemPtr\fR, as returned by the \fIindexProc\fR for that item. \fIanchorItemPtr\fR points to the item that currently has the selection anchor; this is not necessarily the same as \fIselItemPtr\fR. \fIselectAnchor\fR is an index that identifies the anchor position within \fIanchorItemPtr\fR. \fIinsertBorder\fR contains a Tk_3DBorder to use when drawing the insertion cursor; \fIinsertWidth\fR gives the total width of the insertion cursor in pixels, and \fIinsertBorderWidth\fR gives the width of the raised border around the insertion cursor. \fIfocusItemPtr\fR identifies the item that currently has the input focus, or NULL if there is no such item. \fIgotFocus\fR is 1 if the canvas widget has the input focus and 0 otherwise. \fIcursorOn\fR is 1 if the insertion cursor should be drawn in \fIfocusItemPtr\fR and 0 if it should not be drawn; this field is toggled on and off by Tk to make the cursor blink. .PP The structure returned by \fBTk_CanvasGetTextInfo\fR is shared between Tk and the type managers; typically the type manager calls \fBTk_CanvasGetTextInfo\fR once when an item is created and then saves the pointer in the item's record. Tk will update information in the Tk_CanvasTextInfo; for example, a \fBconfigure\fR widget command might change the \fIselBorder\fR field, or a \fBselect\fR widget command might change the \fIselectFirst\fR field, or Tk might change \fIcursorOn\fR in order to make the insertion cursor flash on and off during successive redisplays. .PP Type managers should treat all of the fields of the Tk_CanvasTextInfo structure as read-only, except for \fIselItemPtr\fR, \fIselectFirst\fR, \fIselectLast\fR, and \fIselectAnchor\fR. Type managers may change \fIselectFirst\fR, \fIselectLast\fR, and \fIselectAnchor\fR to adjust for insertions and deletions in the item (but only if the item is the current owner of the selection or anchor, as determined by \fIselItemPtr\fR or \fIanchorItemPtr\fR). If all of the selected text in the item is deleted, the item should set \fIselItemPtr\fR to NULL to indicate that there is no longer a selection. .SH KEYWORDS canvas, focus, insertion cursor, selection, selection anchor, text tk9.0.3/doc/checkbutton.n0000644001000000100000000003114315105057705020306 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH checkbutton n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME checkbutton \- Create and manipulate 'checkbutton' boolean selection widgets .SH SYNOPSIS \fBcheckbutton\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-disabledforeground \-padx \-activeforeground \-font \-pady \-anchor \-foreground \-relief \-background \-highlightbackground \-takefocus \-bitmap \-highlightcolor \-text \-borderwidth \-highlightthickness \-textvariable \-compound \-image \-underline \-cursor \-justify \-wraplength .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command Specifies a Tcl command to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. The button's global variable (\fB\-variable\fR option) will be updated before the command is invoked. .OP \-height height Height Specifies a desired height for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); for text it is in lines of text. If this option is not specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it. .OP \-indicatoron indicatorOn IndicatorOn Specifies whether or not the indicator should be drawn. Must be a proper boolean value. If false, the \fB\-relief\fR option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise. .OP \-offrelief offRelief OffRelief Specifies the relief for the checkbutton when the indicator is not drawn and the checkbutton is off. The default value is .QW raised . By setting this option to .QW flat and setting \fB\-indicatoron\fR to false and \fB\-overrelief\fR to .QW raised , the effect is achieved of having a flat button that raises on mouse-over and which is depressed when activated. This is the behavior typically exhibited by the Bold, Italic, and Underline checkbuttons on the toolbar of a word-processor, for example. .OP \-offvalue offValue Value Specifies value to store in the button's associated variable whenever this button is deselected. Defaults to .QW 0 . .OP \-onvalue onValue Value Specifies value to store in the button's associated variable whenever this button is selected. Defaults to .QW 1 . .OP \-overrelief overRelief OverRelief Specifies an alternative relief for the checkbutton, to be used when the mouse cursor is over the widget. This option can be used to make toolbar buttons, by configuring \fB\-relief flat \-overrelief raised\fR. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the checkbutton. The empty string is the default value. .OP \-selectcolor selectColor Background Specifies a background color to use when the button is selected. If \fBindicatorOn\fR is true then the color is used as the background for the indicator regardless of the select state. If \fBindicatorOn\fR is false, this color is used as the background for the entire widget, in place of \fBbackground\fR or \fBactiveBackground\fR, whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected. .OP \-selectimage selectImage SelectImage Specifies an image to display (in place of the \fB\-image\fR option) when the checkbutton is selected. This option is ignored unless the \fB\-image\fR option has been specified. .OP \-state state State Specifies one of three states for the checkbutton: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the checkbutton is displayed using the \fB\-foreground\fR and \fB\-background\fR options. The active state is typically used when the pointer is over the checkbutton. In active state the checkbutton is displayed using the \fB\-activeforeground\fR and \fB\-activebackground\fR options. Disabled state means that the checkbutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the \fB\-disabledforeground\fR and \fB\-background\fR options determine how the checkbutton is displayed. .OP \-tristateimage tristateImage TristateImage Specifies an image to display (in place of the \fB\-image\fR option) when the checkbutton is in tri-state mode. This option is ignored unless the \fB\-image\fR option has been specified. .OP \-tristatevalue tristateValue Value Specifies the value that causes the checkbutton to display the multi-value selection, also known as the tri-state mode. Defaults to .QW "" . .OP \-variable variable Variable Specifies the name of a global variable to set to indicate whether or not this button is selected. Defaults to the name of the button within its parent (i.e. the last element of the button window's path name). .OP \-width width Width Specifies a desired width for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); for text it is in characters. If this option is not specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it. .BE .SH DESCRIPTION .PP The \fBcheckbutton\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a checkbutton widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the checkbutton such as its colors, font, text, and initial relief. The \fBcheckbutton\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A checkbutton is a widget that displays a textual string, bitmap or image and a square called an \fIindicator\fR. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the \fB\-wraplength\fR option) and one of the characters may optionally be underlined using the \fB\-underline\fR option. A checkbutton has all of the behavior of a simple button, including the following: it can display itself in either of three different ways, according to the \fB\-state\fR option; it can be made to appear raised, sunken, or flat; it can be made to flash; and it invokes a Tcl command whenever mouse button 1 is clicked over the checkbutton. .PP In addition, checkbuttons can be \fIselected\fR. If a checkbutton is selected then the indicator is normally drawn with a selected appearance, and a Tcl variable associated with the checkbutton is set to a particular value (normally 1). The indicator is drawn with a check mark inside. If the checkbutton is not selected, then the indicator is drawn with a deselected appearance, and the associated variable is set to a different value (typically 0). The indicator is drawn without a check mark inside. In the special case where the variable (if specified) has a value that matches the tristatevalue, the indicator is drawn with a tri-state appearance and is in the tri-state mode indicating mixed or multiple values. (This is used when the check box represents the state of multiple items.) The indicator is drawn in a platform dependent manner. Under Unix and Windows, the background interior of the box is .QW grayed . Under Mac, the indicator is drawn with a dash mark inside. By default, the name of the variable associated with a checkbutton is the same as the \fIname\fR used to create the checkbutton. The variable name, and the .QW on , .QW off and .QW tristate values stored in it, may be modified with options on the command line or in the option database. Configuration options may also be used to modify the way the indicator is displayed (or whether it is displayed at all). By default a checkbutton is configured to select and deselect itself on alternate button clicks. In addition, each checkbutton monitors its associated variable and automatically selects and deselects itself when the variables value changes to and from the button's .QW on , .QW off and .QW tristate values. .SH "WIDGET COMMAND" .PP The \fBcheckbutton\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for checkbutton widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR command. .\" METHOD: deselect .TP \fIpathName \fBdeselect\fR . Deselects the checkbutton and sets the associated variable to its .QW off value. .\" METHOD: flash .TP \fIpathName \fBflash\fR . Flashes the checkbutton. This is accomplished by redisplaying the checkbutton several times, alternating between active and normal colors. At the end of the flash the checkbutton is left in the same normal/active state as when the command was invoked. This command is ignored if the checkbutton's state is \fBdisabled\fR. .\" METHOD: invoke .TP \fIpathName \fBinvoke\fR . Does just what would have happened if the user invoked the checkbutton with the mouse: toggle the selection state of the button and invoke the Tcl command associated with the checkbutton, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the checkbutton. This command is ignored if the checkbutton's state is \fBdisabled\fR. .\" METHOD: select .TP \fIpathName \fBselect\fR . Selects the checkbutton and sets the associated variable to its .QW on value. .\" METHOD: toggle .TP \fIpathName \fBtoggle\fR . Toggles the selection state of the button, redisplaying it and modifying its associated variable to reflect the new state. .SH BINDINGS .PP Tk automatically creates class bindings for checkbuttons that give them the following default behavior: .IP [1] On Unix systems, a checkbutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the checkbutton. On Mac and Windows systems, when mouse button 1 is pressed over a checkbutton, the button activates whenever the mouse pointer is inside the button, and deactivates whenever the mouse pointer leaves the button. .IP [2] When mouse button 1 is pressed over a checkbutton, it is invoked (its selection state toggles and the command associated with the button is invoked, if there is one). .IP [3] When a checkbutton has the input focus, the space key causes the checkbutton to be invoked. Under Windows, there are additional key bindings; plus (\fB+\fR) and equal (\fB=\fR) select the button, and minus (\fB\-\fR) deselects the button. .PP If the checkbutton's state is \fBdisabled\fR then none of the above actions occur: the checkbutton is completely non-responsive. .PP The behavior of checkbuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH EXAMPLE .PP This example shows a group of uncoupled checkbuttons. .PP .CS labelframe .lbl -text "Steps:" \fBcheckbutton\fR .c1 -text Lights -variable lights \fBcheckbutton\fR .c2 -text Cameras -variable cameras \fBcheckbutton\fR .c3 -text Action! -variable action pack .c1 .c2 .c3 -in .lbl pack .lbl .CE .SH "SEE ALSO" button(n), options(n), radiobutton(n), ttk::checkbutton(n) .SH KEYWORDS checkbutton, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/chooseColor.n0000644001000000100000000000312115105057705020247 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk_chooseColor n 4.2 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_chooseColor \- pops up a dialog box for the user to select a color. .SH SYNOPSIS \fBtk_chooseColor \fR?\fIoption value ...\fR? .BE .SH DESCRIPTION .PP The procedure \fBtk_chooseColor\fR pops up a dialog box for the user to select a color. The following \fIoption\-value\fR pairs are possible as command line arguments: .\" OPTION: -initialcolor .TP \fB\-initialcolor\fI color\fR . Specifies the color to display in the color dialog when it pops up. \fIcolor\fR must be in a form acceptable to the \fBTk_GetColor\fR function. .\" OPTION: -parent .TP \fB\-parent\fI window\fR . Makes \fIwindow\fR the logical parent of the color dialog. The color dialog is displayed on top of its parent window. .\" OPTION: -title .TP \fB\-title\fI titleString\fR . Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed. .LP If the user selects a color, \fBtk_chooseColor\fR will return the name of the color in a form acceptable to \fBTk_GetColor\fR. If the user cancels the operation, both commands will return the empty string. .SH EXAMPLE .PP .CS button .b -bg [tk_chooseColor -initialcolor gray -title "Choose color"] .CE .SH KEYWORDS color, color selection, dialog '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/chooseDirectory.n0000644001000000100000000000520415076161055021142 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH tk_chooseDirectory n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_chooseDirectory \- pops up a dialog box for the user to select a directory. .SH SYNOPSIS \fBtk_chooseDirectory \fR?\fIoption value ...\fR? .BE .SH DESCRIPTION .PP The procedure \fBtk_chooseDirectory\fR pops up a dialog box for the user to select a directory. The following \fIoption\-value\fR pairs are possible as command line arguments: .\" OPTION: -command .TP \fB\-command\fI string\fR . Specifies the prefix of a Tcl command to invoke when the user closes the dialog after having selected an item. This callback is not called if the user cancelled the dialog. The actual command consists of \fIstring\fR followed by a space and the value selected by the user in the dialog. This is only available on macOS. .\" OPTION: -initialdir .TP \fB\-initialdir\fI dirname\fR . Specifies that the directories in \fIdirectory\fR should be displayed when the dialog pops up. If this parameter is not specified, the initial directory defaults to the current working directory on non-Windows systems and on Windows systems prior to Vista. On Vista and later systems, the initial directory defaults to the last user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. .\" OPTION: -message .TP \fB\-message\fI string\fR . Specifies a message to include in the client area of the dialog. This is only available on macOS. .\" OPTION: -mustexist .TP \fB\-mustexist\fI boolean\fR . Specifies whether the user may specify non-existent directories. If this parameter is true, then the user may only select directories that already exist. The default value is \fIfalse\fR. .\" OPTION: -parent .TP \fB\-parent\fI window\fR . Makes \fIwindow\fR the logical parent of the dialog. The dialog is displayed on top of its parent window. On macOS, this turns the file dialog into a sheet attached to the parent window. .\" OPTION: -title .TP \fB\-title\fI titleString\fR . Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed. .SH EXAMPLE .PP .CS set dir [\fBtk_chooseDirectory\fR \e -initialdir ~ -title "Choose a directory"] if {$dir eq ""} { label .l -text "No directory selected" } else { label .l -text "Selected $dir" } .CE .SH "SEE ALSO" tk_getOpenFile(n), tk_getSaveFile(n) .SH KEYWORDS directory, selection, dialog, platform-specific '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/Clipboard.30000644001000000100000000000573615105057705017612 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_ClipboardClear 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_ClipboardClear, Tk_ClipboardAppend \- Manage the clipboard .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR) .sp int \fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR) .fi .SH ARGUMENTS .AS Tk_ClipboardClear tkwin .AP Tcl_Interp *interp in Interpreter to use for reporting errors. .AP Tk_Window tkwin in Window that determines which display's clipboard to manipulate. .AP Atom target in Conversion type for this clipboard item; has same meaning as \fItarget\fR argument to \fBTk_CreateSelHandler\fR. .AP Atom format in Representation to use when data is retrieved; has same meaning as \fIformat\fR argument to \fBTk_CreateSelHandler\fR. .AP "const char" *buffer in Null terminated string containing the data to be appended to the clipboard. .BE .SH DESCRIPTION .PP These two procedures manage the clipboard for Tk. The clipboard is typically managed by calling \fBTk_ClipboardClear\fR once, then calling \fBTk_ClipboardAppend\fR to add data for any number of targets. .PP \fBTk_ClipboardClear\fR claims the CLIPBOARD selection and frees any data items previously stored on the clipboard in this application. It normally returns \fBTCL_OK\fR, but if an error occurs it returns \fBTCL_ERROR\fR and leaves an error message in interpreter \fIinterp\fR's result. \fBTk_ClipboardClear\fR must be called before a sequence of \fBTk_ClipboardAppend\fR calls can be issued. .PP \fBTk_ClipboardAppend\fR appends a buffer of data to the clipboard. The first buffer for a given \fItarget\fR determines the \fIformat\fR for that \fItarget\fR. Any successive appends for that \fItarget\fR must have the same format or an error will be returned. \fBTk_ClipboardAppend\fR returns \fBTCL_OK\fR if the buffer is successfully copied onto the clipboard. If the clipboard is not currently owned by the application, either because \fBTk_ClipboardClear\fR has not been called or because ownership of the clipboard has changed since the last call to \fBTk_ClipboardClear\fR, \fBTk_ClipboardAppend\fR returns \fBTCL_ERROR\fR and leaves an error message in the result of interpreter \fIinterp\fR. .PP In order to guarantee atomicity, no event handling should occur between \fBTk_ClipboardClear\fR and the following \fBTk_ClipboardAppend\fR calls (otherwise someone could retrieve a partially completed clipboard or claim ownership away from this application). .PP \fBTk_ClipboardClear\fR may invoke callbacks, including arbitrary Tcl scripts, as a result of losing the CLIPBOARD selection, so any calling function should take care to be re-entrant at the point \fBTk_ClipboardClear\fR is invoked. .SH KEYWORDS append, clipboard, clear, format, type tk9.0.3/doc/clipboard.n0000644001000000100000000001321315105057705017732 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH clipboard n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME clipboard \- Manipulate Tk clipboard .SH SYNOPSIS \fBclipboard \fIoption\fR ?\fIarg ...\fR? .BE .SH DESCRIPTION .PP This command provides a Tcl interface to the Tk clipboard, which stores data for later retrieval using the selection mechanism (via the \fB\-selection CLIPBOARD\fR option). In order to copy data into the clipboard, \fBclipboard clear\fR must be called, followed by a sequence of one or more calls to \fBclipboard append\fR. To ensure that the clipboard is updated atomically, all appends should be completed before returning to the event loop. .PP The first argument to \fBclipboard\fR determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: .\" METHOD: append .TP \fBclipboard append\fR ?\fB\-displayof\fI window\fR? ?\fB\-format\fI format\fR? ?\fB\-type\fI type\fR? ?\fB\-\|\-\fR? \fIdata\fR . Appends \fIdata\fR to the clipboard on \fIwindow\fR's display in the form given by \fItype\fR with the representation given by \fIformat\fR and claims ownership of the clipboard on \fIwindow\fR's display. .RS .PP \fIType\fR specifies the form in which the selection is to be returned (the desired .QW target for conversion, in ICCCM terminology), and should be an atom name such as \fBSTRING\fR or \fBFILE_NAME\fR; see the Inter-Client Communication Conventions Manual for complete details. \fIType\fR defaults to \fBSTRING\fR. .PP The \fIformat\fR argument specifies the representation that should be used to transmit the selection to the requester (the second column of Table 2 of the ICCCM), and defaults to \fBSTRING\fR. If \fIformat\fR is \fBSTRING\fR, the selection is transmitted as 8-bit ASCII characters. If \fIformat\fR is \fBATOM\fR, then the \fIdata\fR is divided into fields separated by white space; each field is converted to its atom value, and the 32-bit atom value is transmitted instead of the atom name. For any other \fIformat\fR, \fIdata\fR is divided into fields separated by white space and each field is converted to a 32-bit integer; an array of integers is transmitted to the selection requester. Note that strings passed to \fBclipboard append\fR are concatenated before conversion, so the caller must take care to ensure appropriate spacing across string boundaries. All items appended to the clipboard with the same \fItype\fR must have the same \fIformat\fR. .PP The \fIformat\fR argument is needed only for compatibility with clipboard requesters that do not use Tk. If the Tk toolkit is being used to retrieve the \fBCLIPBOARD\fR selection then the value is converted back to a string at the requesting end, so \fIformat\fR is irrelevant. .PP A \fB\-\|\-\fR argument may be specified to mark the end of options: the next argument will always be used as \fIdata\fR. This feature may be convenient if, for example, \fIdata\fR starts with a \fB\-\fR. .RE .\" METHOD: clear .TP \fBclipboard clear\fR ?\fB\-displayof\fI window\fR? . Claims ownership of the clipboard on \fIwindow\fR's display and removes any previous contents. \fIWindow\fR defaults to .QW . . Returns an empty string. .\" METHOD: get .TP \fBclipboard get\fR ?\fB\-displayof\fI window\fR? ?\fB\-type\fI type\fR? . Retrieve data from the clipboard on \fIwindow\fR's display. \fIWindow\fR defaults to .QW . . \fIType\fR specifies the form in which the data is to be returned and should be an atom name such as \fBSTRING\fR or \fBFILE_NAME\fR. \fIType\fR defaults to \fBSTRING\fR. This command is equivalent to .QW "\fBselection get\fR \fB\-selection CLIPBOARD\fR" . .RS .PP Note that on modern X11 systems, the most useful type to retrieve for transferred strings is not \fBSTRING\fR, but rather \fBUTF8_STRING\fR. .RE .SH EXAMPLES .PP Get the current contents of the clipboard. .CS if {[catch {\fBclipboard get\fR} contents]} { # There were no clipboard contents at all } .CE .PP Set the clipboard to contain a fixed string. .CS \fBclipboard clear\fR \fBclipboard append\fR "some fixed string" .CE .PP You can put custom data into the clipboard by using a custom \fB\-type\fR option. This is not necessarily portable, but can be very useful. The method of passing Tcl scripts this way is effective, but should be mixed with safe interpreters in production code. .CS # This is a very simple canvas serializer; # it produces a script that recreates the item(s) when executed proc getItemConfig {canvas tag} { set script {} foreach item [$canvas find withtag $tag] { append script {$canvas create } [$canvas type $item] append script { } [$canvas coords $item] { } foreach config [$canvas itemconf $item] { lassign $config name - - - value append script [list $name $value] { } } append script \en } return [string trim $script] } # Set up a binding on a canvas to cut and paste an item set c [canvas .c] pack $c $c create text 150 30 -text "cut and paste me" bind $c <> { \fBclipboard clear\fR \fBclipboard append -type\fR TkCanvasItem \e [getItemConfig %W current] # Delete because this is cut, not copy. %W delete current } bind $c <> { catch { set canvas %W eval [\fBclipboard get -type\fR TkCanvasItem] } } .CE .SH "SEE ALSO" interp(n), selection(n) .SH KEYWORDS clear, format, clipboard, append, selection, type '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ClrSelect.30000644001000000100000000000223215105057705017557 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_ClearSelection 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_ClearSelection \- Deselect a selection .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_ClearSelection\fR(\fItkwin, selection\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in The selection will be cleared from the display containing this window. .AP Atom selection in The name of selection to be cleared. .BE .SH DESCRIPTION .PP \fBTk_ClearSelection\fR cancels the selection specified by the atom \fIselection\fR for the display containing \fItkwin\fR. The selection need not be in \fItkwin\fR itself or even in \fItkwin\fR's application. If there is a window anywhere on \fItkwin\fR's display that owns \fIselection\fR, the window will be notified and the selection will be cleared. If there is no owner for \fIselection\fR on the display, then the procedure has no effect. .SH KEYWORDS clear, selection tk9.0.3/doc/colors.n0000644001000000100000000005227715105057705017311 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" Copyright (c) 2003 ActiveState Corporation. '\" Copyright (c) 2006-2007 Daniel A. Steffen '\" Copyright (c) 2008 Donal K. Fellows '\" .TH colors n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS .\" Note: do not modify the .SH NAME line immediately below! .SH NAME colors \- symbolic color names recognized by Tk .BE .SH DESCRIPTION .PP Tk recognizes many symbolic color names (e.g., \fBred\fR) when specifying colors. The symbolic names recognized by Tk and their 8-bit-per-channel RGB values are: .DS .ta 7.2cR 9.5cR 11cR \fBName\fR \fBRed\fR \fBGreen\fR \fBBlue\fR alice blue 240 248 255 AliceBlue 240 248 255 antique white 250 235 215 AntiqueWhite 250 235 215 AntiqueWhite1 255 239 219 AntiqueWhite2 238 223 204 AntiqueWhite3 205 192 176 AntiqueWhite4 139 131 120 aqua 0 255 255 aquamarine 127 255 212 aquamarine1 127 255 212 aquamarine2 118 238 198 aquamarine3 102 205 170 aquamarine4 69 139 116 azure 240 255 255 azure1 240 255 255 azure2 224 238 238 azure3 193 205 205 azure4 131 139 139 beige 245 245 220 bisque 255 228 196 bisque1 255 228 196 bisque2 238 213 183 bisque3 205 183 158 bisque4 139 125 107 black 0 0 0 blanched almond 255 235 205 BlanchedAlmond 255 235 205 blue 0 0 255 blue violet 138 43 226 blue1 0 0 255 blue2 0 0 238 blue3 0 0 205 blue4 0 0 139 BlueViolet 138 43 226 brown 165 42 42 brown1 255 64 64 brown2 238 59 59 brown3 205 51 51 brown4 139 35 35 burlywood 222 184 135 burlywood1 255 211 155 burlywood2 238 197 145 burlywood3 205 170 125 burlywood4 139 115 85 cadet blue 95 158 160 CadetBlue 95 158 160 CadetBlue1 152 245 255 CadetBlue2 142 229 238 CadetBlue3 122 197 205 CadetBlue4 83 134 139 chartreuse 127 255 0 chartreuse1 127 255 0 chartreuse2 118 238 0 chartreuse3 102 205 0 chartreuse4 69 139 0 chocolate 210 105 30 chocolate1 255 127 36 chocolate2 238 118 33 chocolate3 205 102 29 chocolate4 139 69 19 coral 255 127 80 coral1 255 114 86 coral2 238 106 80 coral3 205 91 69 coral4 139 62 47 cornflower blue 100 149 237 CornflowerBlue 100 149 237 cornsilk 255 248 220 cornsilk1 255 248 220 cornsilk2 238 232 205 cornsilk3 205 200 177 cornsilk4 139 136 120 crimson 220 20 60 cyan 0 255 255 cyan1 0 255 255 cyan2 0 238 238 cyan3 0 205 205 cyan4 0 139 139 dark blue 0 0 139 dark cyan 0 139 139 dark goldenrod 184 134 11 dark gray 169 169 169 dark green 0 100 0 dark grey 169 169 169 dark khaki 189 183 107 dark magenta 139 0 139 dark olive green 85 107 47 dark orange 255 140 0 dark orchid 153 50 204 dark red 139 0 0 dark salmon 233 150 122 dark sea green 143 188 143 dark slate blue 72 61 139 dark slate gray 47 79 79 dark slate grey 47 79 79 dark turquoise 0 206 209 dark violet 148 0 211 DarkBlue 0 0 139 DarkCyan 0 139 139 DarkGoldenrod 184 134 11 DarkGoldenrod1 255 185 15 DarkGoldenrod2 238 173 14 DarkGoldenrod3 205 149 12 DarkGoldenrod4 139 101 8 DarkGray 169 169 169 DarkGreen 0 100 0 DarkGrey 169 169 169 DarkKhaki 189 183 107 DarkMagenta 139 0 139 DarkOliveGreen 85 107 47 DarkOliveGreen1 202 255 112 DarkOliveGreen2 188 238 104 DarkOliveGreen3 162 205 90 DarkOliveGreen4 110 139 61 DarkOrange 255 140 0 DarkOrange1 255 127 0 DarkOrange2 238 118 0 DarkOrange3 205 102 0 DarkOrange4 139 69 0 DarkOrchid 153 50 204 DarkOrchid1 191 62 255 DarkOrchid2 178 58 238 DarkOrchid3 154 50 205 DarkOrchid4 104 34 139 DarkRed 139 0 0 DarkSalmon 233 150 122 DarkSeaGreen 143 188 143 DarkSeaGreen1 193 255 193 DarkSeaGreen2 180 238 180 DarkSeaGreen3 155 205 155 DarkSeaGreen4 105 139 105 DarkSlateBlue 72 61 139 DarkSlateGray 47 79 79 DarkSlateGray1 151 255 255 DarkSlateGray2 141 238 238 DarkSlateGray3 121 205 205 DarkSlateGray4 82 139 139 DarkSlateGrey 47 79 79 DarkTurquoise 0 206 209 DarkViolet 148 0 211 deep pink 255 20 147 deep sky blue 0 191 255 DeepPink 255 20 147 DeepPink1 255 20 147 DeepPink2 238 18 137 DeepPink3 205 16 118 DeepPink4 139 10 80 DeepSkyBlue 0 191 255 DeepSkyBlue1 0 191 255 DeepSkyBlue2 0 178 238 DeepSkyBlue3 0 154 205 DeepSkyBlue4 0 104 139 dim gray 105 105 105 dim grey 105 105 105 DimGray 105 105 105 DimGrey 105 105 105 dodger blue 30 144 255 DodgerBlue 30 144 255 DodgerBlue1 30 144 255 DodgerBlue2 28 134 238 DodgerBlue3 24 116 205 DodgerBlue4 16 78 139 firebrick 178 34 34 firebrick1 255 48 48 firebrick2 238 44 44 firebrick3 205 38 38 firebrick4 139 26 26 floral white 255 250 240 FloralWhite 255 250 240 forest green 34 139 34 ForestGreen 34 139 34 fuchsia 255 0 255 gainsboro 220 220 220 ghost white 248 248 255 GhostWhite 248 248 255 gold 255 215 0 gold1 255 215 0 gold2 238 201 0 gold3 205 173 0 gold4 139 117 0 goldenrod 218 165 32 goldenrod1 255 193 37 goldenrod2 238 180 34 goldenrod3 205 155 29 goldenrod4 139 105 20 gray 128 128 128 gray0 0 0 0 gray1 3 3 3 gray2 5 5 5 gray3 8 8 8 gray4 10 10 10 gray5 13 13 13 gray6 15 15 15 gray7 18 18 18 gray8 20 20 20 gray9 23 23 23 gray10 26 26 26 gray11 28 28 28 gray12 31 31 31 gray13 33 33 33 gray14 36 36 36 gray15 38 38 38 gray16 41 41 41 gray17 43 43 43 gray18 46 46 46 gray19 48 48 48 gray20 51 51 51 gray21 54 54 54 gray22 56 56 56 gray23 59 59 59 gray24 61 61 61 gray25 64 64 64 gray26 66 66 66 gray27 69 69 69 gray28 71 71 71 gray29 74 74 74 gray30 77 77 77 gray31 79 79 79 gray32 82 82 82 gray33 84 84 84 gray34 87 87 87 gray35 89 89 89 gray36 92 92 92 gray37 94 94 94 gray38 97 97 97 gray39 99 99 99 gray40 102 102 102 gray41 105 105 105 gray42 107 107 107 gray43 110 110 110 gray44 112 112 112 gray45 115 115 115 gray46 117 117 117 gray47 120 120 120 gray48 122 122 122 gray49 125 125 125 gray50 127 127 127 gray51 130 130 130 gray52 133 133 133 gray53 135 135 135 gray54 138 138 138 gray55 140 140 140 gray56 143 143 143 gray57 145 145 145 gray58 148 148 148 gray59 150 150 150 gray60 153 153 153 gray61 156 156 156 gray62 158 158 158 gray63 161 161 161 gray64 163 163 163 gray65 166 166 166 gray66 168 168 168 gray67 171 171 171 gray68 173 173 173 gray69 176 176 176 gray70 179 179 179 gray71 181 181 181 gray72 184 184 184 gray73 186 186 186 gray74 189 189 189 gray75 191 191 191 gray76 194 194 194 gray77 196 196 196 gray78 199 199 199 gray79 201 201 201 gray80 204 204 204 gray81 207 207 207 gray82 209 209 209 gray83 212 212 212 gray84 214 214 214 gray85 217 217 217 gray86 219 219 219 gray87 222 222 222 gray88 224 224 224 gray89 227 227 227 gray90 229 229 229 gray91 232 232 232 gray92 235 235 235 gray93 237 237 237 gray94 240 240 240 gray95 242 242 242 gray96 245 245 245 gray97 247 247 247 gray98 250 250 250 gray99 252 252 252 gray100 255 255 255 green 0 128 0 green yellow 173 255 47 green1 0 255 0 green2 0 238 0 green3 0 205 0 green4 0 139 0 GreenYellow 173 255 47 grey 128 128 128 grey0 0 0 0 grey1 3 3 3 grey2 5 5 5 grey3 8 8 8 grey4 10 10 10 grey5 13 13 13 grey6 15 15 15 grey7 18 18 18 grey8 20 20 20 grey9 23 23 23 grey10 26 26 26 grey11 28 28 28 grey12 31 31 31 grey13 33 33 33 grey14 36 36 36 grey15 38 38 38 grey16 41 41 41 grey17 43 43 43 grey18 46 46 46 grey19 48 48 48 grey20 51 51 51 grey21 54 54 54 grey22 56 56 56 grey23 59 59 59 grey24 61 61 61 grey25 64 64 64 grey26 66 66 66 grey27 69 69 69 grey28 71 71 71 grey29 74 74 74 grey30 77 77 77 grey31 79 79 79 grey32 82 82 82 grey33 84 84 84 grey34 87 87 87 grey35 89 89 89 grey36 92 92 92 grey37 94 94 94 grey38 97 97 97 grey39 99 99 99 grey40 102 102 102 grey41 105 105 105 grey42 107 107 107 grey43 110 110 110 grey44 112 112 112 grey45 115 115 115 grey46 117 117 117 grey47 120 120 120 grey48 122 122 122 grey49 125 125 125 grey50 127 127 127 grey51 130 130 130 grey52 133 133 133 grey53 135 135 135 grey54 138 138 138 grey55 140 140 140 grey56 143 143 143 grey57 145 145 145 grey58 148 148 148 grey59 150 150 150 grey60 153 153 153 grey61 156 156 156 grey62 158 158 158 grey63 161 161 161 grey64 163 163 163 grey65 166 166 166 grey66 168 168 168 grey67 171 171 171 grey68 173 173 173 grey69 176 176 176 grey70 179 179 179 grey71 181 181 181 grey72 184 184 184 grey73 186 186 186 grey74 189 189 189 grey75 191 191 191 grey76 194 194 194 grey77 196 196 196 grey78 199 199 199 grey79 201 201 201 grey80 204 204 204 grey81 207 207 207 grey82 209 209 209 grey83 212 212 212 grey84 214 214 214 grey85 217 217 217 grey86 219 219 219 grey87 222 222 222 grey88 224 224 224 grey89 227 227 227 grey90 229 229 229 grey91 232 232 232 grey92 235 235 235 grey93 237 237 237 grey94 240 240 240 grey95 242 242 242 grey96 245 245 245 grey97 247 247 247 grey98 250 250 250 grey99 252 252 252 grey100 255 255 255 honeydew 240 255 240 honeydew1 240 255 240 honeydew2 224 238 224 honeydew3 193 205 193 honeydew4 131 139 131 hot pink 255 105 180 HotPink 255 105 180 HotPink1 255 110 180 HotPink2 238 106 167 HotPink3 205 96 144 HotPink4 139 58 98 indian red 205 92 92 IndianRed 205 92 92 IndianRed1 255 106 106 IndianRed2 238 99 99 IndianRed3 205 85 85 IndianRed4 139 58 58 indigo 75 0 130 ivory 255 255 240 ivory1 255 255 240 ivory2 238 238 224 ivory3 205 205 193 ivory4 139 139 131 khaki 240 230 140 khaki1 255 246 143 khaki2 238 230 133 khaki3 205 198 115 khaki4 139 134 78 lavender 230 230 250 lavender blush 255 240 245 LavenderBlush 255 240 245 LavenderBlush1 255 240 245 LavenderBlush2 238 224 229 LavenderBlush3 205 193 197 LavenderBlush4 139 131 134 lawn green 124 252 0 LawnGreen 124 252 0 lemon chiffon 255 250 205 LemonChiffon 255 250 205 LemonChiffon1 255 250 205 LemonChiffon2 238 233 191 LemonChiffon3 205 201 165 LemonChiffon4 139 137 112 light blue 173 216 230 light coral 240 128 128 light cyan 224 255 255 light goldenrod 238 221 130 light goldenrod yellow 250 250 210 light gray 211 211 211 light green 144 238 144 light grey 211 211 211 light pink 255 182 193 light salmon 255 160 122 light sea green 32 178 170 light sky blue 135 206 250 light slate blue 132 112 255 light slate gray 119 136 153 light slate grey 119 136 153 light steel blue 176 196 222 light yellow 255 255 224 LightBlue 173 216 230 LightBlue1 191 239 255 LightBlue2 178 223 238 LightBlue3 154 192 205 LightBlue4 104 131 139 LightCoral 240 128 128 LightCyan 224 255 255 LightCyan1 224 255 255 LightCyan2 209 238 238 LightCyan3 180 205 205 LightCyan4 122 139 139 LightGoldenrod 238 221 130 LightGoldenrod1 255 236 139 LightGoldenrod2 238 220 130 LightGoldenrod3 205 190 112 LightGoldenrod4 139 129 76 LightGoldenrodYellow 250 250 210 LightGray 211 211 211 LightGreen 144 238 144 LightGrey 211 211 211 LightPink 255 182 193 LightPink1 255 174 185 LightPink2 238 162 173 LightPink3 205 140 149 LightPink4 139 95 101 LightSalmon 255 160 122 LightSalmon1 255 160 122 LightSalmon2 238 149 114 LightSalmon3 205 129 98 LightSalmon4 139 87 66 LightSeaGreen 32 178 170 LightSkyBlue 135 206 250 LightSkyBlue1 176 226 255 LightSkyBlue2 164 211 238 LightSkyBlue3 141 182 205 LightSkyBlue4 96 123 139 LightSlateBlue 132 112 255 LightSlateGray 119 136 153 LightSlateGrey 119 136 153 LightSteelBlue 176 196 222 LightSteelBlue1 202 225 255 LightSteelBlue2 188 210 238 LightSteelBlue3 162 181 205 LightSteelBlue4 110 123 139 LightYellow 255 255 224 LightYellow1 255 255 224 LightYellow2 238 238 209 LightYellow3 205 205 180 LightYellow4 139 139 122 lime 0 255 0 lime green 50 205 50 LimeGreen 50 205 50 linen 250 240 230 magenta 255 0 255 magenta1 255 0 255 magenta2 238 0 238 magenta3 205 0 205 magenta4 139 0 139 maroon 128 0 0 maroon1 255 52 179 maroon2 238 48 167 maroon3 205 41 144 maroon4 139 28 98 medium aquamarine 102 205 170 medium blue 0 0 205 medium orchid 186 85 211 medium purple 147 112 219 medium sea green 60 179 113 medium slate blue 123 104 238 medium spring green 0 250 154 medium turquoise 72 209 204 medium violet red 199 21 133 MediumAquamarine 102 205 170 MediumBlue 0 0 205 MediumOrchid 186 85 211 MediumOrchid1 224 102 255 MediumOrchid2 209 95 238 MediumOrchid3 180 82 205 MediumOrchid4 122 55 139 MediumPurple 147 112 219 MediumPurple1 171 130 255 MediumPurple2 159 121 238 MediumPurple3 137 104 205 MediumPurple4 93 71 139 MediumSeaGreen 60 179 113 MediumSlateBlue 123 104 238 MediumSpringGreen 0 250 154 MediumTurquoise 72 209 204 MediumVioletRed 199 21 133 midnight blue 25 25 112 MidnightBlue 25 25 112 mint cream 245 255 250 MintCream 245 255 250 misty rose 255 228 225 MistyRose 255 228 225 MistyRose1 255 228 225 MistyRose2 238 213 210 MistyRose3 205 183 181 MistyRose4 139 125 123 moccasin 255 228 181 navajo white 255 222 173 NavajoWhite 255 222 173 NavajoWhite1 255 222 173 NavajoWhite2 238 207 161 NavajoWhite3 205 179 139 NavajoWhite4 139 121 94 navy 0 0 128 navy blue 0 0 128 NavyBlue 0 0 128 old lace 253 245 230 OldLace 253 245 230 olive 128 128 0 olive drab 107 142 35 OliveDrab 107 142 35 OliveDrab1 192 255 62 OliveDrab2 179 238 58 OliveDrab3 154 205 50 OliveDrab4 105 139 34 orange 255 165 0 orange red 255 69 0 orange1 255 165 0 orange2 238 154 0 orange3 205 133 0 orange4 139 90 0 OrangeRed 255 69 0 OrangeRed1 255 69 0 OrangeRed2 238 64 0 OrangeRed3 205 55 0 OrangeRed4 139 37 0 orchid 218 112 214 orchid1 255 131 250 orchid2 238 122 233 orchid3 205 105 201 orchid4 139 71 137 pale goldenrod 238 232 170 pale green 152 251 152 pale turquoise 175 238 238 pale violet red 219 112 147 PaleGoldenrod 238 232 170 PaleGreen 152 251 152 PaleGreen1 154 255 154 PaleGreen2 144 238 144 PaleGreen3 124 205 124 PaleGreen4 84 139 84 PaleTurquoise 175 238 238 PaleTurquoise1 187 255 255 PaleTurquoise2 174 238 238 PaleTurquoise3 150 205 205 PaleTurquoise4 102 139 139 PaleVioletRed 219 112 147 PaleVioletRed1 255 130 171 PaleVioletRed2 238 121 159 PaleVioletRed3 205 104 127 PaleVioletRed4 139 71 93 papaya whip 255 239 213 PapayaWhip 255 239 213 peach puff 255 218 185 PeachPuff 255 218 185 PeachPuff1 255 218 185 PeachPuff2 238 203 173 PeachPuff3 205 175 149 PeachPuff4 139 119 101 peru 205 133 63 pink 255 192 203 pink1 255 181 197 pink2 238 169 184 pink3 205 145 158 pink4 139 99 108 plum 221 160 221 plum1 255 187 255 plum2 238 174 238 plum3 205 150 205 plum4 139 102 139 powder blue 176 224 230 PowderBlue 176 224 230 purple 128 0 128 purple1 155 48 255 purple2 145 44 238 purple3 125 38 205 purple4 85 26 139 red 255 0 0 red1 255 0 0 red2 238 0 0 red3 205 0 0 red4 139 0 0 rosy brown 188 143 143 RosyBrown 188 143 143 RosyBrown1 255 193 193 RosyBrown2 238 180 180 RosyBrown3 205 155 155 RosyBrown4 139 105 105 royal blue 65 105 225 RoyalBlue 65 105 225 RoyalBlue1 72 118 255 RoyalBlue2 67 110 238 RoyalBlue3 58 95 205 RoyalBlue4 39 64 139 saddle brown 139 69 19 SaddleBrown 139 69 19 salmon 250 128 114 salmon1 255 140 105 salmon2 238 130 98 salmon3 205 112 84 salmon4 139 76 57 sandy brown 244 164 96 SandyBrown 244 164 96 sea green 46 139 87 SeaGreen 46 139 87 SeaGreen1 84 255 159 SeaGreen2 78 238 148 SeaGreen3 67 205 128 SeaGreen4 46 139 87 seashell 255 245 238 seashell1 255 245 238 seashell2 238 229 222 seashell3 205 197 191 seashell4 139 134 130 sienna 160 82 45 sienna1 255 130 71 sienna2 238 121 66 sienna3 205 104 57 sienna4 139 71 38 silver 192 192 192 sky blue 135 206 235 SkyBlue 135 206 235 SkyBlue1 135 206 255 SkyBlue2 126 192 238 SkyBlue3 108 166 205 SkyBlue4 74 112 139 slate blue 106 90 205 slate gray 112 128 144 slate grey 112 128 144 SlateBlue 106 90 205 SlateBlue1 131 111 255 SlateBlue2 122 103 238 SlateBlue3 105 89 205 SlateBlue4 71 60 139 SlateGray 112 128 144 SlateGray1 198 226 255 SlateGray2 185 211 238 SlateGray3 159 182 205 SlateGray4 108 123 139 SlateGrey 112 128 144 snow 255 250 250 snow1 255 250 250 snow2 238 233 233 snow3 205 201 201 snow4 139 137 137 spring green 0 255 127 SpringGreen 0 255 127 SpringGreen1 0 255 127 SpringGreen2 0 238 118 SpringGreen3 0 205 102 SpringGreen4 0 139 69 steel blue 70 130 180 SteelBlue 70 130 180 SteelBlue1 99 184 255 SteelBlue2 92 172 238 SteelBlue3 79 148 205 SteelBlue4 54 100 139 tan 210 180 140 tan1 255 165 79 tan2 238 154 73 tan3 205 133 63 tan4 139 90 43 teal 0 128 128 thistle 216 191 216 thistle1 255 225 255 thistle2 238 210 238 thistle3 205 181 205 thistle4 139 123 139 tomato 255 99 71 tomato1 255 99 71 tomato2 238 92 66 tomato3 205 79 57 tomato4 139 54 38 turquoise 64 224 208 turquoise1 0 245 255 turquoise2 0 229 238 turquoise3 0 197 205 turquoise4 0 134 139 violet 238 130 238 violet red 208 32 144 VioletRed 208 32 144 VioletRed1 255 62 150 VioletRed2 238 58 140 VioletRed3 205 50 120 VioletRed4 139 34 82 wheat 245 222 179 wheat1 255 231 186 wheat2 238 216 174 wheat3 205 186 150 wheat4 139 126 102 white 255 255 255 white smoke 245 245 245 WhiteSmoke 245 245 245 yellow 255 255 0 yellow green 154 205 50 yellow1 255 255 0 yellow2 238 238 0 yellow3 205 205 0 yellow4 139 139 0 YellowGreen 154 205 50 .DE .SH "PORTABILITY ISSUES" .TP \fBmacOS\fR . On macOS, the following additional system colors are available. This first group contains all of the HIBrush colors available in the HIToolbox library. Note that on macOS 10.14 (Mojave) and later these colors are unlikely to match the color actually used for the purpose suggested by the color name. .RS .DS systemActiveAreaFill systemAlertBackgroundActive systemAlertBackgroundInactive systemAlternatePrimaryHighlightColor systemAppleGuideCoachmark systemBevelActiveDark systemBevelActiveLight systemBevelInactiveDark systemBevelInactiveLight systemBlack systemButtonActiveDarkHighlight systemButtonActiveDarkShadow systemButtonActiveLightHighlight systemButtonActiveLightShadow systemButtonFace systemButtonFaceActive systemButtonFaceInactive systemButtonFacePressed systemButtonFrame systemButtonFrameActive systemButtonFrameInactive systemButtonInactiveDarkHighlight systemButtonInactiveDarkShadow systemButtonInactiveLightHighlight systemButtonInactiveLightShadow systemButtonPressedDarkHighlight systemButtonPressedDarkShadow systemButtonPressedLightHighlight systemButtonPressedLightShadow systemChasingArrows systemDialogBackgroundActive systemDialogBackgroundInactive systemDocumentWindowBackground systemDragHilite systemDrawerBackground systemFinderWindowBackground systemFocusHighlight systemHighlight systemHighlightAlternate systemHighlightSecondary systemIconLabelBackground systemIconLabelBackgroundSelected systemListViewBackground systemListViewColumnDivider systemListViewEvenRowBackground systemListViewOddRowBackground systemListViewSeparator systemListViewSortColumnBackground systemMenu systemMenuActive systemMenuBackground systemMenuBackgroundSelected systemModelessDialogBackgroundActive systemModelessDialogBackgroundInactive systemMovableModalBackground systemNotificationWindowBackground systemPopupArrowActive systemPopupArrowInactive systemPopupArrowPressed systemPrimaryHighlightColor systemScrollBarDelimiterActive systemScrollBarDelimiterInactive systemSecondaryHighlightColor systemSelectedTabTextColor systemSheetBackground systemSheetBackgroundOpaque systemSheetBackgroundTransparent systemStaticAreaFill systemToolbarBackground systemTransparent systemUtilityWindowBackgroundActive systemUtilityWindowBackgroundInactive systemWhite systemWindowBody .DE .RE . Tk supports all of the NSColors in the macOS System ColorList. The convention for naming these colors is that the Tk name is generated by capitalizing the macOS name and adding the prefix "system". On macOS 10.14 (Mojave) and later many of these "semantic" colors will appear differently depending on whether the NSWindow in which they are used has the Aqua or DarkAqua appearance. The System ColorList differs between releases of macOS and some colors, such as systemLinkColor and systemControlAccentColor, are simulated on older systems which did not provide them. All of the colors below are available on all supported macOS releases, but newer systems will support additional colors. .RS .DS systemControlAccentColor systemControlTextColor systemDisabledControlTextColor systemLabelColor systemLinkColor systemPlaceholderTextColor systemSelectedTextBackgroundColor systemSelectedTextColor systemSeparatorColor systemTextBackgroundColor systemTextColor .DE .RE . The numbered systemWindowBackgroundColors below are used in the \fBttk::notebook\fR and \fBttk::labelframe\fR widgets to provide a contrasting background. Each numbered color contrasts with its predecessor. .RS .DS systemWindowBackgroundColor systemWindowBackgroundColor1 systemWindowBackgroundColor2 systemWindowBackgroundColor3 systemWindowBackgroundColor4 systemWindowBackgroundColor5 systemWindowBackgroundColor6 systemWindowBackgroundColor7 .DE .RE .TP \fBWindows\fR . On Windows, the following additional system colors are available (note that the actual color values depend on the currently active OS theme): .RS .DS .ta 6c system3dDarkShadow systemHighlightText system3dLight systemInactiveBorder systemActiveBorder systemInactiveCaption systemActiveCaption systemInactiveCaptionText systemAppWorkspace systemInfoBackground systemBackground systemInfoText systemButtonFace systemMenu systemButtonHighlight systemMenuText systemButtonShadow systemPlaceholderText systemButtonText systemScrollbar systemCaptionText systemWindow systemDisabledText systemWindowFrame systemGrayText systemWindowText systemHighlight .DE .RE .SH "SEE ALSO" options(n), Tk_GetColor(3) .SH KEYWORDS color, option '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ConfigWidg.30000644001000000100000000006752115105057705017733 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_ConfigureWidget\fR(\fIinterp, tkwin, specs, objc, objv, widgRec, flags\fR) .sp int \fBTk_ConfigureInfo\fR(\fIinterp, tkwin, specs, widgRec, argvName, flags\fR) .sp int \fBTk_ConfigureValue\fR(\fIinterp, tkwin, specs, widgRec, argvName, flags\fR) .sp \fBTk_FreeOptions\fR(\fIspecs, widgRec, display, flags\fR) .fi .SH ARGUMENTS .AS void *widgRec in/out .AP Tcl_Interp *interp in Interpreter to use for returning error messages. .AP Tk_Window tkwin in Window used to represent widget (needed to set up X resources). .AP "const Tk_ConfigSpec" *specs in Pointer to table specifying legal configuration options for this widget. .AP Tcl_Size objc in Number of arguments in \fIobjv\fR. .AP "Tcl_Obj *const *" objv in Command-line options for configuring widget. .AP char *widgRec in/out Points to widget record structure. Fields in this structure get modified by \fBTk_ConfigureWidget\fR to hold configuration information. .AP int flags in If non-zero, then it specifies an OR-ed combination of flags that control the processing of configuration information. \fBTK_CONFIG_ARGV_ONLY\fR causes the option database and defaults to be ignored, and flag bits \fBTK_CONFIG_USER_BIT\fR and higher are used to selectively disable entries in \fIspecs\fR. .AP "type name" type in The name of the type of a widget record. .AP "field name" field in The name of a field in records of type \fItype\fR. .AP "const char" *argvName in The name used on Tcl command lines to refer to a particular option (e.g. when creating a widget or invoking the \fBconfigure\fR widget command). If non-NULL, then information is returned only for this option. If NULL, then information is returned for all available options. .AP Display *display in Display containing widget whose record is being freed; needed in order to free up resources. .BE .SH DESCRIPTION .PP Note that \fBTk_ConfigureWidget\fR should be replaced with the new \fBTcl_Obj\fR based API, \fBTk_SetOptions\fR. The old interface is retained for backward compatibility. .PP \fBTk_ConfigureWidget\fR is called to configure various aspects of a widget, such as colors, fonts, border width, etc. It is intended as a convenience procedure to reduce the amount of code that must be written in individual widget managers to handle configuration information. It is typically invoked when widgets are created, and again when the \fBconfigure\fR command is invoked for a widget. Although intended primarily for widgets, \fBTk_ConfigureWidget\fR can be used in other situations where \fIobjc-objv\fR information is to be used to fill in a record structure, such as configuring graphical elements for a canvas widget or entries of a menu. .PP \fBTk_ConfigureWidget\fR processes a table specifying the configuration options that are supported (\fIspecs\fR) and a collection of command-line arguments (\fIobjc\fR and \fIobjv\fR) to fill in fields of a record (\fIwidgRec\fR). It uses the option database and defaults specified in \fIspecs\fR to fill in fields of \fIwidgRec\fR that are not specified in \fIobjv\fR. \fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this case it does not modify \fIinterp\fR. If an error occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will leave an error message in interpreter \fIinterp\fR's result in the standard Tcl fashion. In the event of an error return, some of the fields of \fIwidgRec\fR could already have been set, if configuration information for them was successfully processed before the error occurred. The other fields will be set to reasonable initial values so that \fBTk_FreeOptions\fR can be called for cleanup. .PP The \fIspecs\fR array specifies the kinds of configuration options expected by the widget. Each of its entries specifies one configuration option and has the following structure: .CS typedef struct { int \fItype\fR; const char *\fIargvName\fR; const char *\fIdbName\fR; const char *\fIdbClass\fR; const char *\fIdefValue\fR; Tcl_Size \fIoffset\fR; int \fIspecFlags\fR; const Tk_CustomOption *\fIcustomPtr\fR; } \fBTk_ConfigSpec\fR; .CE The \fItype\fR field indicates what type of configuration option this is (e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for an integer value). The \fItype\fR field indicates how to use the value of the option (more on this below). The \fIargvName\fR field is a string such as .QW \-font or .QW \-bg , which is compared with the values in \fIobjv\fR (if \fIargvName\fR is NULL it means this is a grouped entry; see \fBGROUPED ENTRIES\fR below). The \fIdbName\fR and \fIdbClass\fR fields are used to look up a value for this option in the option database. The \fIdefValue\fR field specifies a default value for this configuration option if no value is specified in either \fIobjv\fR or the option database. \fIOffset\fR indicates where in \fIwidgRec\fR to store information about this option, and \fIspecFlags\fR contains additional information to control the processing of this configuration option (see FLAGS below). The last field, \fIcustomPtr\fR, is only used if \fItype\fR is \fBTK_CONFIG_CUSTOM\fR; see CUSTOM OPTION TYPES below. .PP \fBTk_ConfigureWidget\fR first processes \fIobjv\fR to see which (if any) configuration options are specified there. \fIArgv\fR must contain an even number of fields; the first of each pair of fields must match the \fIargvName\fR of some entry in \fIspecs\fR (unique abbreviations are acceptable), and the second field of the pair contains the value for that configuration option. If there are entries in \fIspec\fR for which there were no matching entries in \fIobjv\fR, \fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR fields of the \fIspecs\fR entry to probe the option database; if a value is found, then it is used as the value for the option. Finally, if no entry is found in the option database, the \fIdefValue\fR field of the \fIspecs\fR entry is used as the value for the configuration option. If the \fIdefValue\fR is NULL, or if the \fBTK_CONFIG_DONT_SET_DEFAULT\fR bit is set in \fIflags\fR, then there is no default value and this \fIspecs\fR entry will be ignored if no value is specified in \fIobjv\fR or the option database. .PP Once a string value has been determined for a configuration option, \fBTk_ConfigureWidget\fR translates the string value into a more useful form, such as a color if \fItype\fR is \fBTK_CONFIG_COLOR\fR or an integer if \fItype\fR is \fBTK_CONFIG_INT\fR. This value is then stored in the record pointed to by \fIwidgRec\fR. This record is assumed to contain information relevant to the manager of the widget; its exact type is unknown to \fBTk_ConfigureWidget\fR. The \fIoffset\fR field of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store the information about this configuration option. You should use the \fBoffsetof\fR macro to generate \fIoffset\fR values. The location indicated by \fIwidgRec\fR and \fIoffset\fR will be referred to as the .QW target in the descriptions below. .PP The \fItype\fR field of each entry in \fIspecs\fR determines what to do with the string value of that configuration option. The legal values for \fItype\fR, and the corresponding actions, are: .TP \fBTK_CONFIG_ACTIVE_CURSOR\fR . The value must be an ASCII string identifying a cursor in a form suitable for passing to \fBTk_GetCursor\fR. The value is converted to a \fBTk_Cursor\fR by calling \fBTk_GetCursor\fR and the result is stored in the target. In addition, the resulting cursor is made the active cursor for \fItkwin\fR by calling \fBXDefineCursor\fR. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target and \fItkwin\fR's active cursor will be set to \fBNone\fR. If the previous value of the target was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR. .TP \fBTK_CONFIG_ANCHOR\fR . The value must be an ASCII string identifying an anchor point in one of the ways accepted by \fBTk_GetAnchor\fR. The string is converted to a \fBTk_Anchor\fR by calling \fBTk_GetAnchor\fR and the result is stored in the target. .TP \fBTK_CONFIG_BITMAP\fR . The value must be an ASCII string identifying a bitmap in a form suitable for passing to \fBTk_GetBitmap\fR. The value is converted to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target is set to \fBNone\fR. If the previous value of the target was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR. .TP \fBTK_CONFIG_BOOLEAN\fR . The value must be an ASCII string specifying a boolean value. Any of the values .QW true , .QW yes , .QW on , or .QW 1 , or an abbreviation of one of these values, means true; any of the values .QW false , .QW no , .QW off , or .QW 0 , or an abbreviation of one of these values, means false. The target is expected to be an integer; for true values it will be set to 1 and for false values it will be set to 0. .TP \fBTK_CONFIG_BORDER\fR . The value must be an ASCII string identifying a border color in a form suitable for passing to \fBTk_Get3DBorder\fR. The value is converted to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR. .TP \fBTK_CONFIG_CAP_STYLE\fR . The value must be an ASCII string identifying a cap style in one of the ways accepted by \fBTk_GetCapStyle\fR. The string is converted to an integer value corresponding to the cap style by calling \fBTk_GetCapStyle\fR and the result is stored in the target. .TP \fBTK_CONFIG_COLOR\fR . The value must be an ASCII string identifying a color in a form suitable for passing to \fBTk_GetColor\fR. The value is converted to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to \fBNone\fR. If the previous value of the target was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR. .TP \fBTK_CONFIG_CURSOR\fR . This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except that the new cursor is not made the active one for \fItkwin\fR. .TP \fBTK_CONFIG_CUSTOM\fR . This option allows applications to define new option types. The \fIcustomPtr\fR field of the entry points to a structure defining the new option type. See the section \fBCUSTOM OPTION TYPES\fR below for details. .TP \fBTK_CONFIG_DOUBLE\fR . The value must be an ASCII floating-point number in the format accepted by \fBstrtol\fR. The string is converted to a \fBdouble\fR value, and the value is stored in the target. .TP \fBTK_CONFIG_END\fR . Marks the end of the table. The last entry in \fIspecs\fR must have this type; all of its other fields are ignored and it will never match any arguments. .TP \fBTK_CONFIG_FONT\fR . The value must be an ASCII string identifying a font in a form suitable for passing to \fBTk_GetFont\fR. The value is converted to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR. .TP \fBTK_CONFIG_INT\fR . The value must be an ASCII integer string in the format accepted by \fBstrtol\fR (e.g. .QW 0 and .QW 0x prefixes may be used to specify octal or hexadecimal numbers, respectively). The string is converted to an integer value and the integer is stored in the target. .TP \fBTK_CONFIG_JOIN_STYLE\fR . The value must be an ASCII string identifying a join style in one of the ways accepted by \fBTk_GetJoinStyle\fR. The string is converted to an integer value corresponding to the join style by calling \fBTk_GetJoinStyle\fR and the result is stored in the target. .TP \fBTK_CONFIG_JUSTIFY\fR . The value must be an ASCII string identifying a justification method in one of the ways accepted by \fBTk_GetJustify\fR. The string is converted to a \fBTk_Justify\fR by calling \fBTk_GetJustify\fR and the result is stored in the target. .TP \fBTK_CONFIG_MM\fR . The value must specify a screen distance in one of the forms acceptable to \fBTk_GetScreenMM\fR. The string is converted to double-precision floating-point distance in millimeters and the value is stored in the target. .TP \fBTK_CONFIG_PIXELS\fR . The value must specify screen units in one of the forms acceptable to \fBTk_GetPixels\fR. The string is converted to an integer distance in pixels and the value is stored in the target. .TP \fBTK_CONFIG_RELIEF\fR . The value must be an ASCII string identifying a relief in a form suitable for passing to \fBTk_GetRelief\fR. The value is converted to an integer relief value by calling \fBTk_GetRelief\fR and the result is stored in the target. .TP \fBTK_CONFIG_STRING\fR . A copy of the value is made by allocating memory space with \fBTcl_Alloc\fR and copying the value into the dynamically-allocated space. A pointer to the new string is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value may be an empty string, in which case the target will be set to NULL. If the previous value of the target was not NULL, then it is freed by passing it to \fBTcl_Free\fR. .TP \fBTK_CONFIG_SYNONYM\fR . This \fItype\fR value identifies special entries in \fIspecs\fR that are synonyms for other entries. If an \fIobjv\fR value matches the \fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR for another entry whose \fIargvName\fR is the same as the \fIdbName\fR field in the \fBTK_CONFIG_SYNONYM\fR entry; this new entry is used just as if its \fIargvName\fR had matched the \fIobjv\fR value. The synonym mechanism allows multiple \fIobjv\fR values to be used for a single configuration option, such as .QW \-background and .QW \-bg . .TP \fBTK_CONFIG_UID\fR . The value is translated to a \fBTk_Uid\fR (by passing it to \fBTk_GetUid\fR). The resulting value is stored in the target. If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR and the value is an empty string then the target will be set to NULL. .TP \fBTK_CONFIG_WINDOW\fR . The value must be a window path name. It is translated to a \fBTk_Window\fR token and the token is stored in the target. .SH "GROUPED ENTRIES" .PP In some cases it is useful to generate multiple resources from a single configuration value. For example, a color name might be used both to generate the background color for a widget (using \fBTK_CONFIG_COLOR\fR) and to generate a 3-D border to draw around the widget (using \fBTK_CONFIG_BORDER\fR). In cases like this it is possible to specify that several consecutive entries in \fIspecs\fR are to be treated as a group. The first entry is used to determine a value (using its \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, and \fIdefValue\fR fields). The value will be processed several times (one for each entry in the group), generating multiple different resources and modifying multiple targets within \fIwidgRec\fR. Each of the entries after the first must have a NULL value in its \fIargvName\fR field; this indicates that the entry is to be grouped with the entry that precedes it. Only the \fItype\fR and \fIoffset\fR fields are used from these follow-on entries. .SH "FLAGS" .PP The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR to provide additional control over the processing of configuration options. These values are used in three different ways as described below. .PP First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0), then the option database and \fIdefValue\fR fields are not used. In this case, if an entry in \fIspecs\fR does not match a field in \fIobjv\fR then nothing happens: the corresponding target is not modified. This feature is useful when the goal is to modify certain configuration options while leaving others in their current state, such as when a \fBconfigure\fR widget command is being processed. .PP Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used to control the processing of that entry. Each \fIspecFlags\fR field may consists of an OR-ed combination of the following values: .TP \fBTK_CONFIG_COLOR_ONLY\fR . If this bit is set then the entry will only be considered if the display for \fItkwin\fR has more than one bit plane. If the display is monochromatic then this \fIspecs\fR entry will be ignored. .TP \fBTK_CONFIG_MONO_ONLY\fR . If this bit is set then the entry will only be considered if the display for \fItkwin\fR has exactly one bit plane. If the display is not monochromatic then this \fIspecs\fR entry will be ignored. .TP \fBTK_CONFIG_NULL_OK\fR . This bit is only relevant for some types of entries (see the descriptions of the various entry types above). If this bit is set, it indicates that an empty string value for the field is acceptable and if it occurs then the target should be set to NULL or \fBNone\fR, depending on the type of the target. This flag is typically used to allow a feature to be turned off entirely, e.g. set a cursor value to \fBNone\fR so that a window simply inherits its parent's cursor. If this bit is not set then empty strings are processed as strings, which generally results in an error. .TP \fBTK_CONFIG_DONT_SET_DEFAULT\fR . If this bit is one, it means that the \fIdefValue\fR field of the entry should only be used for returning the default value in \fBTk_ConfigureInfo\fR. In calls to \fBTk_ConfigureWidget\fR no default will be supplied for entries with this flag set; it is assumed that the caller has already supplied a default value in the target location. This flag provides a performance optimization where it is expensive to process the default string: the client can compute the default once, save the value, and provide it before calling \fBTk_ConfigureWidget\fR. .PP The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically used to specify different default values for monochrome and color displays. This is done by creating two entries in \fIspecs\fR that are identical except for their \fIdefValue\fR and \fIspecFlags\fR fields. One entry should have the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the default value for monochrome displays in its \fIdefValue\fR; the other entry should have the value \fBTK_CONFIG_COLOR_ONLY\fR in its \fIspecFlags\fR and the appropriate \fIdefValue\fR for color displays. .PP Third, it is possible to use \fIflags\fR and \fIspecFlags\fR together to selectively disable some entries. This feature is not needed very often. It is useful in cases where several similar kinds of widgets are implemented in one place. It allows a single \fIspecs\fR table to be created with all the configuration options for all the widget types. When processing a particular widget type, only entries relevant to that type will be used. This effect is achieved by setting the high-order bits (those in positions equal to or greater than \fBTK_CONFIG_USER_BIT\fR) in \fIspecFlags\fR values or in \fIflags\fR. In order for a particular entry in \fIspecs\fR to be used, its high-order bits must match exactly the high-order bits of the \fIflags\fR value passed to \fBTk_ConfigureWidget\fR. If a \fIspecs\fR table is being used for N different widget types, then N of the high-order bits will be used. Each \fIspecs\fR entry will have one of more of those bits set in its \fIspecFlags\fR field to indicate the widget types for which this entry is valid. When calling \fBTk_ConfigureWidget\fR, \fIflags\fR will have a single one of these bits set to select the entries for the desired widget type. For a working example of this feature, see the code in tkButton.c. .SH TK_CONFIGUREINFO .PP The \fBTk_ConfigureInfo\fR procedure may be used to obtain information about one or all of the options for a given widget. Given a token for a window (\fItkwin\fR), a table describing the configuration options for a class of widgets (\fIspecs\fR), a pointer to a widget record containing the current information for a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument, \fBTk_ConfigureInfo\fR generates a string describing all of the configuration options for the window. The string is placed in interpreter \fIinterp\fR's result. Under normal circumstances it returns \fBTCL_OK\fR; if an error occurs then it returns \fBTCL_ERROR\fR and the interpreter's result will contain an error message. .PP If \fIargvName\fR is NULL, then the value left in the interpreter's result by \fBTk_ConfigureInfo\fR consists of a list of one or more entries, each of which describes one configuration option (i.e. one entry in \fIspecs\fR). Each entry in the list will contain either two or five values. If the corresponding entry in \fIspecs\fR has type \fBTK_CONFIG_SYNONYM\fR, then the list will contain two values: the \fIargvName\fR for the entry and the \fIdbName\fR (synonym name). Otherwise the list will contain five values: \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR, and current value. The current value is computed from the appropriate field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR. .PP If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL, then it indicates a single option, and information is returned only for that option. The string placed in the interpreter's result will be a list containing two or five values as described above; this will be identical to the corresponding sublist that would have been returned if \fIargvName\fR had been NULL. .PP The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR. .SH TK_CONFIGUREVALUE .PP \fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR; instead of returning a list of values, it just returns the current value of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL). The value is returned in interpreter \fIinterp\fR's result and \fBTCL_OK\fR is normally returned as the procedure's result. If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is not a valid option name), \fBTCL_ERROR\fR is returned and an error message is left in the interpreter's result. This procedure is typically called to implement \fBcget\fR widget commands. .SH TK_FREEOPTIONS .PP The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup to release all of the resources associated with configuration options. It scans through \fIspecs\fR and for each entry corresponding to a resource that must be explicitly freed (e.g. those with type \fBTK_CONFIG_COLOR\fR), it frees the resource in the widget record. If the field in the widget record does not refer to a resource (e.g. it contains a null pointer) then no resource is freed for that entry. After freeing a resource, \fBTk_FreeOptions\fR sets the corresponding field of the widget record to null. .SH "CUSTOM OPTION TYPES" .PP Applications can extend the built-in configuration types with additional configuration types by writing procedures to parse and print options of the a type and creating a structure pointing to those procedures: .CS typedef struct { Tk_OptionParseProc *\fIparseProc\fR; Tk_OptionPrintProc *\fIprintProc\fR; void *\fIclientData\fR; } \fBTk_CustomOption\fR; typedef int \fBTk_OptionParseProc\fR( void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, Tk_Window \fItkwin\fR, const char *\fIvalue\fR, char *\fIwidgRec\fR, Tcl_Size \fIoffset\fR); typedef const char *\fBTk_OptionPrintProc\fR( void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIwidgRec\fR, Tcl_Size \fIoffset\fR, Tcl_FreeProc **\fIfreeProcPtr\fR); .CE The Tk_CustomOption structure contains three fields, which are pointers to the two procedures and a \fIclientData\fR value to be passed to those procedures when they are invoked. The \fIclientData\fR value typically points to a structure containing information that is needed by the procedures when they are parsing and printing options. .PP The \fIparseProc\fR procedure is invoked by \fBTk_ConfigureWidget\fR to parse a string and store the resulting value in the widget record. The \fIclientData\fR argument is a copy of the \fIclientData\fR field in the Tk_CustomOption structure. The \fIinterp\fR argument points to a Tcl interpreter used for error reporting. \fITkwin\fR is a copy of the \fItkwin\fR argument to \fBTk_ConfigureWidget\fR. The \fIvalue\fR argument is a string describing the value for the option; it could have been specified explicitly in the call to \fBTk_ConfigureWidget\fR or it could come from the option database or a default. \fIValue\fR will never be a null pointer but it may point to an empty string. \fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to \fBTk_ConfigureWidget\fR; it points to the start of the widget record to modify. The last argument, \fIoffset\fR, gives the offset in bytes from the start of the widget record to the location where the option value is to be placed. The procedure should translate the string to whatever form is appropriate for the option and store the value in the widget record. It should normally return \fBTCL_OK\fR, but if an error occurs in translating the string to a value then it should return \fBTCL_ERROR\fR and store an error message in interpreter \fIinterp\fR's result. .PP The \fIprintProc\fR procedure is called by \fBTk_ConfigureInfo\fR to produce a string value describing an existing option. Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR arguments all have the same meaning as for Tk_OptionParseProc procedures. The \fIprintProc\fR procedure should examine the option whose value is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing that option, and return a pointer to the string. If the string is stored in dynamically-allocated memory, then the procedure must set \fI*freeProcPtr\fR to the address of a procedure to call to free the string's memory; \fBTk_ConfigureInfo\fR will call this procedure when it is finished with the string. If the result string is stored in static memory then \fIprintProc\fR need not do anything with the \fIfreeProcPtr\fR argument. .PP Once \fIparseProc\fR and \fIprintProc\fR have been defined and a Tk_CustomOption structure has been created for them, options of this new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR fields are \fBTK_CONFIG_CUSTOM\fR and whose \fIcustomPtr\fR fields point to the Tk_CustomOption structure. .SH EXAMPLES .PP Although the explanation of \fBTk_ConfigureWidget\fR is fairly complicated, its actual use is pretty straightforward. The easiest way to get started is to copy the code from an existing widget. The library implementation of frames (tkFrame.c) has a simple configuration table, and the library implementation of buttons (tkButton.c) has a much more complex table that uses many of the fancy \fIspecFlags\fR mechanisms. .SH "SEE ALSO" Tk_SetOptions(3) .SH KEYWORDS anchor, bitmap, boolean, border, cap style, color, configuration options, cursor, custom, double, font, integer, join style, justify, millimeters, pixels, relief, synonym, uid tk9.0.3/doc/ConfigWind.30000644001000000100000000001404015105057705017726 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1993 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_ConfigureWindow 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_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 .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_ConfigureWindow\fR(\fItkwin, valueMask, valuePtr\fR) .sp \fBTk_MoveWindow\fR(\fItkwin, x, y\fR) .sp \fBTk_ResizeWindow\fR(\fItkwin, width, height\fR) .sp \fBTk_MoveResizeWindow\fR(\fItkwin, x, y, width, height\fR) .sp \fBTk_SetWindowBorderWidth\fR(\fItkwin, borderWidth\fR) .sp \fBTk_ChangeWindowAttributes\fR(\fItkwin, valueMask, attsPtr\fR) .sp \fBTk_SetWindowBackground\fR(\fItkwin, pixel\fR) .sp \fBTk_SetWindowBackgroundPixmap\fR(\fItkwin, pixmap\fR) .sp \fBTk_SetWindowBorder\fR(\fItkwin, pixel\fR) .sp \fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR) .sp \fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR) .sp \fBTk_DefineCursor\fR(\fItkwin, cursor\fR) .sp \fBTk_UndefineCursor\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS XSetWindowAttributes borderWidth .AP Tk_Window tkwin in Token for window. .AP "unsigned int" valueMask in OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR, indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use. .AP XWindowChanges *valuePtr in Points to a structure containing new values for the configuration parameters selected by \fIvalueMask\fR. Fields not selected by \fIvalueMask\fR are ignored. .AP int x in New x-coordinate for \fItkwin\fR's top left pixel (including border, if any) within tkwin's parent. .AP int y in New y-coordinate for \fItkwin\fR's top left pixel (including border, if any) within tkwin's parent. .AP "int" width in New width for \fItkwin\fR (interior, not including border). .AP "int" height in New height for \fItkwin\fR (interior, not including border). .AP "int" borderWidth in New width for \fItkwin\fR's border. .AP XSetWindowAttributes *attsPtr in Points to a structure containing new values for the attributes given by the \fIvalueMask\fR argument. Attributes not selected by \fIvalueMask\fR are ignored. .AP "unsigned long" pixel in New background or border color for window. .AP Pixmap pixmap in New pixmap to use for background or border of \fItkwin\fR. WARNING: cannot necessarily be deleted immediately, as for Xlib calls. See note below. .AP Colormap colormap in New colormap to use for \fItkwin\fR. .AP Tk_Cursor cursor in New cursor to use for \fItkwin\fR. If \fBNone\fR is specified, then \fItkwin\fR will not have its own cursor; it will use the cursor of its parent. .BE .SH DESCRIPTION .PP These procedures are analogous to the X library procedures with similar names, such as \fBXConfigureWindow\fR. Each one of the above procedures calls the corresponding X procedure and also saves the configuration information in Tk's local structure for the window. This allows the information to be retrieved quickly by the application (using macros such as \fBTk_X\fR and \fBTk_Height\fR) without having to contact the X server. In addition, if no X window has actually been created for \fItkwin\fR yet, these procedures do not issue X operations or cause event handlers to be invoked; they save the information in Tk's local structure for the window; when the window is created later, the saved information will be used to configure the window. .PP See the X library documentation for details on what these procedures do and how they use their arguments. .PP In the procedures \fBTk_ConfigureWindow\fR, \fBTk_MoveWindow\fR, \fBTk_ResizeWindow\fR, \fBTk_MoveResizeWindow\fR, and \fBTk_SetWindowBorderWidth\fR, if \fItkwin\fR is an internal window then event handlers interested in configure events are invoked immediately, before the procedure returns. If \fItkwin\fR is a top-level window then the event handlers will be invoked later, after X has seen the request and returned an event for it. .PP Applications using Tk should never call procedures like \fBXConfigureWindow\fR directly; they should always use the corresponding Tk procedures. .PP The size and location of a window should only be modified by the appropriate geometry manager for that window and never by a window itself (but see \fBTk_MoveToplevelWindow\fR for moving a top-level window). .PP You may not use \fBTk_ConfigureWindow\fR to change the stacking order of a window (\fIvalueMask\fR may not contain the \fBCWSibling\fR or \fBCWStackMode\fR bits). To change the stacking order, use the procedure \fBTk_RestackWindow\fR. .PP The procedure \fBTk_SetWindowColormap\fR will automatically add \fItkwin\fR to the \fBTK_COLORMAP_WINDOWS\fR property of its nearest top-level ancestor if the new colormap is different from that of \fItkwin\fR's parent and \fItkwin\fR is not already in the \fBTK_COLORMAP_WINDOWS\fR property. .SH BUGS .PP \fBTk_SetWindowBackgroundPixmap\fR and \fBTk_SetWindowBorderPixmap\fR differ slightly from their Xlib counterparts in that the \fIpixmap\fR argument may not necessarily be deleted immediately after calling one of these procedures. This is because \fItkwin\fR's window may not exist yet at the time of the call, in which case \fIpixmap\fR is merely saved and used later when \fItkwin\fR's window is actually created. If you wish to delete \fIpixmap\fR, then call \fBTk_MakeWindowExist\fR first to be sure that \fItkwin\fR's window exists and \fIpixmap\fR has been passed to the X server. .PP A similar problem occurs for the \fIcursor\fR argument passed to \fBTk_DefineCursor\fR. The solution is the same as for pixmaps above: call \fBTk_MakeWindowExist\fR before freeing the cursor. .SH "SEE ALSO" Tk_MoveToplevelWindow, Tk_RestackWindow .SH KEYWORDS attributes, border, color, configure, height, pixel, pixmap, width, window, x, y tk9.0.3/doc/console.n0000644001000000100000000001400715105057705017437 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2001 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH console n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME console \- Control the console on systems without a real console .SH SYNOPSIS \fBconsole\fI subcommand\fR ?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The console window is a replacement for a real console to allow input and output on the standard I/O channels on platforms that do not have a real console. It is implemented as a separate interpreter with the Tk toolkit loaded, and control over this interpreter is given through the \fBconsole\fR command. The behaviour of the console window is defined mainly through the contents of the \fIconsole.tcl\fR file in the Tk library. Except for TkAqua, this command is not available when Tk is loaded into a tclsh interpreter with .QW "\fBpackage require tk\fR" , as a conventional terminal is expected to be present in that case. In TkAqua, this command is disabled when there is a startup script and stdin is \fB/dev/null\fR (as is the case e.g. when a bundled application embedding Tk is started by the macOS Launcher). To enable the command in that case, define the environment variable \fBTK_CONSOLE\fR. This can be done by modifying the Info.plist file by adding the LSEnvironment key to the main dict and setting its value to be a dict with the key \fBTK_CONSOLE\fR. .PP .\" METHOD: eval .TP \fBconsole eval \fIscript\fR . Evaluate the \fIscript\fR argument as a Tcl script in the console interpreter. The normal interpreter is accessed through the \fBconsoleinterp\fR command in the console interpreter. .\" METHOD: hide .TP \fBconsole hide\fR . Hide the console window from view. Precisely equivalent to withdrawing the \fB.\fR window in the console interpreter. .\" METHOD: show .TP \fBconsole show\fR . Display the console window. Precisely equivalent to deiconifying the \fB.\fR window in the console interpreter. .\" METHOD: title .TP \fBconsole title \fR?\fIstring\fR? . Query or modify the title of the console window. If \fIstring\fR is not specified, queries the title of the console window, and sets the title of the console window to \fIstring\fR otherwise. Precisely equivalent to using the \fBwm title\fR command in the console interpreter. .SH "ACCESS TO THE MAIN INTERPRETER" .PP The \fBconsoleinterp\fR command in the console interpreter allows scripts to be evaluated in the main interpreter. It supports two subcommands: \fBeval\fR and \fBrecord\fR. .PP .\" METHOD: eval .TP \fBconsoleinterp eval \fIscript\fR . Evaluates \fIscript\fR as a Tcl script at the global level in the main interpreter. .\" METHOD: record .TP \fBconsoleinterp record \fIscript\fR . Records and evaluates \fIscript\fR as a Tcl script at the global level in the main interpreter as if \fIscript\fR had been typed in at the console. .SH "ADDITIONAL TRAP CALLS" .PP There are several additional commands in the console interpreter that are called in response to activity in the main interpreter. \fIThese are documented here for completeness only; they form part of the internal implementation of the console and are likely to change or be modified without warning.\fR .PP Output to the console from the main interpreter via the stdout and stderr channels is handled by invoking the \fBtk::ConsoleOutput\fR command in the console interpreter with two arguments. The first argument is the name of the channel being written to, and the second argument is the string being written to the channel (after encoding and end-of-line translation processing has been performed.) .PP When the \fB.\fR window of the main interpreter is destroyed, the \fBtk::ConsoleExit\fR command in the console interpreter is called (assuming the console interpreter has not already been deleted itself, that is.) .SH "DEFAULT BINDINGS" .PP The default script creates a console window (implemented using a text widget) that has the following behaviour: .IP [1] Pressing the tab key inserts a TAB character (as defined by the Tcl \et escape.) .IP [2] Pressing the return key causes the current line (if complete by the rules of \fBinfo complete\fR) to be passed to the main interpreter for evaluation. .IP [3] Pressing the delete key deletes the selected text (if any text is selected) or the character to the right of the cursor (if not at the end of the line.) .IP [4] Pressing the backspace key deletes the selected text (if any text is selected) or the character to the left of the cursor (of not at the start of the line.) .IP [5] Pressing either Control+A or the home key causes the cursor to go to the start of the line (but after the prompt, if a prompt is present on the line.) .IP [6] Pressing either Control+E or the end key causes the cursor to go to the end of the line. .IP [7] Pressing either Control+P or the up key causes the previous entry in the command history to be selected. .IP [8] Pressing either Control+N or the down key causes the next entry in the command history to be selected. .IP [9] Pressing either Control+B or the left key causes the cursor to move one character backward as long as the cursor is not at the prompt. .IP [10] Pressing either Control+F or the right key causes the cursor to move one character forward. .IP [11] Pressing F9 rebuilds the console window by destroying all its children and reloading the Tcl script that defined the console's behaviour. .PP Most other behaviour is the same as a conventional text widget except for the way that the \fI<>\fR event is handled identically to the \fI<>\fR event. .SH EXAMPLE .PP Not all platforms have the \fBconsole\fR command, so debugging code often has the following code fragment in it so output produced by \fBputs\fR can be seen while during development: .CS catch {\fBconsole show\fR} .CE .SH "SEE ALSO" destroy(n), fconfigure(n), history(n), interp(n), puts(n), text(n), wm(n) .SH KEYWORDS console, interpreter, window, interactive, output channels '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/CoordToWin.30000644001000000100000000000317315105057705017733 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1993 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CoordsToWindow 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CoordsToWindow \- Find window containing a point .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Window \fBTk_CoordsToWindow\fR(\fIrootX, rootY, tkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP int rootX in X-coordinate (in root window coordinates). .AP int rootY in Y-coordinate (in root window coordinates). .AP Tk_Window tkwin in Token for window that identifies application. .BE .SH DESCRIPTION .PP \fBTk_CoordsToWindow\fR locates the window that contains a given point. The point is specified in root coordinates with \fIrootX\fR and \fIrootY\fR (if a virtual-root window manager is in use then \fIrootX\fR and \fIrootY\fR are in the coordinate system of the virtual root window). The return value from the procedure is a token for the window that contains the given point. If the point is not in any window, or if the containing window is not in the same application as \fItkwin\fR, then NULL is returned. .PP The containing window is decided using the same rules that determine which window contains the mouse cursor: if a parent and a child both contain the point then the child gets preference, and if two siblings both contain the point then the highest one in the stacking order (i.e. the one that's visible on the screen) gets preference. .SH KEYWORDS containing, coordinates, root window tk9.0.3/doc/CrtCmHdlr.30000644001000000100000000000503115105057705017521 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2000 Ajuba Solutions. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateClientMessageHandler 3 "8.4" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateClientMessageHandler, Tk_DeleteClientMessageHandler \- associate procedure callback with ClientMessage type X events .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_CreateClientMessageHandler\fR(\fIproc\fR) .sp \fBTk_DeleteClientMessageHandler\fR(\fIproc\fR) .fi .SH ARGUMENTS .AP Tk_ClientMessageProc *proc in Procedure to invoke whenever a ClientMessage X event occurs on any display. .BE .SH DESCRIPTION .PP \fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked in the future whenever a ClientMessage X event occurs that is not handled by \fBWM_PROTOCOL\fR. \fBTk_CreateClientMessageHandler\fR is intended for use by applications which need to watch X ClientMessage events, such as drag and drop applications. .PP The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; this mechanism only works in programs that dispatch events through \fBTk_HandleEvent\fR (or through other Tk procedures that call \fBTk_HandleEvent\fR, such as \fBTcl_DoOneEvent\fR or \fBTk_MainLoop\fR). .PP \fIProc\fR should have arguments and result that match the type \fBTk_ClientMessageProc\fR: .CS typedef int \fBTk_ClientMessageProc\fR( Tk_Window \fItkwin\fR, XEvent *\fIeventPtr\fR); .CE The \fItkwin\fR parameter to \fIproc\fR is the Tk window which is associated with this event. \fIEventPtr\fR is a pointer to the X event. .PP Whenever an X ClientMessage event is processed by \fBTk_HandleEvent\fR, the \fIproc\fR is called if it was not handled as a \fBWM_PROTOCOL\fR. The return value from \fIproc\fR is normally 0. A non-zero return value indicates that the event is not to be handled further; that is, \fIproc\fR has done all processing that is to be allowed for the event. .PP If there are multiple ClientMessage event handlers, each one is called for each event, in the order in which they were established. .PP \fBTk_DeleteClientMessageHandler\fR may be called to delete a previously-created ClientMessage event handler: it deletes each handler it finds that matches the \fIproc\fR argument. If no such handler exists, then \fBTk_DeleteClientMessageHandler\fR returns without doing anything. Although Tk supports it, it's probably a bad idea to have more than one callback with the same \fIproc\fR argument. .SH KEYWORDS bind, callback, event, handler tk9.0.3/doc/CrtConsoleChan.30000644001000000100000000000274215105057705020552 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2007 ActiveState Software Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_InitConsoleChannels 3 8.5 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_InitConsoleChannels \- Install the console channels as standard channels .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_InitConsoleChannels\fR(\fIinterp\fR) .fi .SH ARGUMENTS .AS Tcl_Interp *interp in .AP Tcl_Interp *interp in Interpreter in which the console channels are created. .BE .SH DESCRIPTION .PP \fBTk_InitConsoleChannels\fR is invoked to create a set of console channels and install them as the standard channels. All I/O on these channels will be discarded until \fBTk_CreateConsoleWindow\fR is called to attach the console to a text widget. .PP This function is for use by shell applications based on Tk, like \fBwish\fR, on platforms which have no standard channels in graphical mode, like Win32. .PP The \fIinterp\fR argument is the interpreter in which to create and install the console channels. .PP \fBNOTE:\fR If this function is used it has to be called before the first call to \fBTcl_RegisterChannel\fR, directly, or indirectly through other channel functions. Because otherwise the standard channels will be already initialized to the system defaults, which will be nonsensical for the case \fBTk_InitConsoleChannels\fR is for. .SH "SEE ALSO" console(n) .SH KEYWORDS standard channels, console tk9.0.3/doc/CrtErrHdlr.30000644001000000100000000001413415105057705017716 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateErrorHandler 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateErrorHandler, Tk_DeleteErrorHandler \- handle X protocol errors .SH SYNOPSIS .nf \fB#include \fR .sp Tk_ErrorHandler \fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR) .sp \fBTk_DeleteErrorHandler\fR(\fIhandler\fR) .fi .SH ARGUMENTS .AS "Tk_ErrorHandler" clientData .AP Display *display in Display whose errors are to be handled. .AP int error in Match only error events with this value in the \fIerror_code\fR field. If \-1, then match any \fIerror_code\fR value. .AP int request in Match only error events with this value in the \fIrequest_code\fR field. If \-1, then match any \fIrequest_code\fR value. .AP int minor in Match only error events with this value in the \fIminor_code\fR field. If \-1, then match any \fIminor_code\fR value. .AP Tk_ErrorProc *proc in Procedure to invoke whenever an error event is received for \fIdisplay\fR and matches \fIerror\fR, \fIrequest\fR, and \fIminor\fR. NULL means ignore any matching errors. .AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .AP Tk_ErrorHandler handler in Token for error handler to delete (return value from a previous call to \fBTk_CreateErrorHandler\fR). .BE .SH DESCRIPTION .PP \fBTk_CreateErrorHandler\fR arranges for a particular procedure (\fIproc\fR) to be called whenever certain protocol errors occur on a particular display (\fIdisplay\fR). Protocol errors occur when the X protocol is used incorrectly, such as attempting to map a window that does not exist. See the Xlib documentation for \fBXSetErrorHandler\fR for more information on the kinds of errors that can occur. For \fIproc\fR to be invoked to handle a particular error, five things must occur: .IP [1] The error must pertain to \fIdisplay\fR. .IP [2] Either the \fIerror\fR argument to \fBTk_CreateErrorHandler\fR must have been \-1, or the \fIerror\fR argument must match the \fIerror_code\fR field from the error event. .IP [3] Either the \fIrequest\fR argument to \fBTk_CreateErrorHandler\fR must have been \-1, or the \fIrequest\fR argument must match the \fIrequest_code\fR field from the error event. .IP [4] Either the \fIminor\fR argument to \fBTk_CreateErrorHandler\fR must have been \-1, or the \fIminor\fR argument must match the \fIminor_code\fR field from the error event. .IP [5] The protocol request to which the error pertains must have been made when the handler was active (see below for more information). .PP \fIProc\fR should have arguments and result that match the following type: .CS typedef int \fBTk_ErrorProc\fR( void *\fIclientData\fR, XErrorEvent *\fIerrEventPtr\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTcl_CreateErrorHandler\fR when the callback was created. Typically, \fIclientData\fR points to a data structure containing application-specific information that is needed to deal with the error. \fIErrEventPtr\fR is a pointer to the X error event. The procedure \fIproc\fR should return an integer value. If it returns 0 it means that \fIproc\fR handled the error completely and there is no need to take any other action for the error. If it returns non-zero it means \fIproc\fR was unable to handle the error. .PP If a value of NULL is specified for \fIproc\fR, all matching errors will be ignored: this will produce the same result as if a procedure had been specified that always returns 0. .PP If more than more than one handler matches a particular error, then they are invoked in turn. The handlers will be invoked in reverse order of creation: most recently declared handler first. If any handler returns 0, then subsequent (older) handlers will not be invoked. If no handler returns 0, then Tk invokes X's default error handler, which prints an error message and aborts the program. If you wish to have a default handler that deals with errors that no other handler can deal with, then declare it first. .PP The X documentation states that .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." This restriction applies to handlers declared by \fBTk_CreateErrorHandler\fR; disobey it at your own risk. .PP \fBTk_DeleteErrorHandler\fR may be called to delete a previously-created error handler. The \fIhandler\fR argument identifies the error handler, and should be a value returned by a previous call to \fBTk_CreateEventHandler\fR. .PP A particular error handler applies to errors resulting from protocol requests generated between the call to \fBTk_CreateErrorHandler\fR and the call to \fBTk_DeleteErrorHandler\fR. However, the actual callback to \fIproc\fR may not occur until after the \fBTk_DeleteErrorHandler\fR call, due to buffering in the client and server. If an error event pertains to a protocol request made just before calling \fBTk_DeleteErrorHandler\fR, then the error event may not have been processed before the \fBTk_DeleteErrorHandler\fR call. When this situation arises, Tk will save information about the handler and invoke the handler's \fIproc\fR later when the error event finally arrives. If an application wishes to delete an error handler and know for certain that all relevant errors have been processed, it should first call \fBTk_DeleteErrorHandler\fR and then call \fBXSync\fR; this will flush out any buffered requests and errors, but will result in a performance penalty because it requires communication to and from the X server. After the \fBXSync\fR call Tk is guaranteed not to call any error handlers deleted before the \fBXSync\fR call. .PP For the Tk error handling mechanism to work properly, it is essential that application code never calls \fBXSetErrorHandler\fR directly; applications should use only \fBTk_CreateErrorHandler\fR. .SH KEYWORDS callback, error, event, handler tk9.0.3/doc/CrtGenHdlr.30000644001000000100000000000636315105057705017704 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateGenericHandler 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateGenericHandler, Tk_DeleteGenericHandler \- associate procedure callback with all X events .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_CreateGenericHandler\fR(\fIproc, clientData\fR) .sp \fBTk_DeleteGenericHandler\fR(\fIproc, clientData\fR) .fi .SH ARGUMENTS .AS "Tk_GenericProc" clientData .AP Tk_GenericProc *proc in Procedure to invoke whenever any X event occurs on any display. .AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION .PP \fBTk_CreateGenericHandler\fR arranges for \fIproc\fR to be invoked in the future whenever any X event occurs. This mechanism is \fInot\fR intended for dispatching X events on windows managed by Tk (you should use \fBTk_CreateEventHandler\fR for this purpose). \fBTk_CreateGenericHandler\fR is intended for other purposes, such as tracing X events, monitoring events on windows not owned by Tk, accessing X-related libraries that were not originally designed for use with Tk, and so on. .PP The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; this mechanism only works in programs that dispatch events through \fBTk_HandleEvent\fR (or through other Tk procedures that call \fBTk_HandleEvent\fR, such as \fBTcl_DoOneEvent\fR or \fBTk_MainLoop\fR). .PP \fIProc\fR should have arguments and result that match the type \fBTk_GenericProc\fR: .CS typedef int \fBTk_GenericProc\fR( void *\fIclientData\fR, XEvent *\fIeventPtr\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTk_CreateGenericHandler\fR when the callback was created. Typically, \fIclientData\fR points to a data structure containing application-specific information about how to handle events. \fIEventPtr\fR is a pointer to the X event. .PP Whenever an X event is processed by \fBTk_HandleEvent\fR, \fIproc\fR is called. The return value from \fIproc\fR is normally 0. A non-zero return value indicates that the event is not to be handled further; that is, \fIproc\fR has done all processing that is to be allowed for the event. .PP If there are multiple generic event handlers, each one is called for each event, in the order in which they were established. .PP \fBTk_DeleteGenericHandler\fR may be called to delete a previously-created generic event handler: it deletes each handler it finds that matches the \fIproc\fR and \fIclientData\fR arguments. If no such handler exists, then \fBTk_DeleteGenericHandler\fR returns without doing anything. Although Tk supports it, it's probably a bad idea to have more than one callback with the same \fIproc\fR and \fIclientData\fR arguments. .PP Establishing a generic event handler does nothing to ensure that the process will actually receive the X events that the handler wants to process. For example, it is the caller's responsibility to invoke \fBXSelectInput\fR to select the desired events, if that is necessary. .SH KEYWORDS bind, callback, event, handler tk9.0.3/doc/CrtImgType.30000644001000000100000000002347215105057705017737 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateImageType, Tk_GetImageModelData \- define new kind of image .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_CreateImageType\fR(\fItypePtr\fR) .sp void * \fBTk_GetImageModelData\fR(\fIinterp, name, typePtrPtr\fR) .fi .SH ARGUMENTS .AS "const Tk_ImageType" *typePtrPtr .AP "const Tk_ImageType" *typePtr in Structure that defines the new type of image. For Tk 8.4 and earlier this must be static: a pointer to this structure is retained by the image code. In Tk 8.5, this limitation was relaxed. .AP Tcl_Interp *interp in Interpreter in which image was created. .AP "const char" *name in Name of existing image. .AP Tk_ImageType **typePtrPtr out Points to word in which to store a pointer to type information for the given image, if it exists. .AP char ***argvPtr in/out Pointer to argument list .BE .SH DESCRIPTION .PP \fBTk_CreateImageType\fR is invoked to define a new kind of image. An image type corresponds to a particular value of the \fItype\fR argument for the \fBimage create\fR command. There may exist any number of different image types, and new types may be defined dynamically by calling \fBTk_CreateImageType\fR. For example, there might be one type for 2-color bitmaps, another for multi-color images, another for dithered images, another for video, and so on. .PP The code that implements a new image type is called an \fIimage manager\fR. It consists of a collection of procedures plus three different kinds of data structures. The first data structure is a Tk_ImageType structure, which contains the name of the image type and pointers to five procedures provided by the image manager to deal with images of this type: .CS typedef struct { const char *\fIname\fR; Tk_ImageCreateProc *\fIcreateProc\fR; Tk_ImageGetProc *\fIgetProc\fR; Tk_ImageDisplayProc *\fIdisplayProc\fR; Tk_ImageFreeProc *\fIfreeProc\fR; Tk_ImageDeleteProc *\fIdeleteProc\fR; } \fBTk_ImageType\fR; .CE The fields of this structure will be described in later subsections of this entry. .PP The second major data structure manipulated by an image manager is called an \fIimage model\fR; it contains overall information about a particular image, such as the values of the configuration options specified in an \fBimage create\fR command. There will usually be one of these structures for each invocation of the \fBimage create\fR command. .PP The third data structure related to images is an \fIimage instance\fR. There will usually be one of these structures for each usage of an image in a particular widget. It is possible for a single image to appear simultaneously in multiple widgets, or even multiple times in the same widget. Furthermore, different instances may be on different screens or displays. The image instance data structure describes things that may vary from instance to instance, such as colors and graphics contexts for redisplay. There is usually one instance structure for each \fB\-image\fR option specified for a widget or canvas item. .PP The following subsections describe the fields of a Tk_ImageType in more detail. .SS NAME .PP \fItypePtr->name\fR provides a name for the image type. Once \fBTk_CreateImageType\fR returns, this name may be used in \fBimage create\fR commands to create images of the new type. If there already existed an image type by this name then the new image type replaces the old one. .SS CREATEPROC .PP \fItypePtr->createProc\fR provides the address of a procedure for Tk to call whenever \fBimage create\fR is invoked to create an image of the new type. \fItypePtr->createProc\fR must match the following prototype: .CS typedef int \fBTk_ImageCreateProc\fR( Tcl_Interp *\fIinterp\fR, const char *\fIname\fR, int \fIobjc\fR, Tcl_Obj *const \fIobjv\fR[], const Tk_ImageType *\fItypePtr\fR, Tk_ImageModel \fImodel\fR, void **\fImodelDataPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the \fBimage\fR command was invoked, and \fIname\fR is the name for the new image, which was either specified explicitly in the \fBimage\fR command or generated automatically by the \fBimage\fR command. The \fIobjc\fR and \fIobjv\fR arguments describe all the configuration options for the new image (everything after the name argument to \fBimage\fR). The \fImodel\fR argument is a token that refers to Tk's information about this image; the image manager must return this token to Tk when invoking the \fBTk_ImageChanged\fR procedure. Typically \fIcreateProc\fR will parse \fIobjc\fR and \fIobjv\fR and create an image model data structure for the new image. \fIcreateProc\fR may store an arbitrary one-word value at *\fImodelDataPtr\fR, which will be passed back to the image manager when other callbacks are invoked. Typically the value is a pointer to the model data structure for the image. .PP If \fIcreateProc\fR encounters an error, it should leave an error message in the interpreter result and return \fBTCL_ERROR\fR; otherwise it should return \fBTCL_OK\fR. .PP \fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the size of the image and request an initial redisplay. .SS GETPROC .PP \fItypePtr->getProc\fR is invoked by Tk whenever a widget calls \fBTk_GetImage\fR to use a particular image. This procedure must match the following prototype: .CS typedef void *\fBTk_ImageGetProc\fR( Tk_Window \fItkwin\fR, void *\fImodelData\fR); .CE The \fItkwin\fR argument identifies the window in which the image will be used and \fImodelData\fR is the value returned by \fIcreateProc\fR when the image model was created. \fIgetProc\fR will usually create a data structure for the new instance, including such things as the resources needed to display the image in the given window. \fIgetProc\fR returns a one-word token for the instance, which is typically the address of the instance data structure. Tk will pass this value back to the image manager when invoking its \fIdisplayProc\fR and \fIfreeProc\fR procedures. .SS DISPLAYPROC .PP \fItypePtr->displayProc\fR is invoked by Tk whenever an image needs to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR). \fIdisplayProc\fR must match the following prototype: .CS typedef void \fBTk_ImageDisplayProc\fR( void *\fIinstanceData\fR, Display *\fIdisplay\fR, Drawable \fIdrawable\fR, int \fIimageX\fR, int \fIimageY\fR, int \fIwidth\fR, int \fIheight\fR, int \fIdrawableX\fR, int \fIdrawableY\fR); .CE The \fIinstanceData\fR will be the same as the value returned by \fIgetProc\fR when the instance was created. \fIdisplay\fR and \fIdrawable\fR indicate where to display the image; \fIdrawable\fR may be a pixmap rather than the window specified to \fIgetProc\fR (this is usually the case, since most widgets double-buffer their redisplay to get smoother visual effects). \fIimageX\fR, \fIimageY\fR, \fIwidth\fR, and \fIheight\fR identify the region of the image that must be redisplayed. This region will always be within the size of the image as specified in the most recent call to \fBTk_ImageChanged\fR. \fIdrawableX\fR and \fIdrawableY\fR indicate where in \fIdrawable\fR the image should be displayed; \fIdisplayProc\fR should display the given region of the image so that point (\fIimageX\fR, \fIimageY\fR) in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR. .SS FREEPROC .PP \fItypePtr->freeProc\fR contains the address of a procedure that Tk will invoke when an image instance is released (i.e., when \fBTk_FreeImage\fR is invoked). This can happen, for example, when a widget is deleted or a image item in a canvas is deleted, or when the image displayed in a widget or canvas item is changed. \fIfreeProc\fR must match the following prototype: .CS typedef void \fBTk_ImageFreeProc\fR( void *\fIinstanceData\fR, Display *\fIdisplay\fR); .CE The \fIinstanceData\fR will be the same as the value returned by \fIgetProc\fR when the instance was created, and \fIdisplay\fR is the display containing the window for the instance. \fIfreeProc\fR should release any resources associated with the image instance, since the instance will never be used again. .SS DELETEPROC .PP \fItypePtr->deleteProc\fR is a procedure that Tk invokes when an image is being deleted (i.e. when the \fBimage delete\fR command is invoked). Before invoking \fIdeleteProc\fR Tk will invoke \fIfreeProc\fR for each of the image's instances. \fIdeleteProc\fR must match the following prototype: .CS typedef void \fBTk_ImageDeleteProc\fR( void *\fImodelData\fR); .CE The \fImodelData\fR argument will be the same as the value stored in \fI*modelDataPtr\fR by \fIcreateProc\fR when the image was created. \fIdeleteProc\fR should release any resources associated with the image. .SH TK_GETIMAGEMODELDATA .PP The procedure \fBTk_GetImageModelData\fR may be invoked to retrieve information about an image. For example, an image manager can use this procedure to locate its image model data for an image. If there exists an image named \fIname\fR in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is filled in with type information for the image (the \fItypePtr\fR value passed to \fBTk_CreateImageType\fR when the image type was registered) and the return value is the clientData value returned by the \fIcreateProc\fR when the image was created (this is typically a pointer to the image model data structure). If no such image exists then NULL is returned and NULL is stored at \fI*typePtrPtr\fR. .SH "SEE ALSO" Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage .SH KEYWORDS image manager, image type, instance, model tk9.0.3/doc/CrtItemType.30000644001000000100000000006610515105057705020121 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994-1995 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_CreateItemType\fR(\fItypePtr\fR) .sp Tk_ItemType * \fBTk_GetItemTypes\fR() .fi .SH ARGUMENTS .AS Tk_ItemType *typePtr .AP Tk_ItemType *typePtr in Structure that defines the new type of canvas item. Note that this is not \fIconst\fR; Tk may write to these structures. .BE .SH INTRODUCTION .PP \fBTk_CreateItemType\fR is invoked to define a new kind of canvas item described by the \fItypePtr\fR argument. An item type corresponds to a particular value of the \fItype\fR argument to the \fBcreate\fR widget command for canvases, and the code that implements a canvas item type is called a \fItype manager\fR. Tk defines several built-in item types, such as \fBrectangle\fR and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR allows additional item types to be defined. Once \fBTk_CreateItemType\fR returns, the new item type may be used in new or existing canvas widgets just like the built-in item types. .PP \fBTk_GetItemTypes\fR returns a pointer to the first in the list of all item types currently defined for canvases. The entries in the list are linked together through their \fInextPtr\fR fields, with the end of the list marked by a NULL \fInextPtr\fR. .PP You may find it easier to understand the rest of this manual entry by looking at the code for an existing canvas item type such as bitmap (in the file tkCanvBmap.c) or text (tkCanvText.c). The easiest way to create a new type manager is to copy the code for an existing type and modify it for the new type. .PP Tk provides a number of utility procedures for the use of canvas type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR; these are described in separate manual entries. .SH "DATA STRUCTURES" .PP A type manager consists of a collection of procedures that provide a standard set of operations on items of that type. The type manager deals with three kinds of data structures. The first data structure is a Tk_ItemType; it contains information such as the name of the type and pointers to the standard procedures implemented by the type manager: .PP .CS typedef struct Tk_ItemType { const char *\fIname\fR; Tcl_Size \fIitemSize\fR; Tk_ItemCreateProc *\fIcreateProc\fR; const Tk_ConfigSpec *\fIconfigSpecs\fR; Tk_ItemConfigureProc *\fIconfigProc\fR; Tk_ItemCoordProc *\fIcoordProc\fR; Tk_ItemDeleteProc *\fIdeleteProc\fR; Tk_ItemDisplayProc *\fIdisplayProc\fR; int \fIflags\fR; Tk_ItemPointProc *\fIpointProc\fR; Tk_ItemAreaProc *\fIareaProc\fR; Tk_ItemPostscriptProc *\fIpostscriptProc\fR; Tk_ItemScaleProc *\fIscaleProc\fR; Tk_ItemTranslateProc *\fItranslateProc\fR; Tk_ItemIndexProc *\fIindexProc\fR; Tk_ItemCursorProc *\fIicursorProc\fR; Tk_ItemSelectionProc *\fIselectionProc\fR; Tk_ItemInsertProc *\fIinsertProc\fR; Tk_ItemDCharsProc *\fIdCharsProc\fR; struct Tk_ItemType *\fInextPtr\fR; .VS "9.0, TIP164" Tk_ItemRotateProc *\fIrotateProc\fR; .VE "9.0, TIP164" } \fBTk_ItemType\fR; .CE .PP The fields of a Tk_ItemType structure are described in more detail later in this manual entry. When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR argument must point to a structure with all of the fields initialized except \fInextPtr\fR, which Tk sets to link all the types together into a list. The structure must be in permanent memory (either statically allocated or dynamically allocated but never freed); Tk retains a pointer to this structure. .PP The second data structure manipulated by a type manager is an \fIitem record\fR. For each item in a canvas there exists one item record. All of the items of a given type generally have item records with the same structure, but different types usually have different formats for their item records. The first part of each item record is a header with a standard structure defined by Tk via the type Tk_Item; the rest of the item record is defined by the type manager. A type manager must define its item records with a Tk_Item as the first field. For example, the item record for bitmap items is defined as follows: .PP .CS typedef struct { Tk_Item \fIheader\fR; double \fIx\fR, \fIy\fR; Tk_Anchor \fIanchor\fR; Pixmap \fIbitmap\fR; XColor *\fIfgColor\fR; XColor *\fIbgColor\fR; GC \fIgc\fR; } \fBBitmapItem\fR; .CE .PP The \fIheader\fR substructure contains information used by Tk to manage the item, such as its identifier, its tags, its type, and its bounding box. The fields starting with \fIx\fR belong to the type manager: Tk will never read or write them. The type manager should not need to read or write any of the fields in the header except for four fields whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. These fields give a bounding box for the items using integer canvas coordinates: the item should not cover any pixels with x-coordinate lower than \fIx1\fR or y-coordinate lower than \fIy1\fR, nor should it cover any pixels with x-coordinate greater than or equal to \fIx2\fR or y-coordinate greater than or equal to \fIy2\fR. It is up to the type manager to keep the bounding box up to date as the item is moved and reconfigured. .PP Whenever Tk calls a procedure in a type manager it passes in a pointer to an item record. The argument is always passed as a pointer to a Tk_Item; the type manager will typically cast this into a pointer to its own specific type, such as BitmapItem. .PP The third data structure used by type managers has type Tk_Canvas; it serves as an opaque handle for the canvas widget as a whole. Type managers need not know anything about the contents of this structure. A Tk_Canvas handle is typically passed in to the procedures of a type manager, and the type manager can pass the handle back to library procedures such as Tk_CanvasTkwin to fetch information about the canvas. .SH "TK_ITEMTYPE FIELDS" .SS NAME .PP This section and the ones that follow describe each of the fields in a Tk_ItemType structure in detail. The \fIname\fR field provides a string name for the item type. Once \fBTk_CreateImageType\fR returns, this name may be used in \fBcreate\fR widget commands to create items of the new type. If there already existed an item type by this name then the new item type replaces the old one. .SS "FLAGS (IN ALWAYSREDRAW)" .PP The \fItypePtr\->flags\fR field contains a collection of flag bits that modify how the canvas core interacts with the item. The following bits are defined: .TP \fBTK_ALWAYS_REDRAW\fR . Indicates that the item should always be redrawn when any part of the canvas is redrawn, rather than only when the bounding box of the item overlaps the area being redrawn. This is used by window items, for example, which need to unmap subwindows that are not on the screen. .TP \fBTK_MOVABLE_POINTS\fR .VS 8.6 Indicates that the item supports the \fIdCharsProc\fR, \fIindexProc\fR and \fIinsertProc\fR with the same semantics as Tk's built-in line and polygon types, and that hence individual coordinate points can be moved. Must not be set if any of the above methods is NULL. .VE 8.6 .SS ITEMSIZE .PP \fItypePtr\->itemSize\fR gives the size in bytes of item records of this type, including the Tk_Item header. Tk uses this size to allocate memory space for items of the type. All of the item records for a given type must have the same size. If variable length fields are needed for an item (such as a list of points for a polygon), the type manager can allocate a separate object of variable length and keep a pointer to it in the item record. .SS CREATEPROC .PP \fItypePtr\->createProc\fR points to a procedure for Tk to call whenever a new item of this type is created. \fItypePtr\->createProc\fR must match the following prototype: .PP .CS typedef int \fBTk_ItemCreateProc\fR( Tcl_Interp *\fIinterp\fR, Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, int \fIobjc\fR, Tcl_Obj *const \fIobjv\fR[]); .CE .PP The \fIinterp\fR argument is the interpreter in which the canvas's \fBcreate\fR widget command was invoked, and \fIcanvas\fR is a handle for the canvas widget. \fIitemPtr\fR is a pointer to a newly-allocated item of size \fItypePtr\->itemSize\fR. Tk has already initialized the item's header (the first \fBsizeof(Tk_ItemType)\fR bytes). The \fIobjc\fR and \fIobjv\fR arguments describe all of the arguments to the \fBcreate\fR command after the \fItype\fR argument. For example, in the widget command: .PP .CS \fB\&.c create rectangle 10 20 50 50 \-fill black\fR .CE .PP \fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the integer object \fB10\fR. .PP \fIcreateProc\fR should use \fIobjc\fR and \fIobjv\fR to initialize the type-specific parts of the item record and set an initial value for the bounding box in the item's header. It should return a standard Tcl completion code and leave an error message in the interpreter result if an error occurs. If an error occurs Tk will free the item record, so \fIcreateProc\fR must be sure to leave the item record in a clean state if it returns an error (e.g., it must free any additional memory that it allocated for the item). .SS CONFIGSPECS .PP Each type manager must provide a standard table describing its configuration options, in a form suitable for use with \fBTk_ConfigureWidget\fR. This table will normally be used by \fItypePtr\->createProc\fR and \fItypePtr\->configProc\fR, but Tk also uses it directly to retrieve option information in the \fBitemcget\fR and \fBitemconfigure\fR widget commands. \fItypePtr\->configSpecs\fR must point to the configuration table for this type. .PP Note that Tk provides a custom option type \fBtk_CanvasTagsOption\fR for implementing the \fB\-tags\fR option; see an existing type manager for an example of how to use it in \fIconfigSpecs\fR. .SS CONFIGPROC .PP \fItypePtr\->configProc\fR is called by Tk whenever the \fBitemconfigure\fR widget command is invoked to change the configuration options for a canvas item. This procedure must match the following prototype: .PP .CS typedef int \fBTk_ItemConfigureProc\fR( Tcl_Interp *\fIinterp\fR, Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, int \fIobjc\fR, Tcl_Obj *const \fIobjv\fR[], int \fIflags\fR); .CE .PP The \fIinterp\fR argument identifies the interpreter in which the widget command was invoked, \fIcanvas\fR is a handle for the canvas widget, and \fIitemPtr\fR is a pointer to the item being configured. \fIobjc\fR and \fIobjv\fR contain the configuration options. For example, if the following command is invoked: .PP .CS \fB\&.c itemconfigure 2 \-fill red \-outline black\fR .CE .PP \fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR through \fBblack\fR. \fIobjc\fR will always be an even value. The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR; currently this value is always \fBTK_CONFIG_ARGV_ONLY\fR when Tk invokes \fItypePtr\->configProc\fR, but the type manager's \fIcreateProc\fR procedure will usually invoke \fIconfigProc\fR with different flag values. .PP \fItypePtr\->configProc\fR returns a standard Tcl completion code and leaves an error message in the interpreter result if an error occurs. It must update the item's bounding box to reflect the new configuration options. .SS COORDPROC .PP \fItypePtr\->coordProc\fR is invoked by Tk to implement the \fBcoords\fR widget command for an item. It must match the following prototype: .PP .CS typedef int \fBTk_ItemCoordProc\fR( Tcl_Interp *\fIinterp\fR, Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, int \fIobjc\fR, Tcl_Obj *const \fIobjv\fR[]); .CE .PP The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR all have the standard meanings, and \fIobjc\fR and \fIobjv\fR describe the coordinate arguments. For example, if the following widget command is invoked: .PP .CS \fB\&.c coords 2 30 90\fR .CE .PP \fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects \fB30\fR and \fB90\fR. .PP The \fIcoordProc\fR procedure should process the new coordinates, update the item appropriately (e.g., it must reset the bounding box in the item's header), and return a standard Tcl completion code. If an error occurs, \fIcoordProc\fR must leave an error message in the interpreter result. .SS DELETEPROC .PP \fItypePtr\->deleteProc\fR is invoked by Tk to delete an item and free any resources allocated to it. It must match the following prototype: .PP .CS typedef void \fBTk_ItemDeleteProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, Display *\fIdisplay\fR); .CE .PP The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual interpretations, and \fIdisplay\fR identifies the X display containing the canvas. \fIdeleteProc\fR must free up any resources allocated for the item, so that Tk can free the item record. \fIdeleteProc\fR should not actually free the item record; this will be done by Tk when \fIdeleteProc\fR returns. .SS "DISPLAYPROC" .PP \fItypePtr\->displayProc\fR is invoked by Tk to redraw an item on the screen. It must match the following prototype: .PP .CS typedef void \fBTk_ItemDisplayProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, Display *\fIdisplay\fR, Drawable \fIdst\fR, int \fIx\fR, int \fIy\fR, int \fIwidth\fR, int \fIheight\fR); .CE .PP The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. \fIdisplay\fR identifies the display containing the canvas, and \fIdst\fR specifies a drawable in which the item should be rendered; typically this is an off-screen pixmap, which Tk will copy into the canvas's window once all relevant items have been drawn. \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular region in canvas coordinates, which is the area to be redrawn; only information that overlaps this area needs to be redrawn. Tk will not call \fIdisplayProc\fR unless the item's bounding box overlaps the redraw area, but the type manager may wish to use the redraw area to optimize the redisplay of the item. .PP Because of scrolling and the use of off-screen pixmaps for double-buffered redisplay, the item's coordinates in \fIdst\fR will not necessarily be the same as those in the canvas. \fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR to transform coordinates from those of the canvas to those of \fIdst\fR. .PP Normally an item's \fIdisplayProc\fR is only invoked if the item overlaps the area being displayed. However, if bit zero of \fItypePtr\->flags\fR is 1, (i.e.\| .QW "\fItypePtr\->flags & 1 == 1\fR" ) then \fIdisplayProc\fR is invoked during every redisplay operation, even if the item does not overlap the area of redisplay; this is useful for cases such as window items, where the subwindow needs to be unmapped when it is off the screen. .SS POINTPROC .PP \fItypePtr\->pointProc\fR is invoked by Tk to find out how close a given point is to a canvas item. Tk uses this procedure for purposes such as locating the item under the mouse or finding the closest item to a given point. The procedure must match the following prototype: .PP .CS typedef double \fBTk_ItemPointProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, double *\fIpointPtr\fR); .CE .PP \fIcanvas\fR and \fIitemPtr\fR have the usual meaning. \fIpointPtr\fR points to an array of two numbers giving the x and y coordinates of a point. \fIpointProc\fR must return a real value giving the distance from the point to the item, or 0 if the point lies inside the item. .SS AREAPROC .PP \fItypePtr\->areaProc\fR is invoked by Tk to find out the relationship between an item and a rectangular area. It must match the following prototype: .PP .CS typedef int \fBTk_ItemAreaProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, double *\fIrectPtr\fR); .CE .PP \fIcanvas\fR and \fIitemPtr\fR have the usual meaning. \fIrectPtr\fR points to an array of four real numbers; the first two give the x and y coordinates of the upper left corner of a rectangle, and the second two give the x and y coordinates of the lower right corner. \fIareaProc\fR must return \-1 if the item lies entirely outside the given area, 0 if it lies partially inside and partially outside the area, and 1 if it lies entirely inside the area. .SS POSTSCRIPTPROC .PP \fItypePtr\->postscriptProc\fR is invoked by Tk to generate Postscript for an item during the \fBpostscript\fR widget command. If the type manager is not capable of generating Postscript then \fItypePtr\->postscriptProc\fR should be NULL. The procedure must match the following prototype: .PP .CS typedef int \fBTk_ItemPostscriptProc\fR( Tcl_Interp *\fIinterp\fR, Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, int \fIprepass\fR); .CE .PP The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have standard meanings; \fIprepass\fR will be described below. If \fIpostscriptProc\fR completes successfully, it should append Postscript for the item to the information in the interpreter result (e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR) and return \fBTCL_OK\fR. If an error occurs, \fIpostscriptProc\fR should clear the result and replace its contents with an error message; then it should return \fBTCL_ERROR\fR. .PP Tk provides a collection of utility procedures to simplify \fIpostscriptProc\fR. For example, \fBTk_CanvasPsColor\fR will generate Postscript to set the current color to a given Tk color and \fBTk_CanvasPsFont\fR will set up font information. When generating Postscript, the type manager is free to change the graphics state of the Postscript interpreter, since Tk places \fBgsave\fR and \fBgrestore\fR commands around the Postscript for the item. The type manager can use canvas x coordinates directly in its Postscript, but it must call \fBTk_CanvasPsY\fR to convert y coordinates from the space of the canvas (where the origin is at the upper left) to the space of Postscript (where the origin is at the lower left). .PP In order to generate Postscript that complies with the Adobe Document Structuring Conventions, Tk actually generates Postscript in two passes. It calls each item's \fIpostscriptProc\fR in each pass. The only purpose of the first pass is to collect font information (which is done by \fBTk_CanvasPsFont\fR); the actual Postscript is discarded. Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1 during the first pass; the type manager can use \fIprepass\fR to skip all Postscript generation except for calls to \fBTk_CanvasPsFont\fR. During the second pass \fIprepass\fR will be 0, so the type manager must generate complete Postscript. .SS SCALEPROC .PP \fItypePtr\->scaleProc\fR is invoked by Tk to rescale a canvas item during the \fBscale\fR widget command. The procedure must match the following prototype: .PP .CS typedef void \fBTk_ItemScaleProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, double \fIoriginX\fR, double \fIoriginY\fR, double \fIscaleX\fR, double \fIscaleY\fR); .CE .PP The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. \fIoriginX\fR and \fIoriginY\fR specify an origin relative to which the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the x and y scale factors. The item should adjust its coordinates so that a point in the item that used to have coordinates \fIx\fR and \fIy\fR will have new coordinates \fIx\(fm\fR and \fIy\(fm\fR, where .PP .CS \fIx\(fm\fR = \fIoriginX\fR + \fIscaleX\fR \(mu (\fIx\fR \(mi \fIoriginX\fR) \fIy\(fm\fR = \fIoriginY\fR + \fIscaleY\fR \(mu (\fIy\fR \(mi \fIoriginY\fR) .CE .PP \fIscaleProc\fR must also update the bounding box in the item's header. .SS TRANSLATEPROC .PP \fItypePtr\->translateProc\fR is invoked by Tk to translate a canvas item during the \fBmove\fR widget command. The procedure must match the following prototype: .PP .CS typedef void \fBTk_ItemTranslateProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, double \fIdeltaX\fR, double \fIdeltaY\fR); .CE .PP The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning, and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be added to each x and y coordinate within the item. The type manager should adjust the item's coordinates and update the bounding box in the item's header. .SS ROTATEPROC .VS "9.0, TIP164" .PP \fItypePtr\->rotateProc\fR is invoked by Tk to rotate a canvas item during the \fBrotate\fR widget command. The procedure must match the following prototype: .PP .CS typedef void \fBTk_ItemRotateProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, double \fIoriginX\fR, double \fIoriginY\fR, double \fIangleRad\fR); .CE .PP The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. \fIoriginX\fR and \fIoriginY\fR specify an origin relative to which the item is to be rotated, and \fIangleRad\fR gives the anticlockwise rotation to be applied in radians. The item should adjust the coordinates of its control points so that where they used to have coordinates \fIx\fR and \fIy\fR, they will have new coordinates \fIx\(fm\fR and \fIy\(fm\fR, where .PP .CS \fIrelX\fR = \fIx\fR \(mi \fIoriginX\fR \fIrelY\fR = \fIy\fR \(mi \fIoriginY\fR \fIx\(fm\fR = \fIoriginX\fR + \fIrelX\fR \(mu cos(\fIangleRad\fR) + \fIrelY\fR \(mu sin(\fIangleRad\fR) \fIy\(fm\fR = \fIoriginY\fR \(mi \fIrelX\fR \(mu sin(\fIangleRad\fR) + \fIrelY\fR \(mu cos(\fIangleRad\fR) .CE .PP The control points for an item are not necessarily the coordinates provided to the item when it is created (or via the \fItypePtr\->coordProc\fR), but could instead be derived from them. \fIrotateProc\fR must also update the bounding box in the item's header. .PP Item types do not need to provide a \fItypePtr\->rotateProc\fR. If the \fItypePtr\->rotateProc\fR is NULL, the \fItypePtr\->coordProc\fR will be used instead to retrieve and update the list of coordinates. .VE "9.0, TIP164" .SS INDEXPROC .PP \fItypePtr\->indexProc\fR is invoked by Tk to translate a string index specification into a numerical index, for example during the \fBindex\fR widget command. It is only relevant for item types that support indexable text or coordinates; \fItypePtr\->indexProc\fR may be specified as NULL for non-textual item types if they do not support detailed coordinate addressing. The procedure must match the following prototype: .PP .CS typedef int \fBTk_ItemIndexProc\fR( Tcl_Interp *\fIinterp\fR, Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, Tcl_Obj *\fIindexObj\fR, int *\fIindexPtr\fR); .CE .PP The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have the usual meaning. \fIindexObj\fR contains a textual description of an index, and \fIindexPtr\fR points to an integer value that should be filled in with a numerical index. It is up to the type manager to decide what forms of index are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR, \fBend\fR, etc.). \fIindexProc\fR should return a Tcl completion code and set the interpreter result in the event of an error. .SS ICURSORPROC .PP \fItypePtr\->icursorProc\fR is invoked by Tk during the \fBicursor\fR widget command to set the position of the insertion cursor in a textual item. It is only relevant for item types that support an insertion cursor; \fItypePtr\->icursorProc\fR may be specified as NULL for item types that do not support an insertion cursor. The procedure must match the following prototype: .PP .CS typedef void \fBTk_ItemCursorProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, int \fIindex\fR); .CE .PP \fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and \fIindex\fR is an index into the item's text, as returned by a previous call to \fItypePtr\->insertProc\fR. The type manager should position the insertion cursor in the item just before the character given by \fIindex\fR. Whether or not to actually display the insertion cursor is determined by other information provided by \fBTk_CanvasGetTextInfo\fR. .SS SELECTIONPROC .PP \fItypePtr\->selectionProc\fR is invoked by Tk during selection retrievals; it must return part or all of the selected text in the item (if any). It is only relevant for item types that support text; \fItypePtr\->selectionProc\fR may be specified as NULL for non-textual item types. The procedure must match the following prototype: .PP .CS typedef int \fBTk_ItemSelectionProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, int \fIoffset\fR, char *\fIbuffer\fR, int \fImaxBytes\fR); .CE .PP \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIoffset\fR is an offset in bytes into the selection where 0 refers to the first byte of the selection; it identifies the first character that is to be returned in this call. \fIbuffer\fR points to an area of memory in which to store the requested bytes, and \fImaxBytes\fR specifies the maximum number of bytes to return. \fIselectionProc\fR should extract up to \fImaxBytes\fR characters from the selection and copy them to \fImaxBytes\fR; it should return a count of the number of bytes actually copied, which may be less than \fImaxBytes\fR if there are not \fIoffset+maxBytes\fR bytes in the selection. .SS INSERTPROC .PP \fItypePtr\->insertProc\fR is invoked by Tk during the \fBinsert\fR widget command to insert new text or coordinates into a canvas item. It is only relevant for item types that support the \fBinsert\fR method; \fItypePtr\->insertProc\fR may be specified as NULL for other item types. The procedure must match the following prototype: .PP .CS typedef void \fBTk_ItemInsertProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, int \fIindex\fR, Tcl_Obj *\fIobj\fR); .CE .PP \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIindex\fR is an index into the item's text, as returned by a previous call to \fItypePtr\->insertProc\fR, and \fIobj\fR contains new text to insert just before the character given by \fIindex\fR. If the item supports modification of the coordinates list by this .PP The type manager should insert the text and recompute the bounding box in the item's header. .SS DCHARSPROC .PP \fItypePtr\->dCharsProc\fR is invoked by Tk during the \fBdchars\fR widget command to delete a range of text from a canvas item or a range of coordinates from a pathed item. It is only relevant for item types that support text; \fItypePtr\->dCharsProc\fR may be specified as NULL for non-textual item types that do not want to support coordinate deletion. The procedure must match the following prototype: .PP .CS typedef void \fBTk_ItemDCharsProc\fR( Tk_Canvas \fIcanvas\fR, Tk_Item *\fIitemPtr\fR, int \fIfirst\fR, int \fIlast\fR); .CE .PP \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. \fIfirst\fR and \fIlast\fR give the indices of the first and last bytes to be deleted, as returned by previous calls to \fItypePtr\->indexProc\fR. The type manager should delete the specified characters and update the bounding box in the item's header. .SH "SEE ALSO" Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin .SH KEYWORDS canvas, focus, item type, selection, type manager tk9.0.3/doc/CrtPhImgFmt.30000644001000000100000000004453015105057705020032 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Australian National University '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" Author: Paul Mackerras (paulus@cs.anu.edu.au), '\" Department of Computer Science, '\" Australian National University. '\" .TH Tk_CreatePhotoImageFormat 3 9.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreatePhotoImageFormat \- define new file format for photo images .SH SYNOPSIS .nf \fB#include \fR .sp .VS 9.0 \fBTk_CreatePhotoImageFormatVersion3\fR(\fIformatVersion3Ptr\fR) .VE 9.0 .sp \fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) .SH ARGUMENTS .AS "const Tk_PhotoImageFormatVersion3" *formatVersion3Ptr .VS 9.0 .AP "const Tk_PhotoImageFormatVersion3" *formatVersion3Ptr in Structure that defines the new file format including metadata functionality. .VE 9.0 .AP "const Tk_PhotoImageFormat" *formatPtr in Structure that defines the new file format. .BE .SH DESCRIPTION .PP \fBTk_CreatePhotoImageFormatVersion3\fR is invoked to define a new file format for image data for use with photo images. The code that implements an image file format is called an image file format handler, or handler for short. The photo image code maintains a list of handlers that can be used to read and write data to or from a file. Some handlers may also support reading image data from a string or converting image data to a string format. The user can specify which handler to use with the \fB\-format\fR image configuration option or the \fB\-format\fR option to the \fBread\fR and \fBwrite\fR photo image subcommands. .PP The alternate version 2 function \fBTk_CreatePhotoImageFormat\fR has identical functionality, but does not allow the handler to get or return the metadata dictionary of the image. It is described in section \fBVERSION 2 INTERFACE\fR below. .PP An image file format handler consists of a collection of procedures plus a \fBTk_PhotoImageFormatVersion3\fR structure, which contains the name of the image file format and pointers to six procedures provided by the handler to deal with files and strings in this format. The Tk_PhotoImageFormatVersion3 structure contains the following fields: .VS 9.0 .CS typedef struct { const char *\fIname\fR; Tk_ImageFileMatchProcVersion3 *\fIfileMatchProc\fR; Tk_ImageStringMatchProcVersion3 *\fIstringMatchProc\fR; Tk_ImageFileReadProcVersion3 *\fIfileReadProc\fR; Tk_ImageStringReadProcVersion3 *\fIstringReadProc\fR; Tk_ImageFileWriteProcVersion3 *\fIfileWriteProc\fR; Tk_ImageStringWriteProcVersion3 *\fIstringWriteProc\fR; } \fBTk_PhotoImageFormatVersion3\fR; .CE .VE 9.0 .PP The handler need not provide implementations of all six procedures. For example, the procedures that handle string data would not be provided for a format in which the image data are stored in binary, and could therefore contain null characters. If any procedure is not implemented, the corresponding pointer in the Tk_PhotoImageFormat structure should be set to NULL. The handler must provide the \fIfileMatchProc\fR procedure if it provides the \fIfileReadProc\fR procedure, and the \fIstringMatchProc\fR procedure if it provides the \fIstringReadProc\fR procedure. .SS NAME .PP \fIformatPtr->name\fR provides a name for the image type. Once \fBTk_CreatePhotoImageFormatVersion3\fR returns, this name may be used in the \fB\-format\fR photo image configuration and subcommand option. The manual page for the photo image (photo(n)) describes how image file formats are chosen based on their names and the value given to the \fB\-format\fR option. The first character of \fIformatPtr->name\fR must not be an uppercase character from the ASCII character set (that is, one of the characters \fBA\fR-\fBZ\fR). Such names are used only for legacy interface support (see below). .VS 9.0 .SS FILEMATCHPROC .PP \fIformatPtr->fileMatchProc\fR provides the address of a procedure for Tk to call when it is searching for an image file format handler suitable for reading data in a given file. \fIformatPtr->fileMatchProc\fR must match the following prototype: .CS typedef int \fBTk_ImageFileMatchProcVersion3\fR( Tcl_Interp *\fIinterp\fR, Tcl_Channel \fIchan\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, Tcl_Obj *\fImetadataIn\fR, int *\fIwidthPtr\fR, int *\fIheightPtr\fR, Tcl_Obj *\fImetadataOut\fR); .CE The \fIfileName\fR argument is the name of the file containing the image data, which is open for reading as \fIchan\fR. The \fIformat\fR argument contains the value given for the \fB\-format\fR option, or NULL if the option was not specified. \fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata dictionary as described in section \fBMETADATA INTERFACE\fR below. If the data in the file appears to be in the format supported by this handler, the \fIformatPtr->fileMatchProc\fR procedure should store the width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR respectively, and return 1. Otherwise it should return 0. .SS STRINGMATCHPROC .PP \fIformatPtr->stringMatchProc\fR provides the address of a procedure for Tk to call when it is searching for an image file format handler suitable for reading data from a given string. \fIformatPtr->stringMatchProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringMatchProcVersion3\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIdata\fR, Tcl_Obj *\fIformat\fR, Tcl_Obj *\fImetadataIn\fR, int *\fIwidthPtr\fR, int *\fIheightPtr\fR, Tcl_Obj *\fImetadataOut\fR); .CE The \fIdata\fR argument points to the object containing the image data. The \fIformat\fR argument contains the value given for the \fB\-format\fR option, or NULL if the option was not specified. \fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata dictionary as described in section \fBMETADATA INTERFACE\fR below. If the data in the string appears to be in the format supported by this handler, the \fIformatPtr->stringMatchProc\fR procedure should store the width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR respectively, and return 1. Otherwise it should return 0. .SS FILEREADPROC .PP \fIformatPtr->fileReadProc\fR provides the address of a procedure for Tk to call to read data from an image file into a photo image. \fIformatPtr->fileReadProc\fR must match the following prototype: .CS typedef int \fBTk_ImageFileReadProcVersion3\fR( Tcl_Interp *\fIinterp\fR, Tcl_Channel \fIchan\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, Tcl_Obj *\fImetadataIn\fR, PhotoHandle \fIimageHandle\fR, int \fIdestX\fR, int \fIdestY\fR, int \fIwidth\fR, int \fIheight\fR, int \fIsrcX\fR, int \fIsrcY\fR, Tcl_Obj *\fImetadataOut\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. The image data is in the file named \fIfileName\fR, which is open for reading as \fIchan\fR. The \fIformat\fR argument contains the value given for the \fB\-format\fR option, or NULL if the option was not specified. The image data in the file, or a subimage of it, is to be read into the photo image identified by the handle \fIimageHandle\fR. The subimage of the data in the file is of dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo image with its top-left corner at coordinates (\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. \fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata dictionary as described in section \fBMETADATA INTERFACE\fR below. The return value is a standard Tcl return value. .SS STRINGREADPROC .PP \fIformatPtr->stringReadProc\fR provides the address of a procedure for Tk to call to read data from a string into a photo image. \fIformatPtr->stringReadProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringReadProcVersion3\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIdata\fR, Tcl_Obj *\fIformat\fR, Tcl_Obj *\fImetadataIn\fR, PhotoHandle \fIimageHandle\fR, int \fIdestX\fR, int \fIdestY\fR, int \fIwidth\fR, int \fIheight\fR, int \fIsrcX\fR, int \fIsrcY\fR, Tcl_Obj *\fImetadataOut\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. The \fIdata\fR argument points to the image data in object form. The \fIformat\fR argument contains the value given for the \fB\-format\fR option, or NULL if the option was not specified. The image data in the string, or a subimage of it, is to be read into the photo image identified by the handle \fIimageHandle\fR. The subimage of the data in the string is of dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo image with its top-left corner at coordinates (\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. \fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata dictionary as described in section \fBMETADATA INTERFACE\fR below. The return value is a standard Tcl return value. .SS FILEWRITEPROC .PP \fIformatPtr->fileWriteProc\fR provides the address of a procedure for Tk to call to write data from a photo image to a file. \fIformatPtr->fileWriteProc\fR must match the following prototype: .CS typedef int \fBTk_ImageFileWriteProcVersion3\fR( Tcl_Interp *\fIinterp\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, Tcl_Obj *\fImetadataIn\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to write the image; it should be used for reporting errors. The image data to be written are in memory and are described by the Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the manual page FindPhoto(3) for details. The \fIfileName\fR argument points to the string giving the name of the file in which to write the image data. The \fIformat\fR argument contains the value given for the \fB\-format\fR option, or NULL if the option was not specified. The format string can contain extra characters after the name of the format. If appropriate, the \fIformatPtr->fileWriteProc\fR procedure may interpret these characters to specify further details about the image file. \fBmetadataIn\fR may contain metadata keys that a driver may include into the output data. The return value is a standard Tcl return value. .SS STRINGWRITEPROC .PP \fIformatPtr->stringWriteProc\fR provides the address of a procedure for Tk to call to translate image data from a photo image into a string. \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringWriteProcVersion3\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIformat\fR, Tcl_Obj *\fImetadataIn\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to convert the image; it should be used for reporting errors. The image data to be converted are in memory and are described by the Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the manual page FindPhoto(3) for details. The data for the string should be put in the interpreter \fIinterp\fR result. The \fIformat\fR argument contains the value given for the \fB\-format\fR option, or NULL if the option was not specified. The format string can contain extra characters after the name of the format. If appropriate, the \fIformatPtr->stringWriteProc\fR procedure may interpret these characters to specify further details about the image file. \fBmetadataIn\fR may contain metadata keys that a driver may include into the output data. The return value is a standard Tcl return value. .PP .SH "METADATA INTERFACE" .PP Image formats contain a description of the image bitmap and may contain additional information like image resolution or comments. Image metadata may be read from image files and passed to the script level by including dictionary keys into the metadata property of the image. Image metadata may be written to image data on file write or image data output. .PP .SS "METADATA KEYS" .PP The metadata may contain any key. A driver will handle only a set of dictionary keys documented in the documentation. See the photo image manual page for currently defined keys for the system drivers. .PP The following rules may give guidance to name metadata keys: .IP \(bu Abbreviations are in upper case. .IP \(bu Words are in US English in small case (except proper nouns) .IP \(bu Vertical DPI is expressed as DPI/aspect. The reason is, that some image formats may feature aspect and no resolution value. .SS "METADATA INPUT" .PP Each driver function gets a Tcl object pointer \fBmetadataIn\fR as parameter. This parameter serves to input a metadata dict to the driver function. It may be NULL to flag that the metadata dict is empty. .PP A typical driver code snipped to check for a metadata key is: .CS if (NULL != metadataIn) { Tcl_Obj *itemData; Tcl_DictObjGet(interp, metadataIn, Tcl_NewStringObj("Comment",-1), &itemData)); // use value reference in itemData } .CE .PP The \fB\-metadata\fR command option data of the following commands is passed to the driver: \fBimage create\fR, \fBconfigure\fR, \fBput\fR, \fBread\fR, \fBdata\fR and \fBwrite\fR. If no \fB\-metadata\fR command option available or not given, the metadata property of the image is passed to the driver using the following commands: \fBcget\fR, \fBconfigure\fR, \fBdata\fR and \fBwrite\fR. .PP Note that setting the \fB\-metadata\fR property of an image using \fBconfigure\fR without any other option does not invoke any driver function. .PP The metadata dictionary is not suited to pass options to the driver related to the bitmap representation, as the image bitmap is not recreated on a metadata change. The format string should be used for this purpose. .PP .SS "METADATA OUTPUT" .PP The image match and read driver functions may set keys in a prepared metadata dict to return them. Those functions get a Tcl object pointer \fImetadataOut\fR as parameter. \fImetadataOut\fR may be NULL to indicate, that no metadata return is required (\fBput\fR, \fBread\fR subcommands). The variable pointed to by \fImetadataOut\fR is initialized to an empty unshared dict object if metadata return is attended (\fBimage create\fR command, \fBconfigure\fR subcommand). The driver may set dict keys in this object to return metadata. If a match function succeeds, the metadataOut pointer is passed to the corresponding read function. .PP A sample driver code snippet is: .CS if (NULL != metadataOut) { Tcl_DictObjPut(NULL, metadataOut, Tcl_NewStringObj("XMP",-1), Tcl_NewStringObj(xmpMetadata)); } .CE .PP The metadata keys returned by the driver are merged into the present metadata property of the image or into the metadata dict given by the \fB\-metadata\fR command line option. At the script level, the command \fBimage create\fR and the \fBconfigure\fR method may return metadata from the driver. .PP Format string options or metadata keys may influence the creation of metadata within the driver. For example, the creation of an expensive metadata key may depend on a format string option or on a metadata input key. .PP .VE 9.0 .SH "VERSION 2 INTERFACE" .PP Version 2 Interface does not include the possibility for the driver to use the metadata dict for input or output. .SS SYNOPSIS \fB#include \fR .sp \fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) .SS ARGUMENTS .AS "const Tk_PhotoImageFormat" *formatPtr .AP "const Tk_PhotoImageFormat" *formatPtr in Structure that defines the new file format. .BE .SS DESCRIPTION A driver using the version 2 interface invokes \fBTk_CreatePhotoImageFormat\fR for driver registration. The Tk_PhotoImageFormat structure contains the following fields: .CS typedef struct { const char *\fIname\fR; Tk_ImageFileMatchProc *\fIfileMatchProc\fR; Tk_ImageStringMatchProc *\fIstringMatchProc\fR; Tk_ImageFileReadProc *\fIfileReadProc\fR; Tk_ImageStringReadProc *\fIstringReadProc\fR; Tk_ImageFileWriteProc *\fIfileWriteProc\fR; Tk_ImageStringWriteProc *\fIstringWriteProc\fR; } \fBTk_PhotoImageFormat\fR; .CE .PP .SS FILEMATCHPROC .PP \fIformatPtr->fileMatchProc\fR must match the following prototype: .CS typedef int \fBTk_ImageFileMatchProc\fR( Tcl_Channel \fIchan\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, int *\fIwidthPtr\fR, int *\fIheightPtr\fR, Tcl_Interp *\fIinterp\fR); .CE .PP .SS STRINGMATCHPROC .PP \fIformatPtr->stringMatchProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringMatchProc\fR( Tcl_Obj *\fIdata\fR, Tcl_Obj *\fIformat\fR, int *\fIwidthPtr\fR, int *\fIheightPtr\fR, Tcl_Interp *\fIinterp\fR); .CE .SS FILEREADPROC .PP \fIformatPtr->fileReadProc\fR must match the following prototype: .CS typedef int \fBTk_ImageFileReadProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Channel \fIchan\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, PhotoHandle \fIimageHandle\fR, int \fIdestX\fR, int \fIdestY\fR, int \fIwidth\fR, int \fIheight\fR, int \fIsrcX\fR, int \fIsrcY\fR); .CE .SS STRINGREADPROC .PP \fIformatPtr->stringReadProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringReadProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIdata\fR, Tcl_Obj *\fIformat\fR, PhotoHandle \fIimageHandle\fR, int \fIdestX\fR, int \fIdestY\fR, int \fIwidth\fR, int \fIheight\fR, int \fIsrcX\fR, int \fIsrcY\fR); .CE .SS FILEWRITEPROC .PP \fIformatPtr->fileWriteProc\fR must match the following prototype: .CS typedef int \fBTk_ImageFileWriteProc\fR( Tcl_Interp *\fIinterp\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE .SS STRINGWRITEPROC .PP \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringWriteProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIformat\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE .SH "SEE ALSO" Tk_FindPhoto, Tk_PhotoPutBlock .SH KEYWORDS photo image, image file tk9.0.3/doc/CrtSelHdlr.30000644001000000100000000001213715105057705017712 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateSelHandler 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateSelHandler, Tk_DeleteSelHandler \- arrange to handle requests for a selection .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR) .sp \fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR) .fi .SH ARGUMENTS .AS Tk_SelectionProc clientData .AP Tk_Window tkwin in Window for which \fIproc\fR will provide selection information. .AP Atom selection in The name of the selection for which \fIproc\fR will provide selection information. .AP Atom target in Form in which \fIproc\fR can provide the selection (e.g. STRING or FILE_NAME). Corresponds to \fItype\fR arguments in \fBselection\fR commands. .AP Tk_SelectionProc *proc in Procedure to invoke whenever the selection is owned by \fItkwin\fR and the selection contents are requested in the format given by \fItarget\fR. .AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .AP Atom format in If the selection requestor is not in this process, \fIformat\fR determines the representation used to transmit the selection to its requestor. .BE .SH DESCRIPTION .PP \fBTk_CreateSelHandler\fR arranges for a particular procedure (\fIproc\fR) to be called whenever \fIselection\fR is owned by \fItkwin\fR and the selection contents are requested in the form given by \fItarget\fR. \fITarget\fR should be one of the entries defined in the left column of Table 2 of the X Inter-Client Communication Conventions Manual (ICCCM) or any other form in which an application is willing to present the selection. The most common form is STRING. .PP \fIProc\fR should have arguments and result that match the type \fBTk_SelectionProc\fR: .CS typedef Tcl_Size \fBTk_SelectionProc\fR( void *\fIclientData\fR, Tcl_Size \fIoffset\fR, char *\fIbuffer\fR, Tcl_Size \fImaxBytes\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTk_CreateSelHandler\fR. Typically, \fIclientData\fR points to a data structure containing application-specific information that is needed to retrieve the selection. \fIOffset\fR specifies an offset position into the selection, \fIbuffer\fR specifies a location at which to copy information about the selection, and \fImaxBytes\fR specifies the amount of space available at \fIbuffer\fR. \fIProc\fR should place a NULL-terminated string at \fIbuffer\fR containing \fImaxBytes\fR or fewer characters (not including the terminating NULL), and it should return a count of the number of non-NULL characters stored at \fIbuffer\fR. If the selection no longer exists (e.g. it once existed but the user deleted the range of characters containing it), then \fIproc\fR should return \-1. .PP When transferring large selections, Tk will break them up into smaller pieces (typically a few thousand bytes each) for more efficient transmission. It will do this by calling \fIproc\fR one or more times, using successively higher values of \fIoffset\fR to retrieve successive portions of the selection. If \fIproc\fR returns a count less than \fImaxBytes\fR it means that the entire remainder of the selection has been returned. If \fIproc\fR's return value is \fImaxBytes\fR it means there may be additional information in the selection, so Tk must make another call to \fIproc\fR to retrieve the next portion. .PP \fIProc\fR always returns selection information in the form of a character string. However, the ICCCM allows for information to be transmitted from the selection owner to the selection requestor in any of several formats, such as a string, an array of atoms, an array of integers, etc. The \fIformat\fR argument to \fBTk_CreateSelHandler\fR indicates what format should be used to transmit the selection to its requestor (see the middle column of Table 2 of the ICCCM for examples). If \fIformat\fR is not STRING, then Tk will take the value returned by \fIproc\fR and divided it into fields separated by white space. If \fIformat\fR is ATOM, then Tk will return the selection as an array of atoms, with each field in \fIproc\fR's result treated as the name of one atom. For any other value of \fIformat\fR, Tk will return the selection as an array of 32-bit values where each field of \fIproc\fR's result is treated as a number and translated to a 32-bit value. In any event, the \fIformat\fR atom is returned to the selection requestor along with the contents of the selection. .PP If \fBTk_CreateSelHandler\fR is called when there already exists a handler for \fIselection\fR and \fItarget\fR on \fItkwin\fR, then the existing handler is replaced with a new one. .PP \fBTk_DeleteSelHandler\fR removes the handler given by \fItkwin\fR, \fIselection\fR, and \fItarget\fR, if such a handler exists. If there is no such handler then it has no effect. .SH KEYWORDS format, handler, selection, target tk9.0.3/doc/CrtWindow.30000644001000000100000000001456215105057705017630 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \- create or delete window .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Window \fBTk_CreateWindow\fR(\fIinterp, parent, name, topLevScreen\fR) .sp Tk_Window \fBTk_CreateAnonymousWindow\fR(\fIinterp, parent, topLevScreen\fR) .sp Tk_Window \fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR) .sp \fBTk_DestroyWindow\fR(\fItkwin\fR) .sp \fBTk_MakeWindowExist\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tcl_Interp *topLevScreen .AP Tcl_Interp *interp out Tcl interpreter to use for error reporting. If no error occurs, then \fI*interp\fR is not modified. .AP Tk_Window parent in Token for the window that is to serve as the logical parent of the new window. .AP "const char" *name in Name to use for this window. Must be unique among all children of the same \fIparent\fR. .AP "const char" *topLevScreen in Has same format as \fIscreenName\fR. If NULL, then new window is created as an internal window. If non-NULL, new window is created as a top-level window on screen \fItopLevScreen\fR. If \fItopLevScreen\fR is an empty string .PQ "" then new window is created as top-level window of \fIparent\fR's screen. .AP Tk_Window tkwin in Token for window. .AP "const char" *pathName in Name of new window, specified as path name within application (e.g. \fB.a.b.c\fR). .BE .SH DESCRIPTION .PP The procedures \fBTk_CreateWindow\fR, \fBTk_CreateAnonymousWindow\fR, and \fBTk_CreateWindowFromPath\fR are used to create new windows for use in Tk-based applications. Each of the procedures returns a token that can be used to manipulate the window in other calls to the Tk library. If the window could not be created successfully, then NULL is returned and the result of interpreter \fIinterp\fR is modified to hold an error message. .PP Tk supports two different kinds of windows: internal windows and top-level windows. An internal window is an interior window of a Tk application, such as a scrollbar or menu bar or button. A top-level window is one that is created as a child of a screen's root window, rather than as an interior window, but which is logically part of some existing main window. Examples of top-level windows are pop-up menus and dialog boxes. .PP New windows may be created by calling \fBTk_CreateWindow\fR. If the \fItopLevScreen\fR argument is NULL, then the new window will be an internal window. If \fItopLevScreen\fR is non-NULL, then the new window will be a top-level window: \fItopLevScreen\fR indicates the name of a screen and the new window will be created as a child of the root window of \fItopLevScreen\fR. In either case Tk will consider the new window to be the logical child of \fIparent\fR: the new window's path name will reflect this fact, options may be specified for the new window under this assumption, and so on. The only difference is that new X window for a top-level window will not be a child of \fIparent\fR's X window. For example, a pull-down menu's \fIparent\fR would be the button-like window used to invoke it, which would in turn be a child of the menu bar window. A dialog box might have the application's main window as its parent. .PP \fBTk_CreateAnonymousWindow\fR differs from \fBTk_CreateWindow\fR in that it creates an unnamed window. This window will be manipulatable only using C interfaces, and will not be visible to Tcl scripts. Both interior windows and top-level windows may be created with \fBTk_CreateAnonymousWindow\fR. .PP \fBTk_CreateWindowFromPath\fR offers an alternate way of specifying new windows. In \fBTk_CreateWindowFromPath\fR the new window is specified with a token for any window in the target application (\fItkwin\fR), plus a path name for the new window. It produces the same effect as \fBTk_CreateWindow\fR and allows both top-level and internal windows to be created, depending on the value of \fItopLevScreen\fR. In calls to \fBTk_CreateWindowFromPath\fR, as in calls to \fBTk_CreateWindow\fR, the parent of the new window must exist at the time of the call, but the new window must not already exist. .PP The window creation procedures do not actually issue the command to X to create a window. Instead, they create a local data structure associated with the window and defer the creation of the X window. The window will actually be created by the first call to \fBTk_MapWindow\fR. Deferred window creation allows various aspects of the window (such as its size, background color, etc.) to be modified after its creation without incurring any overhead in the X server. When the window is finally mapped all of the window attributes can be set while creating the window. .PP The value returned by a window-creation procedure is not the X token for the window (it cannot be, since X has not been asked to create the window yet). Instead, it is a token for Tk's local data structure for the window. Most of the Tk library procedures take Tk_Window tokens, rather than X identifiers. The actual X window identifier can be retrieved from the local data structure using the \fBTk_WindowId\fR macro; see the manual entry for \fBTk_WindowId\fR for details. .PP \fBTk_DestroyWindow\fR deletes a window and all the data structures associated with it, including any event handlers created with \fBTk_CreateEventHandler\fR. In addition, \fBTk_DestroyWindow\fR will delete any children of \fItkwin\fR recursively (where children are defined in the Tk sense, consisting of all windows that were created with the given window as \fIparent\fR). If \fItkwin\fR is an internal window, then event handlers interested in destroy events are invoked immediately. If \fItkwin\fR is a top-level or main window, then the event handlers will be invoked later, after X has seen the request and returned an event for it. .PP If a window has been created but has not been mapped, so no X window exists, it is possible to force the creation of the X window by calling \fBTk_MakeWindowExist\fR. This procedure issues the X commands to instantiate the window given by \fItkwin\fR. .SH KEYWORDS create, deferred creation, destroy, display, internal window, screen, top-level window, window tk9.0.3/doc/cursors.n0000644001000000100000000000457215076161055017504 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" '\" Copyright (c) 2006-2007 Daniel A. Steffen '\" .TH cursors n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME cursors \- mouse cursors available in Tk .BE .SH DESCRIPTION .PP The \fB\-cursor\fR widget option allows a Tk programmer to change the mouse cursor for a particular widget. The cursor names recognized by Tk on all platforms are: .CS X_cursor arrow based_arrow_down based_arrow_up boat bogosity bottom_left_corner bottom_right_corner bottom_side bottom_tee box_spiral center_ptr circle clock coffee_mug cross cross_reverse crosshair diamond_cross dot dotbox double_arrow draft_large draft_small draped_box exchange fleur gobbler gumby hand1 hand2 heart icon iron_cross left_ptr left_side left_tee leftbutton ll_angle lr_angle man middlebutton mouse none pencil pirate plus question_arrow right_ptr right_side right_tee rightbutton rtl_logo sailboat sb_down_arrow sb_h_double_arrow sb_left_arrow sb_right_arrow sb_up_arrow sb_v_double_arrow shuttle sizing spider spraycan star target tcross top_left_arrow top_left_corner top_right_corner top_side top_tee trek ul_angle umbrella ur_angle watch xterm .CE .PP The \fBnone\fR cursor can be specified to eliminate the cursor. .SH "PORTABILITY ISSUES" .TP \fBWindows\fR . On Windows systems, the following cursors are mapped to native cursors: .RS .CS arrow center_ptr crosshair fleur ibeam icon none sb_h_double_arrow sb_v_double_arrow watch xterm .CE And the following additional cursors are available: .CS no starting size size_ne_sw size_ns size_nw_se size_we uparrow wait .CE .RE .TP \fBmacOS\fR . On macOS, the following cursors are mapped to native cursors: .RS .CS arrow top_left_arrow left_ptr cross crosshair tcross ibeam none xterm .CE And the following additional native cursors are available: .CS copyarrow aliasarrow contextualmenuarrow movearrow text cross-hair hand openhand closedhand fist pointinghand resize resizeleft resizeright resizeleftright resizeup resizedown resizeupdown resizebottomleft resizetopleft resizebottomright resizetopright notallowed poof wait countinguphand countingdownhand countingupanddownhand spinning help bucket cancel eyedrop eyedrop-full zoom-in zoom-out .CE .RE .SH KEYWORDS cursor, option '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/DeleteImg.30000644001000000100000000000151515105057705017541 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_DeleteImage 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_DeleteImage \- Destroy an image. .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_DeleteImage\fR(\fIinterp, name\fR) .fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in Interpreter for which the image was created. .AP "const char" *name in Name of the image. .BE .SH DESCRIPTION .PP \fBTk_DeleteImage\fR deletes the image given by \fIinterp\fR and \fIname\fR, if there is one. All instances of that image will redisplay as empty regions. If the given image does not exist then the procedure has no effect. .SH KEYWORDS delete image, image manager tk9.0.3/doc/destroy.n0000644001000000100000000000240115076161055017462 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH destroy n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME destroy \- Destroy one or more windows .SH SYNOPSIS \fBdestroy \fR?\fIwindow window ...\fR? .BE .SH DESCRIPTION .PP This command deletes the windows given by the \fIwindow\fR arguments, plus all of their descendants. If a \fIwindow\fR .QW . is deleted then all windows will be destroyed and the application will (normally) exit. The \fIwindow\fRs are destroyed in order, and if an error occurs in destroying a window the command aborts without destroying the remaining windows. No error is returned if \fIwindow\fR does not exist. .SH EXAMPLE .PP Destroy all checkbuttons that are direct children of the given widget: .CS proc killCheckbuttonChildren {parent} { foreach w [winfo children $parent] { if {[winfo class $w] eq "Checkbutton"} { \fBdestroy\fR $w } } } .CE .SH KEYWORDS application, destroy, window '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/dialog.n0000644001000000100000000000466715105057705017247 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk_dialog n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_dialog \- Create modal dialog and wait for response .SH SYNOPSIS \fBtk_dialog \fIwindow title text bitmap default string string ...\fR .BE .SH DESCRIPTION .PP This procedure is part of the Tk script library. It is largely \fIdeprecated\fR by the \fBtk_messageBox\fR. Its arguments describe a dialog box: .IP \fIwindow\fR Name of top-level window to use for dialog. Any existing window by this name is destroyed. .IP \fItitle\fR Text to appear in the window manager's title bar for the dialog. .IP \fItext\fR Message to appear in the top portion of the dialog box. .IP \fIbitmap\fR If non-empty, specifies a bitmap (in a form suitable for Tk_GetBitmap) to display in the top portion of the dialog, to the left of the text. If this is an empty string then no bitmap is displayed in the dialog. .IP \fIdefault\fR If this is an integer greater than or equal to zero, then it gives the index of the button that is to be the default button for the dialog (0 for the leftmost button, and so on). If negative or an empty string then there will not be any default button. .IP \fIstring\fR There will be one button for each of these arguments. Each \fIstring\fR specifies text to display in a button, in order from left to right. .PP After creating a dialog box, \fBtk_dialog\fR waits for the user to select one of the buttons either by clicking on the button with the mouse or by typing return to invoke the default button (if any). Then it returns the index of the selected button: 0 for the leftmost button, 1 for the button next to it, and so on. If the dialog's window is destroyed before the user selects one of the buttons, then \-1 is returned. .PP While waiting for the user to respond, \fBtk_dialog\fR sets a local grab. This prevents the user from interacting with the application in any way except to invoke the dialog box. .SH EXAMPLE .PP .CS set reply [\fBtk_dialog\fR .foo "The Title" "Do you want to say yes?" \e questhead 0 Yes No "I'm not sure"] .CE .SH "SEE ALSO" tk_messageBox(n) .SH KEYWORDS bitmap, dialog, modal '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/DrawFocHlt.30000644001000000100000000000211315105057705017672 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_DrawFocusHighlight 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_DrawFocusHighlight\fR(\fItkwin, gc, width, drawable\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *joinPtr .AP Tk_Window tkwin in Window for which the highlight is being drawn. Used to retrieve the window's dimensions, among other things. .AP GC gc in Graphics context to use for drawing the highlight. .AP int width in Width of the highlight ring, in pixels. .AP Drawable drawable in Drawable in which to draw the highlight; usually an offscreen pixmap for double buffering. .BE .SH DESCRIPTION .PP \fBTk_DrawFocusHighlight\fR is a utility procedure that draws the traversal highlight ring for a widget. It is typically invoked by widgets during redisplay. .SH KEYWORDS focus, traversal highlight tk9.0.3/doc/entry.n0000644001000000100000000005717215105057705017150 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH entry n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME entry \- Create and manipulate 'entry' one-line text entry widgets .SH SYNOPSIS \fBentry\fI pathName \fR?\fIoptions\fR? .SO \-background \-highlightthickness \-selectbackground \-borderwidth \-insertbackground \-selectborderwidth \-cursor \-insertborderwidth \-selectforeground \-exportselection \-insertofftime \-takefocus \-font \-insertontime \-textvariable \-foreground \-insertwidth \-xscrollcommand \-highlightbackground \-justify \-highlightcolor \-relief \-placeholder \-placeholderforeground .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-disabledbackground disabledBackground DisabledBackground Specifies the background color to use when the entry is disabled. If this option is the empty string, the normal background color is used. .OP \-disabledforeground disabledForeground DisabledForeground Specifies the foreground color to use when the entry is disabled. If this option is the empty string, the normal foreground color is used. .OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand Specifies a script to eval when \fB\-validatecommand\fR returns 0. Setting it to {} disables this feature (the default). The best use of this option is to set it to \fIbell\fR. See \fBVALIDATION\fR below for more information. .OP \-readonlybackground readonlyBackground ReadonlyBackground Specifies the background color to use when the entry is readonly. If this option is the empty string, the normal background color is used. .OP \-show show Show If this option is specified, then the true contents of the entry are not displayed in the window. Instead, each character in the entry's value will be displayed as the first character in the value of this option, such as .QW * . This is useful, for example, if the entry is to be used to enter a password. If characters in the entry are selected and copied elsewhere, the information copied will be what is displayed, not the true contents of the entry. .OP \-state state State Specifies one of three states for the entry: \fBnormal\fR, \fBdisabled\fR, or \fBreadonly\fR. If the entry is readonly, then the value may not be changed using widget commands and no insertion cursor will be displayed, even if the input focus is in the widget; the contents of the widget may still be selected. If the entry is disabled, the value may not be changed, no insertion cursor will be displayed, the contents will not be selectable, and the entry may be displayed in a different color, depending on the values of the \fB\-disabledforeground\fR and \fB\-disabledbackground\fR options. .OP \-validate validate Validate Specifies the mode in which validation should operate: \fBnone\fR, \fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. It defaults to \fBnone\fR. When you want validation, you must explicitly state which mode you wish to use. See \fBVALIDATION\fR below for more. .OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand Specifies a script to eval when you want to validate the input into the entry widget. Setting it to {} disables this feature (the default). This command must return a valid Tcl boolean value. If it returns 0 (or the valid Tcl boolean equivalent) then it means you reject the new edition and it will not occur and the \fB\-invalidcommand\fR will be evaluated if it is set. If it returns 1, then the new edition occurs. See \fBVALIDATION\fR below for more information. .OP \-width width Width Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. If the value is negative or zero, the widget picks a size just large enough to hold its current text. .BE .SH DESCRIPTION .PP The \fBentry\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into an entry widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the entry such as its colors, font, and relief. The \fBentry\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP An entry is a widget that displays a one-line text string and allows that string to be edited using widget commands described below, which are typically bound to keystrokes and mouse actions. When first created, an entry's string is empty. A portion of the entry may be selected as described below. If an entry is exporting its selection (see the \fB\-exportselection\fR option), then it will observe the standard X11 protocols for handling the selection; entry selections are available as type \fBSTRING\fR. Entries also observe the standard Tk rules for dealing with the input focus. When an entry has the input focus it displays an \fIinsertion cursor\fR to indicate where new characters will be inserted. .PP Entries are capable of displaying strings that are too long to fit entirely within the widget's window. In this case, only a portion of the string will be displayed; commands described below may be used to change the view in the window. Entries use the standard \fB\-xscrollcommand\fR mechanism for interacting with scrollbars (see the description of the \fB\-xscrollcommand\fR option for details). They also support scanning, as described below. .SH VALIDATION .PP Validation works by setting the \fB\-validatecommand\fR option to a script (\fIvalidateCommand\fR) which will be evaluated according to the \fB\-validate\fR option as follows: .PP .IP \fBnone\fR 10 Default. This means no validation will occur. .IP \fBfocus\fR 10 \fIvalidateCommand\fR will be called when the entry receives or loses focus. .IP \fBfocusin\fR 10 \fIvalidateCommand\fR will be called when the entry receives focus. .IP \fBfocusout\fR 10 \fIvalidateCommand\fR will be called when the entry loses focus. .IP \fBkey\fR 10 \fIvalidateCommand\fR will be called when the entry is edited. .IP \fBall\fR 10 \fIvalidateCommand\fR will be called for all above conditions. .PP It is possible to perform percent substitutions on the value of the \fB\-validatecommand\fR and \fB\-invalidcommand\fR options, just as you would in a \fBbind\fR script. The following substitutions are recognized: .PP .IP \fB%d\fR 5 Type of action: 1 for \fBinsert\fR, 0 for \fBdelete\fR, or \-1 for focus, forced or textvariable validation. .IP \fB%i\fR 5 Index of char string to be inserted/deleted, if any, otherwise \-1. .IP \fB%P\fR 5 The value of the entry if the edit is allowed. If you are configuring the entry widget to have a new textvariable, this will be the value of that textvariable. .IP \fB%s\fR 5 The current value of entry prior to editing. .IP \fB%S\fR 5 The text string being inserted/deleted, if any, {} otherwise. .IP \fB%v\fR 5 The type of validation currently set. .IP \fB%V\fR 5 The type of validation that triggered the callback (key, focusin, focusout, forced). .IP \fB%W\fR 5 The name of the entry widget. .PP In general, the \fB\-textvariable\fR and \fB\-validatecommand\fR options can be dangerous to mix. Any problems have been overcome so that using the \fB\-validatecommand\fR will not interfere with the traditional behavior of the entry widget. Using the \fB\-textvariable\fR for read-only purposes will never cause problems. The danger comes when you try set the \fB\-textvariable\fR to something that the \fB\-validatecommand\fR would not accept, which causes \fB\-validate\fR to become \fInone\fR (the \fB\-invalidcommand\fR will not be triggered). The same happens when an error occurs evaluating the \fB\-validatecommand\fR. .PP Primarily, an error will occur when the \fB\-validatecommand\fR or \fB\-invalidcommand\fR encounters an error in its script while evaluating or \fB\-validatecommand\fR does not return a valid Tcl boolean value. The \fB\-validate\fR option will also set itself to \fBnone\fR when you edit the entry widget from within either the \fB\-validatecommand\fR or the \fB\-invalidcommand\fR. Such editions will override the one that was being validated. If you wish to edit the entry widget (for example set it to {}) during validation and still have the \fB\-validate\fR option set, you should include the command: .CS after idle {%W config -validate %v} .CE in the \fB\-validatecommand\fR or \fB\-invalidcommand\fR (whichever one you were editing the entry widget from). It is also recommended to not set an associated \fB\-textvariable\fR during validation, as that can cause the entry widget to become out of sync with the \fB\-textvariable\fR. .SH "WIDGET COMMAND" .PP The \fBentry\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName subcommand \fR?\fIarg ...\fR? .CE \fISubcommand\fR and the \fIarg\fRs determine the exact behavior of the command. .SS INDICES .PP Many of the widget commands for entries take one or more indices as arguments. An index specifies a particular character in the entry's string, in any of the following ways: .TP 12 \fInumber\fR . Specifies the character as a numerical index, where 0 corresponds to the first character in the string. .TP 12 \fBanchor\fR . Indicates the anchor point for the selection, which is set with the \fBselect from\fR and \fBselect adjust\fR widget commands. .TP 12 \fBend\fR . Indicates the character just after the last one in the entry's string. This is equivalent to specifying a numerical index equal to the length of the entry's string. .TP 12 \fBinsert\fR . Indicates the character adjacent to and immediately following the insertion cursor. .TP 12 \fBsel.first\fR . Indicates the first character in the selection. It is an error to use this form if the selection is not in the entry window. .TP 12 \fBsel.last\fR . Indicates the character just after the last one in the selection. It is an error to use this form if the selection is not in the entry window. .TP 12 \fB@\fInumber\fR . In this form, \fInumber\fR is treated as an x-coordinate in the entry's window; the character spanning that x-coordinate is used. For example, .QW \fB@0\fR indicates the left-most character in the window. .LP Abbreviations may be used for any of the forms above, e.g. .QW \fBe\fR or .QW \fBsel.f\fR . In general, out-of-range indices are automatically rounded to the nearest legal value. Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. .SS SUBCOMMANDS .PP The following commands are possible for entry widgets: .\" METHOD: bbox .TP \fIpathName \fBbbox \fIindex\fR . Returns a list of four numbers describing the bounding box of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBentry\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBentry\fR command. .\" METHOD: delete .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? . Delete one or more elements of the entry. \fIFirst\fR is the index of the first character to delete, and \fIlast\fR is the index of the character just after the last one to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, i.e. a single character is deleted. This command returns an empty string. .\" METHOD: get .TP \fIpathName \fBget\fR . Returns the entry's string. .\" METHOD: icursor .TP \fIpathName \fBicursor \fIindex\fR . Arrange for the insertion cursor to be displayed just before the character given by \fIindex\fR. Returns an empty string. .\" METHOD: index .TP \fIpathName \fBindex\fI index\fR . Returns the numerical index corresponding to \fIindex\fR. .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex string\fR . Insert the characters of \fIstring\fR just before the character indicated by \fIindex\fR. Returns an empty string. .\" METHOD: scan .TP \fIpathName \fBscan\fI option args\fR . This command is used to implement scanning on entries. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx\fR . Records \fIx\fR and the current view in the entry window; used in conjunction with later \fBscan dragto\fR commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. .TP \fIpathName \fBscan dragto \fIx\fR . This command computes the difference between its \fIx\fR argument and the \fIx\fR argument to the last \fBscan mark\fR command for the widget. It then adjusts the view left or right by 10 times the difference in x-coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the entry at high speed through the window. The return value is an empty string. .RE .\" METHOD: selection .TP \fIpathName \fBselection \fIoption arg\fR . This command is used to adjust the selection within an entry. It has several forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBselection adjust \fIindex\fR . Locate the end of the selection nearest to the character given by \fIindex\fR, and adjust that end of the selection to be at \fIindex\fR (i.e. including but not going beyond \fIindex\fR). The other end of the selection is made the anchor point for future \fBselect to\fR commands. If the selection is not currently in the entry, then a new selection is created to include the characters between \fIindex\fR and the most recent selection anchor point, inclusive. Returns an empty string. .TP \fIpathName \fBselection clear\fR . Clear the selection if it is currently in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. .TP \fIpathName \fBselection from \fIindex\fR . Set the selection anchor point to just before the character given by \fIindex\fR. Does not change the selection. Returns an empty string. .TP \fIpathName \fBselection present\fR . Returns 1 if there is are characters selected in the entry, 0 if nothing is selected. .TP \fIpathName \fBselection range \fIstart end\fR . Sets the selection to include the characters starting with the one indexed by \fIstart\fR and ending with the one just before \fIend\fR. If \fIend\fR refers to the same character as \fIstart\fR or an earlier one, then the entry's selection is cleared. .TP \fIpathName \fBselection to \fIindex\fR . If \fIindex\fR is before the anchor point, set the selection to the characters from \fIindex\fR up to but not including the anchor point. If \fIindex\fR is the same as the anchor point, do nothing. If \fIindex\fR is after the anchor point, set the selection to the characters from the anchor point up to but not including \fIindex\fR. The anchor point is determined by the most recent \fBselect from\fR or \fBselect adjust\fR command in this widget. If the selection is not in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string. .RE .\" METHOD: validate .TP \fIpathName \fBvalidate\fR . This command is used to force an evaluation of the \fB\-validatecommand\fR independent of the conditions specified by the \fB\-validate\fR option. This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR. It returns 0 or 1. .\" METHOD: xview .TP \fIpathName \fBxview \fIargs\fR . This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR . Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the entry's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP \fIpathName \fBxview\fI index\fR . Adjusts the view in the window so that the character given by \fIindex\fR is displayed at the left edge of the window. .TP \fIpathName \fBxview moveto\fI fraction\fR . Adjusts the view in the window so that the character \fIfraction\fR of the way through the text appears at the left edge of the window. \fIFraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR . This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then it is converted to an integer, rounded away from 0. \fIWhat\fR must be either \fBpages\fR or \fBunits\fR or an abbreviation of one of these. If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by \fInumber\fR average-width characters on the display. .RE .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for entries that give them the following default behavior. In the descriptions below, .QW word refers to a contiguous group of letters, digits, or .QW _ characters, or any single character other than these. .IP [1] Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse. .IP [2] Double-clicking with mouse button 1 selects the word under the mouse and positions the insertion cursor at the end of the word. Dragging after a double click will stroke out a selection consisting of whole words. .IP [3] Triple-clicking with mouse button 1 selects all of the text in the entry and positions the insertion cursor at the end of the line. .IP [4] The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words. .IP [5] Clicking mouse button 1 with the Control key down will position the insertion cursor in the entry without affecting the selection. .IP [6] If any normal printing characters are typed in an entry, they are inserted at the point of the insertion cursor. .IP [7] The view in the entry can be adjusted by dragging with the middle mouse button (button 2, or button 3 in TkAqua). If the middle mouse button is clicked without moving the mouse, the selection is copied into the entry at the position of the mouse cursor. .IP [8] If the mouse is dragged out of the entry on the left or right sides while button 1 is pressed, the entry will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window). .IP [9] The Left and Right keys move the insertion cursor one character to the left or right; they also clear any selection in the entry and set the selection anchor. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f behave the same as Control-Left and Control-Right, respectively. .IP [10] The Home key, or Control-a, will move the insertion cursor to the beginning of the entry and clear any selection in the entry. Shift-Home moves the insertion cursor to the beginning of the entry and also extends the selection to that point. .IP [11] The End key, or Control-e, will move the insertion cursor to the end of the entry and clear any selection in the entry. Shift-End moves the cursor to the end and extends the selection to that point. .IP [12] The Select key and Control-Space set the selection anchor to the position of the insertion cursor. They do not affect the current selection. Shift-Select and Control-Shift-Space adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was not any selection previously. .IP [13] Control-/ selects all the text in the entry. .IP [14] Control-\e clears any selection in the entry. .IP [15] The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection. .IP [16] The F20 key (labelled Cut on many Sun workstations) or Control-w copies the selection in the widget to the clipboard and deletes the selection. If there is no selection in the widget then these keys have no effect. .IP [17] The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the contents of the clipboard at the position of the insertion cursor. .IP [18] The Delete key deletes the selection, if there is one in the entry. If there is no selection, it deletes the character to the right of the insertion cursor. .IP [19] The BackSpace key and Control-h delete the selection, if there is one in the entry. If there is no selection, it deletes the character to the left of the insertion cursor. .IP [20] Control-d deletes the character to the right of the insertion cursor. .IP [21] Meta-d deletes the word to the right of the insertion cursor. .IP [22] Control-k deletes all the characters to the right of the insertion cursor. .IP [23] Control-t reverses the order of the two characters to the right of the insertion cursor. .PP If the entry is disabled using the \fB\-state\fR option, then the entry's view can still be adjusted and text in the entry can still be selected, but no insertion cursor will be displayed and no text modifications will take place except if the entry is linked to a variable using the \fB\-textvariable\fR option, in which case any changes to the variable are reflected by the entry whatever the value of its \fB\-state\fR option. .PP The behavior of entries can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "SEE ALSO" ttk::entry(n) .SH KEYWORDS entry, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/event.n0000644001000000100000000005536315105057705017130 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1996 Sun Microsystems, Inc. '\" Copyright (c) 1998-2000 Ajuba Solutions. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH event n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME event \- Miscellaneous event facilities: define virtual events and generate events .SH SYNOPSIS \fBevent\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBevent\fR command provides several facilities for dealing with window system events, such as defining virtual events and synthesizing events. The command has several different forms, determined by the first argument. The following forms are currently supported: .\" METHOD: add .TP \fBevent add <<\fIvirtual\fB>>\fI sequence \fR?\fIsequence ...\fR? . Associates the virtual event \fIvirtual\fR with the physical event sequence(s) given by the \fIsequence\fR arguments, so that the virtual event will trigger whenever any one of the \fIsequence\fRs occurs. \fIVirtual\fR may be any string value and \fIsequence\fR may have any of the values allowed for the \fIsequence\fR argument to the \fBbind\fR command. If \fIvirtual\fR is already defined, the new physical event sequences add to the existing sequences for the event. .\" METHOD: delete .TP \fBevent delete <<\fIvirtual\fB>> \fR?\fIsequence sequence ...\fR? . Deletes each of the \fIsequence\fRs from those associated with the virtual event given by \fIvirtual\fR. \fIVirtual\fR may be any string value and \fIsequence\fR may have any of the values allowed for the \fIsequence\fR argument to the \fBbind\fR command. Any \fIsequence\fRs not currently associated with \fIvirtual\fR are ignored. If no \fIsequence\fR argument is provided, all physical event sequences are removed for \fIvirtual\fR, so that the virtual event will not trigger anymore. .\" METHOD: generate .TP \fBevent generate \fIwindow event \fR?\fIoption value option value ...\fR? . Generates a window event and arranges for it to be processed just as if it had come from the window system. \fIWindow\fR gives the path name of the window for which the event will be generated; it may also be an identifier (such as returned by \fBwinfo id\fR) as long as it is for a window in the current application. \fIEvent\fR provides a basic description of the event, such as \fB\fR or \fB<>\fR. If \fIWindow\fR is empty the whole screen is meant, and coordinates are relative to the screen. \fIEvent\fR may have any of the forms allowed for the \fIsequence\fR argument of the \fBbind\fR command except that it must consist of a single event pattern, not a sequence. \fIOption-value\fR pairs may be used to specify additional attributes of the event, such as the x and y mouse position; see \fBEVENT FIELDS\fR below. If the \fB\-when\fR option is not specified, the event is processed immediately: all of the handlers for the event will complete before the \fBevent generate\fR command returns. If the \fB\-when\fR option is specified then it determines when the event is processed. Certain events, such as key events, require that the window has focus to receive the event properly. .\" METHOD: info .TP \fBevent info \fR?\fB<<\fIvirtual\fB>>\fR? . Returns information about virtual events. If the \fB<<\fIvirtual\fB>>\fR argument is omitted, the return value is a list of all the virtual events that are currently defined. If \fB<<\fIvirtual\fB>>\fR is specified then the return value is a list whose elements are the physical event sequences currently defined for the given virtual event; if the virtual event is not defined then an empty string is returned. .RS .PP Note that virtual events that are not bound to physical event sequences are \fInot\fR returned by \fBevent info\fR. .RE .SH "EVENT FIELDS" .PP The following options are supported for the \fBevent generate\fR command. These correspond to the .QW % expansions allowed in binding scripts for the \fBbind\fR command. .\" OPTION: -above .TP \fB\-above\fI window\fR . \fIWindow\fR specifies the \fIabove\fR field for the event, either as a window path name or as an integer window id. Valid for \fBConfigure\fR events. Corresponds to the \fB%a\fR substitution for binding scripts. .\" OPTION: -borderwidth .TP \fB\-borderwidth\fI size\fR . \fISize\fR must be a screen distance; it specifies the \fIborder_width\fR field for the event. Valid for \fBConfigure\fR events. Corresponds to the \fB%B\fR substitution for binding scripts. .\" OPTION: -button .TP \fB\-button\fI number\fR . \fINumber\fR must be an integer; it specifies the \fIdetail\fR field for a \fBButton\fR or \fBButtonRelease\fR event, overriding any button number provided in the base \fIevent\fR argument. Corresponds to the \fB%b\fR substitution for binding scripts. .\" OPTION: -count .TP \fB\-count\fI number\fR . \fINumber\fR must be an integer; it specifies the \fIcount\fR field for the event. Valid for \fBExpose\fR events. Corresponds to the \fB%c\fR substitution for binding scripts. .\" OPTION: -data .TP \fB\-data\fI string\fR . \fIString\fR may be any value; it specifies the \fIuser_data\fR field for the event. Only valid for virtual events. Corresponds to the \fB%d\fR substitution for virtual events in binding scripts. .\" OPTION: -delta .TP \fB\-delta\fI number\fR . \fINumber\fR must be an integer; it specifies the \fIdelta\fR field for the \fBMouseWheel\fR event. The \fIdelta\fR refers to the direction and magnitude the mouse wheel was rotated. Note the value is not a screen distance but are units of motion in the mouse wheel. Typically these values are multiples of 120. For example, 120 should scroll the text widget up 4 lines and \-240 would scroll the text widget down 8 lines. Of course, other widgets may define different behaviors for mouse wheel motion. This field corresponds to the \fB%D\fR substitution for binding scripts. .\" OPTION: -detail .TP \fB\-detail\fI detail\fR . \fIDetail\fR specifies the \fIdetail\fR field for the event and must be one of the following: .RS .DS .ta 6c \fBNotifyAncestor\fR \fBNotifyNonlinearVirtual\fR \fBNotifyDetailNone\fR \fBNotifyPointer\fR \fBNotifyInferior\fR \fBNotifyPointerRoot\fR \fBNotifyNonlinear\fR \fBNotifyVirtual\fR .DE Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR and \fBFocusOut\fR events. Corresponds to the \fB%d\fR substitution for binding scripts. .RE .\" OPTION: -focus .TP \fB\-focus\fI boolean\fR . \fIBoolean\fR must be a boolean value; it specifies the \fIfocus\fR field for the event. Valid for \fBEnter\fR and \fBLeave\fR events. Corresponds to the \fB%f\fR substitution for binding scripts. .\" OPTION: -height .TP \fB\-height\fI size\fR . \fISize\fR must be a screen distance; it specifies the \fIheight\fR field for the event. Valid for \fBConfigure\fR events. Corresponds to the \fB%h\fR substitution for binding scripts. .\" OPTION: -keycode .TP \fB\-keycode\fI number\fR . \fINumber\fR must be an integer; it specifies the \fIkeycode\fR field for the event. Valid for \fBKey\fR and \fBKeyRelease\fR events. Corresponds to the \fB%k\fR substitution for binding scripts. .\" OPTION: -keysym .TP \fB\-keysym\fI name\fR . \fIName\fR must be the name of a valid keysym, such as \fBg\fR, \fBspace\fR, or \fBReturn\fR; its corresponding keycode value is used as the \fIkeycode\fR field for event, overriding any detail specified in the base \fIevent\fR argument. Valid for \fBKey\fR and \fBKeyRelease\fR events. Corresponds to the \fB%K\fR substitution for binding scripts. .\" OPTION: -mode .TP \fB\-mode\fI notify\fR . \fINotify\fR specifies the \fImode\fR field for the event and must be one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or \fBNotifyWhileGrabbed\fR. Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events. Corresponds to the \fB%m\fR substitution for binding scripts. .\" OPTION: -override .TP \fB\-override\fI boolean\fR . \fIBoolean\fR must be a boolean value; it specifies the \fIoverride_redirect\fR field for the event. Valid for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. Corresponds to the \fB%o\fR substitution for binding scripts. .\" OPTION: -place .TP \fB\-place\fI where\fR . \fIWhere\fR specifies the \fIplace\fR field for the event; it must be either \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid for \fBCirculate\fR events. Corresponds to the \fB%p\fR substitution for binding scripts. .\" OPTION: -root .TP \fB\-root\fI window\fR . \fIWindow\fR must be either a window path name or an integer window identifier; it specifies the \fIroot\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. Corresponds to the \fB%R\fR substitution for binding scripts. .\" OPTION: -rootx .TP \fB\-rootx\fI coord\fR . \fICoord\fR must be a screen distance; it specifies the \fIx_root\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. Corresponds to the \fB%X\fR substitution for binding scripts. .\" OPTION: -rooty .TP \fB\-rooty\fI coord\fR . \fICoord\fR must be a screen distance; it specifies the \fIy_root\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. Corresponds to the \fB%Y\fR substitution for binding scripts. .\" OPTION: -sendevent .TP \fB\-sendevent\fI boolean\fR . \fIBoolean\fR must be a boolean value; it specifies the \fIsend_event\fR field for the event. Valid for all events. Corresponds to the \fB%E\fR substitution for binding scripts. .\" OPTION: -serial .TP \fB\-serial\fI number\fR . \fINumber\fR must be an integer; it specifies the \fIserial\fR field for the event. Valid for all events. Corresponds to the \fB%#\fR substitution for binding scripts. .\" OPTION: -state .TP \fB\-state\fI state\fR . \fIState\fR specifies the \fIstate\fR field for the event. For \fBKey\fR, \fBKeyRelease\fR, \fBButtons\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events it must be an integer value. For \fBVisibility\fR events it must be one of \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, or \fBVisibilityFullyObscured\fR. This option overrides any modifiers such as \fBMeta\fR or \fBControl\fR specified in the base \fIevent\fR. Corresponds to the \fB%s\fR substitution for binding scripts. .\" OPTION: -subwindow .TP \fB\-subwindow\fI window\fR . \fIWindow\fR specifies the \fIsubwindow\fR field for the event, either as a path name for a Tk widget or as an integer window identifier. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. Similar to \fB%S\fR substitution for binding scripts. .\" OPTION: -time .TP \fB\-time\fI integer\fR . \fIInteger\fR must be an integer value; it specifies the \fItime\fR field for the event. Additionally, the special value \fBcurrent\fR is allowed; this value will be substituted by the current event time. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, \fBMotion\fR, and \fBProperty\fR events. Corresponds to the \fB%t\fR substitution for binding scripts. .\" OPTION: -warp .TP \fB\-warp\fI boolean\fR . \fIboolean\fR must be a boolean value; it specifies whether the screen pointer should be warped as well. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, and \fBMotion\fR events. The pointer will only warp to a window if it is mapped. .\" OPTION: -width .TP \fB\-width\fI size\fR . \fISize\fR must be a screen distance; it specifies the \fIwidth\fR field for the event. Valid for \fBConfigure\fR events. Corresponds to the \fB%w\fR substitution for binding scripts. .\" OPTION: -when .TP \fB\-when\fI when\fR . \fIWhen\fR determines when the event will be processed; it must have one of the following values: .RS .IP \fBnow\fR 10 Process the event immediately, before the command returns. This also happens if the \fB\-when\fR option is omitted. .IP \fBtail\fR 10 Place the event on Tcl's event queue behind any events already queued for this application. .IP \fBhead\fR 10 Place the event at the front of Tcl's event queue, so that it will be handled before any other events already queued. .IP \fBmark\fR 10 Place the event at the front of Tcl's event queue but behind any other events already queued with \fB\-when mark\fR. This option is useful when generating a series of events that should be processed in order but at the front of the queue. .RE .\" OPTION: -x .TP \fB\-x\fI coord\fR . \fICoord\fR must be a screen distance; it specifies the \fIx\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, \fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR events. Corresponds to the \fB%x\fR substitution for binding scripts. If \fIWindow\fR is empty the coordinate is relative to the screen, and this option corresponds to the \fB%X\fR substitution for binding scripts. .\" OPTION: -y .TP \fB\-y\fI coord\fR . \fICoord\fR must be a screen distance; it specifies the \fIy\fR field for the event. Valid for \fBKey\fR, \fBKeyRelease\fR, \fBButton\fR, \fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, \fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR events. Corresponds to the \fB%y\fR substitution for binding scripts. If \fIWindow\fR is empty the coordinate is relative to the screen, and this option corresponds to the \fB%Y\fR substitution for binding scripts. .PP Any options that are not specified when generating an event are filled with the value 0, except for \fIserial\fR, which is filled with the next X event serial number. .SH "PREDEFINED VIRTUAL EVENTS" .PP Tk defines the following virtual events for the purposes of notification: .TP \fB<>\fR . This is sent to widget to notify it that the letter it has underlined (as an accelerator indicator) with the \fB\-underline\fR option has been pressed in combination with the Alt key. The usual response to this is to either focus into the widget (or some related widget) or to invoke the widget. .TP \fB<>\fR . This can be sent to some widgets (e.g. button, listbox, menu) as an alternative to . .TP \fB<>\fR . This is sent to a listbox when the set of selected item(s) in the listbox is updated. .TP \fB<>\fR . This is sent to a menu when the currently selected item in the menu changes. It is intended for use with context-sensitive help systems. .TP \fB<>\fR . This is sent to a text widget when the contents of the widget are changed. .TP \fB<>\fR . This is sent to a text widget when the selection in the widget is changed. .TP \fB<>\fR . This is sent to all widgets when the ttk theme changed. The ttk widgets listen to this event and redisplay themselves when it fires. The legacy widgets ignore this event. .TP \fB<>\fR . This event is sent to all widgets when a font is changed, for example, by the use of [font configure]. The user_data field (%d) will have the value "FontChanged". For other system wide changes, this event will be sent to all widgets, and the user_data field will indicate the cause of the change. NOTE: all tk and ttk widgets already handle this event internally. .TP \fB<>\fR . This is sent to a widget when the focus enters the widget because of a user-driven .QW "tab to widget" action. .TP \fB<>\fR . This is sent to a widget when the focus leaves the widget because of a user-driven .QW "tab to widget" action. .TP \fB<>\fR . This is sent to a text widget when its undo stack or redo stack becomes empty or unempty. .TP \fB<>\fR . This is sent to a text widget when its internal data become obsolete, and again when these internal data are back in sync with the widget view. The detail field (%d substitution) is either true (when the widget is in sync) or false (when it is not). .PP Tk defines the following virtual events for the purposes of unifying bindings across multiple platforms. Users expect them to behave in the following way: .TP \fB<>\fR . Delete the currently selected widget contents. .TP \fB<>\fR . Copy the currently selected widget contents to the clipboard. .TP \fB<>\fR . Move the currently selected widget contents to the clipboard. .TP \fB<>\fR . Move to the end of the line in the current widget while deselecting any selected contents. .TP \fB<>\fR . Move to the start of the line in the current widget while deselecting any selected contents. .TP \fB<>\fR . Move to the next item (i.e., visible character) in the current widget while deselecting any selected contents. .TP \fB<>\fR . Move to the next line in the current widget while deselecting any selected contents. .TP \fB<>\fR . Move to the next paragraph in the current widget while deselecting any selected contents. .TP \fB<>\fR . Move to the next group of items (i.e., visible word) in the current widget while deselecting any selected contents. .TP \fB<>\fR . Replace the currently selected widget contents with the contents of the clipboard. .TP \fB<>\fR . Insert the contents of the selection at the mouse location. (This event has meaningful \fB%x\fR and \fB%y\fR substitutions). .TP \fB<>\fR . Move to the previous item (i.e., visible character) in the current widget while deselecting any selected contents. .TP \fB<>\fR . Move to the previous line in the current widget while deselecting any selected contents. .TP \fB<>\fR . Move to the previous paragraph in the current widget while deselecting any selected contents. .TP \fB<>\fR . Traverse to the previous window. .TP \fB<>\fR . Move to the previous group of items (i.e., visible word) in the current widget while deselecting any selected contents. .TP \fB<>\fR . Redo one undone action. .TP \fB<>\fR . Set the range of selected contents to the complete widget. .TP \fB<>\fR . Move to the end of the line in the current widget while extending the range of selected contents. .TP \fB<>\fR . Move to the start of the line in the current widget while extending the range of selected contents. .TP \fB<>\fR . Move to the next item (i.e., visible character) in the current widget while extending the range of selected contents. .TP \fB<>\fR . Move to the next line in the current widget while extending the range of selected contents. .TP \fB<>\fR . Move to the next paragraph in the current widget while extending the range of selected contents. .TP \fB<>\fR . Move to the next group of items (i.e., visible word) in the current widget while extending the range of selected contents. .TP \fB<>\fR . Reset the range of selected contents to be empty. .TP \fB<>\fR . Move to the previous item (i.e., visible character) in the current widget while extending the range of selected contents. .TP \fB<>\fR . Move to the previous line in the current widget while extending the range of selected contents. .TP \fB<>\fR . Move to the previous paragraph in the current widget while extending the range of selected contents. .TP \fB<>\fR . Move to the previous group of items (i.e., visible word) in the current widget while extending the range of selected contents. .TP \fB<>\fR . Toggle the selection. .TP \fB<>\fR . Undo the last action. .SH EXAMPLES .SS "MAPPING KEYS TO VIRTUAL EVENTS" .PP In order for a virtual event binding to trigger, two things must happen. First, the virtual event must be defined with the \fBevent add\fR command. Second, a binding must be created for the virtual event with the \fBbind\fR command. Consider the following virtual event definitions: .PP .CS \fBevent add\fR <> \fBevent add\fR <> \fBevent add\fR <> \fBevent add\fR <> if {[tk windowingsystem] eq "aqua"} { \fBevent add\fR <> } .CE .PP In the \fBbind\fR command, a virtual event can be bound like any other builtin event type as follows: .PP .CS bind Entry <> {%W insert [selection get]} .CE .PP The double angle brackets are used to specify that a virtual event is being bound. If the user types Control-y or presses button 2, or if a \fB<>\fR virtual event is synthesized with \fBevent generate\fR, then the \fB<>\fR binding will be invoked. .PP If a virtual binding has the exact same sequence as a separate physical binding, then the physical binding will take precedence. Consider the following example: .PP .CS \fBevent add\fR <> bind Entry {puts Control-y} bind Entry <> {puts Paste} .CE .PP When the user types Control-y the \fB\fR binding will be invoked, because a physical event is considered more specific than a virtual event, all other things being equal. However, when the user types Meta-Control-y the \fB<>\fR binding will be invoked, because the \fBMeta\fR modifier in the physical pattern associated with the virtual binding is more specific than the \fB sequence for the physical event. .PP Bindings on a virtual event may be created before the virtual event exists. Indeed, the virtual event never actually needs to be defined, for instance, on platforms where the specific virtual event would be meaningless or ungeneratable. .PP When a definition of a virtual event changes at run time, all windows will respond immediately to the new definition. Starting from the preceding example, if the following code is executed: .PP .CS bind Entry {} \fBevent add\fR <> .CE .PP the behavior will change such in two ways. First, the shadowed \fB<>\fR binding will emerge. Typing Control-y will no longer invoke the \fB\fR binding, but instead invoke the virtual event \fB<>\fR. Second, pressing the F6 key will now also invoke the \fB<>\fR binding. .SS "MOVING THE MOUSE POINTER" .PP Sometimes it is useful to be able to really move the mouse pointer. For example, if you have some software that is capable of demonstrating directly to the user how to use the program. To do this, you need to .QW warp the mouse around by using \fBevent generate\fR, like this: .PP .CS for {set xy 0} {$xy < 200} {incr xy} { \fBevent generate\fR . -x $xy -y $xy -warp 1 update after 50 } .CE .PP Note that it is usually considered bad style to move the mouse pointer for the user because it removes control from them. Therefore this technique should be used with caution. Also note that it is not guaranteed to function on all platforms. .SH "SEE ALSO" bind(n) .SH KEYWORDS event, binding, define, handle, virtual event '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/EventHndlr.30000644001000000100000000000667715105057705017771 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_CreateEventHandler 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateEventHandler, Tk_DeleteEventHandler, Tk_GetButtonMask, Tk_SendVirtualEvent \- associate procedure callback with an X event .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR) .sp \fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR) .sp \fBTk_GetButtonMask\fR(\fIbutton\fR) .sp \fBTk_SendVirtualEvent\fR(\fItkwin, eventName, detail\fR) .fi .SH ARGUMENTS .AS "unsigned long" clientData .AP unsigned button in Button number. .AP "const char" *eventName in The name of the virtual event. .AP Tcl_Obj *detail in Detail information for the virtual event. May be NULL. .AP Tk_Window tkwin in Token for window in which events may occur. .AP "unsigned long" mask in Bit-mask of events (such as \fBButtonPressMask\fR) for which \fIproc\fR should be called. .AP Tk_EventProc *proc in Procedure to invoke whenever an event in \fImask\fR occurs in the window given by \fItkwin\fR. .AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION .PP \fBTk_CreateEventHandler\fR arranges for \fIproc\fR to be invoked in the future whenever one of the event types specified by \fImask\fR occurs in the window specified by \fItkwin\fR. The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; this mechanism only works in programs that dispatch events through \fBTk_HandleEvent\fR (or through other Tk procedures that call \fBTk_HandleEvent\fR, such as \fBTcl_DoOneEvent\fR or \fBTk_MainLoop\fR). .PP \fIProc\fR should have arguments and result that match the type \fBTk_EventProc\fR: .CS typedef void \fBTk_EventProc\fR( void *\fIclientData\fR, XEvent *\fIeventPtr\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTk_CreateEventHandler\fR when the callback was created. Typically, \fIclientData\fR points to a data structure containing application-specific information about the window in which the event occurred. \fIEventPtr\fR is a pointer to the X event, which will be one of the ones specified in the \fImask\fR argument to \fBTk_CreateEventHandler\fR. .PP \fBTk_DeleteEventHandler\fR may be called to delete a previously-created event handler: it deletes the first handler it finds that is associated with \fItkwin\fR and matches the \fImask\fR, \fIproc\fR, and \fIclientData\fR arguments. If no such handler exists, then \fBTk_HandleEvent\fR returns without doing anything. Although Tk supports it, it's probably a bad idea to have more than one callback with the same \fImask\fR, \fIproc\fR, and \fIclientData\fR arguments. When a window is deleted all of its handlers will be deleted automatically; in this case there is no need to call \fBTk_DeleteEventHandler\fR. .PP If multiple handlers are declared for the same type of X event on the same window, then the handlers will be invoked in the order they were created. .PP \fBTk_GetButtonMask\fR returns the button mask corresponding to the button. E.g it will return \fIButton1Mask\fR for button \fIButton1\fR. .PP \fBTk_SendVirtualEvent\fR sends a virtual event to Tk's event queue. .SH KEYWORDS bind, callback, event, handler tk9.0.3/doc/FindPhoto.30000644001000000100000000003127615105057705017603 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Australian National University '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" Author: Paul Mackerras (paulus@cs.anu.edu.au), '\" Department of Computer Science, '\" Australian National University. '\" .TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize \- manipulate the image data stored in a photo image. .SH SYNOPSIS .nf \fB#include \fR .sp Tk_PhotoHandle \fBTk_FindPhoto\fR(\fIinterp, imageName\fR) .sp int \fBTk_PhotoPutBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ compRule\fR) .sp int \fBTk_PhotoPutZoomedBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\ zoomX, zoomY, subsampleX, subsampleY, compRule\fR) .sp int \fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR) .sp \fBTk_PhotoBlank\fR(\fIhandle\fR) .sp int \fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR) .sp \fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR) .sp int \fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR) .fi .SH ARGUMENTS .AS Tk_PhotoImageBlock window_path .AP Tcl_Interp *interp in Interpreter in which image was created and in which error reporting is to be done. .AP "const char" *imageName in Name of the photo image. .AP Tk_PhotoHandle handle in Opaque handle identifying the photo image to be affected. .AP Tk_PhotoImageBlock *blockPtr in Specifies the address and storage layout of image data. .AP int x in Specifies the X coordinate where the top-left corner of the block is to be placed within the image. .AP int y in Specifies the Y coordinate where the top-left corner of the block is to be placed within the image. .AP int width in Specifies the width of the image area to be affected (for \fBTk_PhotoPutBlock\fR) or the desired image width (for \fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR). .AP int compRule in Specifies the compositing rule used when combining transparent pixels in a block of data with a photo image. Must be one of \fBTK_PHOTO_COMPOSITE_OVERLAY\fR (which puts the block of data over the top of the existing photo image, with the previous contents showing through in the transparent bits) or \fBTK_PHOTO_COMPOSITE_SET\fR (which discards the existing photo image contents in the rectangle covered by the data block.) .AP int height in Specifies the height of the image area to be affected (for \fBTk_PhotoPutBlock\fR) or the desired image height (for \fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR). .AP int *widthPtr out Pointer to location in which to store the image width. .AP int *heightPtr out Pointer to location in which to store the image height. .AP int subsampleX in Specifies the subsampling factor in the X direction for input image data. .AP int subsampleY in Specifies the subsampling factor in the Y direction for input image data. .AP int zoomX in Specifies the zoom factor to be applied in the X direction to pixels being written to the photo image. .AP int zoomY in Specifies the zoom factor to be applied in the Y direction to pixels being written to the photo image. .BE .SH DESCRIPTION .PP \fBTk_FindPhoto\fR returns an opaque handle that is used to identify a particular photo image to the other procedures. The parameter is the name of the image, that is, the name specified to the \fBimage create photo\fR command, or assigned by that command if no name was specified. If \fIimageName\fR does not exist or is not a photo image, \fBTk_FindPhoto\fR returns NULL. .PP \fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be displayed. The call affects an area of the image of size \fIwidth\fR x \fIheight\fR pixels, with its top-left corner at coordinates (\fIx\fR,\fIy\fR). All of \fIwidth\fR, \fIheight\fR, \fIx\fR, and \fIy\fR must be non-negative. If part of this area lies outside the current bounds of the image, the image will be expanded to include the area, unless the user has specified an explicit image size with the \fB\-width\fR and/or \fB\-height\fR widget configuration options (see photo(n)); in that case the area is silently clipped to the image boundaries. .PP The \fIblock\fR parameter is a pointer to a \fBTk_PhotoImageBlock\fR structure, defined as follows: .CS typedef struct { unsigned char *\fIpixelPtr\fR; int \fIwidth\fR; int \fIheight\fR; int \fIpitch\fR; int \fIpixelSize\fR; int \fIoffset\fR[4]; } \fBTk_PhotoImageBlock\fR; .CE The \fIpixelPtr\fR field points to the first pixel, that is, the top-left pixel in the block. The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the block of pixels. The \fIpixelSize\fR field specifies the address difference between two horizontally adjacent pixels. It should be 4 for RGB and 2 for grayscale image data. Other values are possible, if the offsets in the \fIoffset\fR array are adjusted accordingly (e.g. for red, green and blue data stored in different planes). Using such a layout is strongly discouraged, though. Due to a bug, it might not work correctly if an alpha channel is provided. (see the \fBBUGS\fR section below). The \fIpitch\fR field specifies the address difference between two vertically adjacent pixels. The \fIoffset\fR array contains the offsets from the address of a pixel to the addresses of the bytes containing the red, green, blue and alpha (transparency) components. If the offsets for red, green and blue are equal, the image is interpreted as grayscale. If they differ, RGB data is assumed. Normally the offsets will be 0, 1, 2, 3 for RGB data and 0, 0, 0, 1 for grayscale. It is possible to provide image data without an alpha channel by setting the offset for alpha to a negative value and adjusting the \fIpixelSize\fR field accordingly. This use is discouraged, though (see the \fBBUGS\fR section below). .PP The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a compositing rule that says what to do with transparent pixels. The value \fBTK_PHOTO_COMPOSITE_OVERLAY\fR says that the previous contents of the photo image should show through, and the value \fBTK_PHOTO_COMPOSITE_SET\fR says that the previous contents of the photo image should be completely ignored, and the values from the block be copied directly across. The behavior in Tk8.3 and earlier was equivalent to having \fBTK_PHOTO_COMPOSITE_OVERLAY\fR as a compositing rule. .PP The value given for the \fIwidth\fR and \fIheight\fR parameters to \fBTk_PhotoPutBlock\fR do not have to correspond to the values specified in \fIblock\fR. If they are smaller, \fBTk_PhotoPutBlock\fR extracts a sub-block from the image data supplied. If they are larger, the data given are replicated (in a tiled fashion) to fill the specified area. These rules operate independently in the horizontal and vertical directions. .PP \fBTk_PhotoPutBlock\fR normally returns \fBTCL_OK\fR, though if it cannot allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is returned instead and, if the \fIinterp\fR argument is non-NULL, an error message is placed in the interpreter's result. .PP \fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that the image can be reduced or enlarged for display. The \fIsubsampleX\fR and \fIsubsampleY\fR parameters allow the size of the image to be reduced by subsampling. \fBTk_PhotoPutZoomedBlock\fR will use only pixels from the input image whose X coordinates are multiples of \fIsubsampleX\fR, and whose Y coordinates are multiples of \fIsubsampleY\fR. For example, an image of 512x512 pixels can be reduced to 256x256 by setting \fIsubsampleX\fR and \fIsubsampleY\fR to 2. .PP The \fIzoomX\fR and \fIzoomY\fR parameters allow the image to be enlarged by pixel replication. Each pixel of the (possibly subsampled) input image will be written to a block \fIzoomX\fR pixels wide and \fIzoomY\fR pixels high of the displayed image. Subsampling and zooming can be used together for special effects. .PP \fBTk_PhotoGetImage\fR can be used to retrieve image data from a photo image. \fBTk_PhotoGetImage\fR fills in the structure pointed to by the \fIblockPtr\fR parameter with values that describe the address and layout of the image data that the photo image has stored internally. The values are valid until the image is destroyed or its size is changed. .PP It is possible to modify an image by writing directly to the data the \fIpixelPtr\fR field points to. The size of the image cannot be changed this way, though. Also, changes made by writing directly to \fIpixelPtr\fR will not be immediately visible, but only after a call to \fBTk_ImageChanged\fR or after an event that causes the interested widgets to redraw themselves. For these reasons usually it is preferable to make changes to a copy of the image data and write it back with \fBTk_PhotoPutBlock\fR or \fBTk_PhotoPutZoomedBlock\fR. .PP \fBTk_PhotoGetImage\fR returns 1 for compatibility with the corresponding procedure in the old photo widget. .PP \fBTk_PhotoBlank\fR blanks the entire area of the photo image. Blank areas of a photo image are transparent. .PP \fBTk_PhotoExpand\fR requests that the widget's image be expanded to be at least \fIwidth\fR x \fIheight\fR pixels in size. The width and/or height are unchanged if the user has specified an explicit image width or height with the \fB\-width\fR and/or \fB\-height\fR configuration options, respectively. If the image data are being supplied in many small blocks, it is more efficient to use \fBTk_PhotoExpand\fR or \fBTk_PhotoSetSize\fR at the beginning rather than allowing the image to expand in many small increments as image blocks are supplied. .PP \fBTk_PhotoExpand\fR normally returns \fBTCL_OK\fR, though if it cannot allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is returned instead and, if the \fIinterp\fR argument is non-NULL, an error message is placed in the interpreter's result. .PP \fBTk_PhotoSetSize\fR specifies the size of the image, as if the user had specified the given \fIwidth\fR and \fIheight\fR values to the \fB\-width\fR and \fB\-height\fR configuration options. A value of zero for \fIwidth\fR or \fIheight\fR does not change the image's width or height, but allows the width or height to be changed by subsequent calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or \fBTk_PhotoExpand\fR. .PP \fBTk_PhotoSetSize\fR normally returns \fBTCL_OK\fR, though if it cannot allocate sufficient memory to hold the resulting image, \fBTCL_ERROR\fR is returned instead and, if the \fIinterp\fR argument is non-NULL, an error message is placed in the interpreter's result. .PP \fBTk_PhotoGetSize\fR returns the dimensions of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR. .SH PORTABILITY .PP In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and \fBTk_PhotoPutZoomedBlock\fR had different signatures. If you want to compile code that uses the old interface against 8.4 without updating your code, compile it with the flag -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK. Code linked using Stubs against older versions of Tk will continue to work. .PP In Tk 8.4, \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR, \fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR did not take an \fIinterp\fR argument or return any result code. If insufficient memory was available for an image, Tk would panic. This behaviour is still supported if you compile your extension with the additional flag -DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE. Code linked using Stubs against older versions of Tk will continue to work. .SH BUGS The \fBTk_PhotoImageBlock\fR structure used to provide image data to \fBTk_PhotoPutBlock\fR promises great flexibility in the layout of the data (e.g. separate planes for the red, green, blue and alpha channels). Unfortunately, the implementation fails to hold this promise. The problem is that the \fIpixelSize\fR field is (incorrectly) used to determine whether the image has an alpha channel. Currently, if the offset for the alpha channel is greater than or equal to \fIpixelSize\fR, \fBtk_PhotoPutblock\fR assumes no alpha data is present and makes the image fully opaque. This means that for layouts where the channels are separate (or any other exotic layout where \fIpixelSize\fR has to be smaller than the alpha offset), the alpha channel will not be read correctly. In order to be on the safe side if this issue will be corrected in a future release, it is strongly recommended you always provide alpha data - even if the image has no transparency - and only use the "standard" layout with a \fIpixelSize\fR of 2 for grayscale and 4 for RGB data with \fIoffset\fRs of 0, 0, 0, 1 or 0, 1, 2, 3 respectively. .SH CREDITS .PP The code for the photo image type was developed by Paul Mackerras, based on his earlier photo widget code. .SH KEYWORDS photo, image tk9.0.3/doc/focus.n0000644001000000100000000001263115105057705017115 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH focus n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME focus \- Manage the input focus .SH SYNOPSIS .nf \fBfocus\fR \fBfocus \fIwindow\fR \fBfocus \fIoption\fR ?\fIarg ...\fR? .fi .BE .SH DESCRIPTION .PP The \fBfocus\fR command is used to manage the Tk input focus. At any given time, one window on each display is designated as the \fIfocus window\fR; any key press or key release events for the display are sent to that window. It is normally up to the window manager to redirect the focus among the top-level windows of a display. For example, some window managers automatically set the input focus to a top-level window whenever the mouse enters it; others redirect the input focus only when the user clicks on a window. Usually the window manager will set the focus only to top-level windows, leaving it up to the application to redirect the focus among the children of the top-level. .PP Tk remembers one focus window for each top-level (the most recent descendant of that top-level to receive the focus); when the window manager gives the focus to a top-level, Tk automatically redirects it to the remembered window. Within a top-level Tk uses an \fIexplicit\fR focus model by default. Moving the mouse within a top-level does not normally change the focus; the focus changes only when a widget decides explicitly to claim the focus (e.g., because of a button click), or when the user types a key such as Tab that moves the focus. .PP The Tcl procedure \fBtk_focusFollowsMouse\fR may be invoked to create an \fIimplicit\fR focus model: it reconfigures Tk so that the focus is set to a window whenever the mouse enters it. The Tcl procedures \fBtk_focusNext\fR and \fBtk_focusPrev\fR implement a focus order among the windows of a top-level; they are used in the default bindings for Tab and Shift-Tab, among other things. .PP The \fBfocus\fR command can take any of the following forms: .TP \fBfocus\fR . Returns the path name of the focus window on the display containing the application's main window, or an empty string if no window in this application has the focus on that display. Note: it is better to specify the display explicitly using \fB\-displayof\fR (see below) so that the code will work in applications using multiple displays. .TP \fBfocus \fIwindow\fR . If the application currently has the input focus on \fIwindow\fR's display, this command resets the input focus for \fIwindow\fR's display to \fIwindow\fR and returns an empty string. If the application does not currently have the input focus on \fIwindow\fR's display, \fIwindow\fR will be remembered as the focus for its top-level; the next time the focus arrives at the top-level, Tk will redirect it to \fIwindow\fR. If \fIwindow\fR is an empty string then the command does nothing. .TP \fBfocus \-displayof \fIwindow\fR . Returns the name of the focus window on the display containing \fIwindow\fR. If the focus window for \fIwindow\fR's display is not in this application, the return value is an empty string. .TP \fBfocus \-force \fIwindow\fR . Sets the focus of \fIwindow\fR's display to \fIwindow\fR, even if the application does not currently have the input focus for the display. This command should be used sparingly, if at all. In normal usage, an application should not claim the focus for itself; instead, it should wait for the window manager to give it the focus. If \fIwindow\fR is an empty string then the command does nothing. .TP \fBfocus \-lastfor \fIwindow\fR . Returns the name of the most recent window to have the input focus among all the windows in the same top-level as \fIwindow\fR. If no window in that top-level has ever had the input focus, or if the most recent focus window has been deleted, then the name of the top-level is returned. The return value is the window that will receive the input focus the next time the window manager gives the focus to the top-level. .SH "QUIRKS" .PP When an internal window receives the input focus, Tk does not actually set the X focus to that window; as far as X is concerned, the focus will stay on the top-level window containing the window with the focus. However, Tk generates FocusIn and FocusOut events just as if the X focus were on the internal window. This approach gets around a number of problems that would occur if the X focus were actually moved; the fact that the X focus is on the top-level is invisible unless you use C code to query the X server directly. .SH "EXAMPLE" .PP To make a window that only participates in the focus traversal ring when a variable is set, add the following bindings to the widgets \fIbefore\fR and \fIafter\fR it in that focus ring: .PP .CS button .before -text "Before" button .middle -text "Middle" button .after -text "After" checkbutton .flag -variable traverseToMiddle -takefocus 0 pack .flag -side left pack .before .middle .after bind .before { if {!$traverseToMiddle} { \fBfocus\fR .after break } } bind .after { if {!$traverseToMiddle} { \fBfocus\fR .before break } } \fBfocus\fR .before .CE .SH KEYWORDS events, focus, keyboard, top-level, window manager '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/focusNext.n0000644001000000100000000000464115105057705017756 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk_focusNext n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_focusNext, tk_focusPrev, tk_focusFollowsMouse \- Utility procedures for managing the input focus. .SH SYNOPSIS .nf \fBtk_focusNext \fIwindow\fR \fBtk_focusPrev \fIwindow\fR \fBtk_focusFollowsMouse\fR .fi .BE .SH DESCRIPTION .PP \fBtk_focusNext\fR is a utility procedure used for keyboard traversal. It returns the .QW next window after \fIwindow\fR in focus order. The focus order is determined by the stacking order of windows and the structure of the window hierarchy. Among siblings, the focus order is the same as the stacking order, with the lowest window being first. If a window has children, the window is visited first, followed by its children (recursively), followed by its next sibling. Top-level windows other than \fIwindow\fR are skipped, so that \fBtk_focusNext\fR never returns a window in a different top-level from \fIwindow\fR. .PP After computing the next window, \fBtk_focusNext\fR examines the window's \fB\-takefocus\fR option to see whether it should be skipped. If so, \fBtk_focusNext\fR continues on to the next window in the focus order, until it eventually finds a window that will accept the focus or returns back to \fIwindow\fR. .PP \fBtk_focusPrev\fR is similar to \fBtk_focusNext\fR except that it returns the window just before \fIwindow\fR in the focus order. .PP \fBtk_focusFollowsMouse\fR changes the focus model for the application to an implicit one where the window under the mouse gets the focus. After this procedure is called, whenever the mouse enters a window Tk will automatically give it the input focus. The \fBfocus\fR command may be used to move the focus to a window other than the one under the mouse, but as soon as the mouse moves into a new window the focus will jump to that window. .PP Note that at present there is no built-in support for returning the application to an explicit focus model; to do this you will have to write a script that deletes the bindings created by \fBtk_focusFollowsMouse\fR. .SH KEYWORDS focus, keyboard traversal, top-level '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/font.n0000644001000000100000000004006015076161056016743 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1996 Sun Microsystems, Inc. '\" Copyright (c) 2006-2007 Daniel A. Steffen '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH font n 8.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME font \- Create and inspect fonts. .SH SYNOPSIS \fBfont\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBfont\fR command provides several facilities for dealing with fonts, such as defining named fonts and inspecting the actual attributes of a font. The command has several different forms, determined by the first argument. The following forms are currently supported: .\" METHOD: actual .TP \fBfont actual \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? ?\fB\-\|\-\fR? ?\fIchar\fR? . Returns information about the actual attributes that are obtained when \fIfont\fR is used on \fIwindow\fR's display; the actual attributes obtained may differ from the attributes requested due to platform-dependent limitations, such as the availability of font families and point sizes. \fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR argument is omitted, it defaults to the main window. If \fIoption\fR is specified, returns the value of that attribute; if it is omitted, the return value is a list of all the attributes and their values. See \fBFONT OPTIONS\fR below for a list of the possible attributes. If the \fIchar\fR argument is supplied, it must be a single character. The font attributes returned will be those of the specific font used to render that character, which will be different from the base font if the base font does not contain the given character. If \fIchar\fR may be a hyphen, it should be preceded by \fB\-\|\-\fR to distinguish it from a misspelled \fIoption\fR. .\" METHOD: configure .TP \fBfont configure \fIfontname\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the desired attributes for the named font called \fIfontname\fR. If no \fIoption\fR is specified, returns a list describing all the options and their values for \fIfontname\fR. If a single \fIoption\fR is specified with no \fIvalue\fR, then returns the current value of that attribute. If one or more \fIoption\fR\-\fIvalue\fR pairs are specified, then the command modifies the given named font to have the given values; in this case, all widgets using that font will redisplay themselves using the new attributes for the font. See \fBFONT OPTIONS\fR below for a list of the possible attributes. .RS .PP Note that on Aqua/macOS, the system fonts (see \fBPLATFORM SPECIFIC FONTS\fR below) may not be actually altered because they are implemented by the system theme. To achieve the effect of modification, use \fBfont actual\fR to get their configuration and \fBfont create\fR to synthesize a copy of the font which can be modified. .RE .\" METHOD: create .TP \fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? . Creates a new named font and returns its name. \fIfontname\fR specifies the name for the font; if it is omitted, then Tk generates a new name of the form \fBfont\fIx\fR, where \fIx\fR is an integer. There may be any number of \fIoption\fR\-\fIvalue\fR pairs, which provide the desired attributes for the new named font. See \fBFONT OPTIONS\fR below for a list of the possible attributes. .\" METHOD: delete .TP \fBfont delete\fI fontname\fR ?\fIfontname ...\fR? . Delete the specified named fonts. If there are widgets using the named font, the named font will not actually be deleted until all the instances are released. Those widgets will continue to display using the last known values for the named font. If a deleted named font is subsequently recreated with another call to \fBfont create\fR, the widgets will use the new named font and redisplay themselves using the new attributes of that font. .\" METHOD: families .TP \fBfont families\fR ?\fB\-displayof \fIwindow\fR? . The return value is a list of the case-insensitive names of all font families that exist on \fIwindow\fR's display. If the \fIwindow\fR argument is omitted, it defaults to the main window. .\" METHOD: measure .TP \fBfont measure \fIfont\fR ?\fB\-displayof \fIwindow\fR? \fItext\fR . Measures the amount of space the string \fItext\fR would use in the given \fIfont\fR when displayed in \fIwindow\fR. \fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR argument is omitted, it defaults to the main window. The return value is the total width in pixels of \fItext\fR, not including the extra pixels used by highly exaggerated characters such as cursive .QW f . If the string contains newlines or tabs, those characters are not expanded or treated specially when measuring the string. .\" METHOD: metrics .TP \fBfont metrics \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? . Returns information about the metrics (the font-specific data), for \fIfont\fR when it is used on \fIwindow\fR's display. \fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below. If the \fIwindow\fR argument is omitted, it defaults to the main window. If \fIoption\fR is specified, returns the value of that metric; if it is omitted, the return value is a list of all the metrics and their values. See \fBFONT METRICS\fR below for a list of the possible metrics. .\" METHOD: names .TP \fBfont names\fR . The return value is a list of all the named fonts that are currently defined. .SH "FONT DESCRIPTIONS" .PP The following formats are accepted as a font description anywhere \fIfont\fR is specified as an argument above; these same forms are also permitted when specifying the \fB\-font\fR option for widgets. .TP [1] \fIfontname\fR . The name of a named font, created using the \fBfont create\fR command. When a widget uses a named font, it is guaranteed that this will never cause an error, as long as the named font exists, no matter what potentially invalid or meaningless set of attributes the named font has. If the named font cannot be displayed with exactly the specified attributes, some other close font will be substituted automatically. .TP [2] \fIsystemfont\fR . The platform-specific name of a font, interpreted by the graphics server. This also includes, under X, an XLFD (see [4]) for which a single .QW \fB*\fR character was used to elide more than one field in the middle of the name. See \fBPLATFORM SPECIFIC FONTS\fR for a list of the system fonts. .TP [3] \fIfamily \fR?\fIsize\fR? ?\fIstyle\fR? ?\fIstyle ...\fR? . A properly formed list whose first element is the desired font \fIfamily\fR and whose optional second element is the desired \fIsize\fR. The interpretation of the \fIsize\fR attribute follows the same rules described for \fB\-size\fR in \fBFONT OPTIONS\fR below. Any additional optional arguments following the \fIsize\fR are font \fIstyle\fRs. Possible values for the \fIstyle\fR arguments are as follows: .RS .DS .ta 3c 6c 9c \fBnormal\fR \fBbold\fR \fBroman\fR \fBitalic\fR \fBunderline\fR \fBoverstrike\fR .DE .RE .TP [4] X-font names (XLFD) . A Unix-centric font name of the form \fI\-foundry\-family\-weight\-slant\-setwidth\-addstyle\-pixel\-point\-resx\-resy\-spacing\-width\-charset\-encoding\fR. The .QW \fB*\fR character may be used to skip individual fields that the user does not care about. There must be exactly one .QW \fB*\fR for each field skipped, except that a .QW \fB*\fR at the end of the XLFD skips any remaining fields; the shortest valid XLFD is simply .QW \fB*\fR , signifying all fields as defaults. Any fields that were skipped are given default values. For compatibility, an XLFD always chooses a font of the specified pixel size (not point size); although this interpretation is not strictly correct, all existing applications using XLFDs assumed that one .QW point was in fact one pixel and would display incorrectly (generally larger) if the correct size font were actually used. .TP [5] \fIoption value \fR?\fIoption value ...\fR? . A properly formed list of \fIoption\fR\-\fIvalue\fR pairs that specify the desired attributes of the font, in the same format used when defining a named font; see \fBFONT OPTIONS\fR below. .LP When font description \fIfont\fR is used, the system attempts to parse the description according to each of the above five rules, in the order specified. Cases [1] and [2] must match the name of an existing named font or of a system font. Cases [3], [4], and [5] are accepted on all platforms and the closest available font will be used. In some situations it may not be possible to find any close font (e.g., the font family was a garbage value); in that case, some system-dependent default font is chosen. If the font description does not match any of the above patterns, an error is generated. .SH "FONT METRICS" .PP The following options are used by the \fBfont metrics\fR command to query font-specific data determined when the font was created. These properties are for the whole font itself and not for individual characters drawn in that font. In the following definitions, the .QW baseline of a font is the horizontal line where the bottom of most letters line up; certain letters, such as lower-case .QW g stick below the baseline. .\" OPTION: -ascent .TP \fB\-ascent\fR . The amount in pixels that the tallest letter sticks up above the baseline of the font, plus any extra blank space added by the designer of the font. .\" OPTION: -descent .TP \fB\-descent\fR . The largest amount in pixels that any letter sticks down below the baseline of the font, plus any extra blank space added by the designer of the font. .\" OPTION: -linespace .TP \fB\-linespace\fR . Returns how far apart vertically in pixels two lines of text using the same font should be placed so that none of the characters in one line overlap any of the characters in the other line. This is generally the sum of the ascent above the baseline line plus the descent below the baseline. .\" OPTION: -fixed .TP \fB\-fixed\fR . Returns a boolean flag that is .QW \fB1\fR if this is a fixed-width font, where each normal character is the same width as all the other characters, or is .QW \fB0\fR if this is a proportionally-spaced font, where individual characters have different widths. The widths of control characters, tab characters, and other non-printing characters are not included when calculating this value. .SH "FONT OPTIONS" .PP The following options are supported on all platforms, and are used when constructing a named font or when specifying a font using style [5] as above: .\" OPTION: -family .TP \fB\-family \fIname\fR . The case-insensitive font family name. Tk guarantees to support the font families named \fBCourier\fR (a monospaced .QW typewriter font), \fBTimes\fR (a serifed .QW newspaper font), and \fBHelvetica\fR (a sans-serif .QW European font). The most closely matching native font family will automatically be substituted when one of the above font families is used. The \fIname\fR may also be the name of a native, platform-specific font family; in that case it will work as desired on one platform but may not display correctly on other platforms. If the family is unspecified or unrecognized, a platform-specific default font will be chosen. .\" OPTION: -size .TP \fB\-size \fIsize\fR . The desired size of the font. If the \fIsize\fR argument is a positive number, it is interpreted as a size in points. If \fIsize\fR is a negative number, its absolute value is interpreted as a size in pixels. If a font cannot be displayed at the specified size, a nearby size will be chosen. If \fIsize\fR is unspecified or zero, a platform-dependent default size will be chosen. .RS .PP Sizes should normally be specified in points so the application will remain the same ruler size on the screen, even when changing screen resolutions or moving scripts across platforms. However, specifying pixels is useful in certain circumstances such as when a piece of text must line up with respect to a fixed-size bitmap. The mapping between points and pixels is set when the application starts, based on properties of the installed monitor, but it can be overridden by calling the \fBtk scaling\fR command. .RE .\" OPTION: -weight .TP \fB\-weight \fIweight\fR . The nominal thickness of the characters in the font. The value \fBnormal\fR specifies a normal weight font, while \fBbold\fR specifies a bold font. The closest available weight to the one specified will be chosen. The default weight is \fBnormal\fR. .\" OPTION: -slant .TP \fB\-slant \fIslant\fR . The amount the characters in the font are slanted away from the vertical. Valid values for slant are \fBroman\fR and \fBitalic\fR. A roman font is the normal, upright appearance of a font, while an italic font is one that is tilted some number of degrees from upright. The closest available slant to the one specified will be chosen. The default slant is \fBroman\fR. .\" OPTION: -underline .TP \fB\-underline \fIboolean\fR . The value is a boolean flag that specifies whether characters in this font should be underlined. The default value for underline is \fBfalse\fR. .\" OPTION: -overstrike .TP \fB\-overstrike \fIboolean\fR . The value is a boolean flag that specifies whether a horizontal line should be drawn through the middle of characters in this font. The default value for overstrike is \fBfalse\fR. .SH "STANDARD FONTS" .PP The following named fonts are supported on all systems, and default to values that match appropriate system defaults. .IP \fBTkDefaultFont\fR This font is the default for all GUI items not otherwise specified. .IP \fBTkTextFont\fR This font should be used for user text in entry widgets, listboxes etc. .IP \fBTkFixedFont\fR This font is the standard fixed-width font. .IP \fBTkMenuFont\fR This font is used for menu items. .IP \fBTkHeadingFont\fR This font should be used for column headings in lists and tables. .IP \fBTkCaptionFont\fR This font should be used for window and dialog caption bars. .IP \fBTkSmallCaptionFont\fR This font should be used for captions on contained windows or tool dialogs. .IP \fBTkIconFont\fR This font should be used for icon captions. .IP \fBTkTooltipFont\fR This font should be used for tooltip windows (transient information windows). .LP It is \fInot\fR advised to change these fonts, as they may be modified by Tk itself in response to system changes. Instead, make a copy of the font and modify that. .SH "PLATFORM SPECIFIC FONTS" .PP The following system fonts are supported: .TP \fBX Windows\fR . All valid X font names, including those listed by xlsfonts(1), are available. .TP \fBMS Windows\fR . The following fonts are supported, and are mapped to the user's style defaults. .RS .DS .ta 3c 6c \fBsystem\fR \fBansi\fR \fBdevice\fR \fBsystemfixed\fR \fBansifixed\fR \fBoemfixed\fR .DE .RE .TP \fBmacOS\fR . The following fonts are supported, and are mapped to the user's style defaults. .RS .DS .ta 3c 6c \fBsystem\fR \fBapplication\fR \fBmenu\fR .DE .PP Additionally, the following named fonts provide access to the Aqua theme fonts: .DS .ta 5c \fBsystemSystemFont\fR \fBsystemEmphasizedSystemFont\fR \fBsystemSmallSystemFont\fR \fBsystemSmallEmphasizedSystemFont\fR \fBsystemApplicationFont\fR \fBsystemLabelFont\fR \fBsystemViewsFont\fR \fBsystemMenuTitleFont\fR \fBsystemMenuItemFont\fR \fBsystemMenuItemMarkFont\fR \fBsystemMenuItemCmdKeyFont\fR \fBsystemWindowTitleFont\fR \fBsystemPushButtonFont\fR \fBsystemUtilityWindowTitleFont\fR \fBsystemAlertHeaderFont\fR \fBsystemToolbarFont\fR \fBsystemMiniSystemFont\fR \fBsystemDetailSystemFont\fR \fBsystemDetailEmphasizedSystemFont\fR .DE .RE .SH EXAMPLE .PP Fill a text widget with lots of font demonstrators, one for every font family installed on your system: .CS pack [text .t -wrap none] -fill both -expand 1 set count 0 set tabwidth 0 foreach family [lsort -dictionary [\fBfont families\fR]] { .t tag configure f[incr count] -font [list $family 10] .t insert end ${family}:\et {} \e "This is a simple sampler\en" f$count set w [\fBfont measure\fR [.t cget -font] ${family}:] if {$w + 5 > $tabwidth} { set tabwidth [expr {$w + 5}] .t configure -tabs $tabwidth } } .CE .SH "SEE ALSO" options(n) .SH KEYWORDS font '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/fontchooser.n0000644001000000100000000001746615076161056020344 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2008 Daniel A. Steffen '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH fontchooser n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME fontchooser \- control font selection dialog .SH SYNOPSIS .nf \fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value ...\fR? \fBtk fontchooser\fR \fBshow\fR \fBtk fontchooser\fR \fBhide\fR .fi .BE .SH DESCRIPTION .PP The \fBtk fontchooser\fR command controls the Tk font selection dialog. It uses the native platform font selection dialog where available, or a dialog implemented in Tcl otherwise. .PP Unlike most of the other Tk dialog commands, \fBtk fontchooser\fR does not return an immediate result, as on some platforms (macOS) the standard font dialog is modeless while on others (Windows) it is modal. To accommodate this difference, all user interaction with the dialog will be communicated to the caller via callbacks or virtual events. .PP The \fBtk fontchooser\fR command can have one of the following forms: .\" METHOD: configure .TP \fBtk fontchooser\fR \fBconfigure \fR?\fI\-option value ...\fR? . Set or query one or more of the configurations options below (analogous to Tk widget configuration). .\" METHOD: show .TP \fBtk fontchooser\fR \fBshow\fR . Show the font selection dialog. Depending on the platform, may return immediately or only once the dialog has been withdrawn. .\" METHOD: hide .TP \fBtk fontchooser\fR \fBhide\fR . Hide the font selection dialog if it is visible and cause any pending \fBtk fontchooser\fR \fBshow\fR command to return. .PP .SH "CONFIGURATION OPTIONS" .\" OPTION: -parent .TP \fB\-parent\fR . Specifies/returns the logical parent window of the font selection dialog (similar to the \fB\-parent\fR option to other dialogs). The font selection dialog is hidden if it is visible when the parent window is destroyed. .\" OPTION: -title .TP \fB\-title\fR . Specifies/returns the title of the dialog. Has no effect on platforms where the font selection dialog does not support titles. .\" OPTION: -font .TP \fB\-font\fR . Specifies/returns the font that is currently selected in the dialog if it is visible, or that will be initially selected when the dialog is shown (if supported by the platform). Can be set to the empty string to indicate that no font should be selected. Fonts can be specified in any form given by the "FONT DESCRIPTION" section in the \fBfont\fR manual page. .\" OPTION: -command .TP \fB\-command\fR . Specifies/returns the command prefix to be called when a font selection has been made by the user. The command prefix is evaluated at the global level after having the specification of the selected font appended. On platforms where the font selection dialog offers the user control of further font attributes (such as color), additional key/value pairs may be appended before evaluation. Can be set to the empty string to indicate that no callback should be invoked. Fonts are specified by a list of form [3] of the "FONT DESCRIPTION" section in the \fBfont\fR manual page (i.e. a list of the form \fI{family size style ?style ...?}\fR). .\" OPTION: -visible .TP \fB\-visible\fR . Read-only option that returns a boolean indicating whether the font selection dialog is currently visible. Attempting to set this option results in an error. .PP .SH "VIRTUAL EVENTS" .TP \fB<>\fR . Sent to the dialog parent whenever the visibility of the font selection dialog changes, both as a result of user action (e.g. disposing of the dialog via OK/Cancel button or close box) and of the \fBtk fontchooser\fR \fBshow\fR/\fBhide\fR commands being called. Binding scripts can determine the current visibility of the dialog by querying the \fB\-visible\fR configuration option. .TP \fB<>\fR . Sent to the dialog parent whenever the font selection dialog is visible and the selected font changes, both as a result of user action and of the \fB\-font\fR configuration option being set. Binding scripts can determine the currently selected font by querying the \fB\-font\fR configuration option. .PP .SH NOTES .PP Callers should not expect a result from \fBtk fontchooser\fR \fBshow\fR and may not assume that the dialog has been withdrawn or closed when the command returns. All user interaction with the dialog is communicated to the caller via the \fB\-command\fR callback and the \fB<>\fR virtual events. It is implementation dependent which exact user actions result in the callback being called resp. the virtual events being sent. Where an Apply or OK button is present in the dialog, that button will trigger the \fB\-command\fR callback and \fB<>\fR virtual event. On some implementations other user actions may also have that effect; on macOS for instance, the standard font selection dialog immediately reflects all user choices to the caller. .PP In the presence of multiple widgets intended to be influenced by the font selection dialog, care needs to be taken to correctly handle focus changes: the font selected in the dialog should always match the current font of the widget with the focus, and the \fB\-command\fR callback should only act on the widget with the focus. The recommended practice is to set font dialog \fB\-font\fR and \fB\-command\fR configuration options in per\-widget \fB\fR handlers (and if necessary to unset them \- i.e. set to the empty string \- in corresponding \fB\fR handlers). This is particularly important for implementers of library code using the font selection dialog, to avoid conflicting with application code that may also want to use the dialog. .PP Because the font selection dialog is application-global, in the presence of multiple interpreters calling \fBtk fontchooser\fR, only the \fB\-command\fR callback set by the interpreter that most recently called \fBtk fontchooser\fR \fBconfigure\fR or \fBtk fontchooser\fR \fBshow\fR will be invoked in response to user action and only the \fB\-parent\fR set by that interpreter will receive \fB<>\fR virtual events. .PP The font dialog implementation may only store (and return) \fBfont\fR \fBactual\fR data as the value of the \fB\-font\fR configuration option. This can be an issue when \fB\-font\fR is set to a named font, if that font is subsequently changed, the font dialog \fB\-font\fR option needs to be set again to ensure its selected font matches the new value of the named font. .PP .SH EXAMPLE .PP .CS proc fontchooserDemo {} { wm title . "Font Chooser Demo" \fBtk fontchooser\fR \fBconfigure\fR -parent . button .b -command fontchooserToggle -takefocus 0 fontchooserVisibility .b bind . \fB<>\fR \e [list fontchooserVisibility .b] foreach w {.t1 .t2} { text $w -width 20 -height 4 -borderwidth 1 -relief solid bind $w [list fontchooserFocus $w] $w insert end "Text Widget $w" } .t1 configure -font {Courier 14} .t2 configure -font {Times 16} pack .b .t1 .t2; focus .t1 } proc fontchooserToggle {} { \fBtk fontchooser\fR [expr { [\fBtk fontchooser\fR \fBconfigure\fR -visible] ? "\fBhide\fR" : "\fBshow\fR"}] } proc fontchooserVisibility {w} { $w configure -text [expr { [\fBtk fontchooser\fR \fBconfigure\fR -visible] ? "Hide Font Dialog" : "Show Font Dialog"}] } proc fontchooserFocus {w} { \fBtk fontchooser\fR \fBconfigure\fR -font [$w cget -font] \e -command [list fontchooserFontSelection $w] } proc fontchooserFontSelection {w font args} { $w configure -font [font actual $font] } fontchooserDemo .CE .SH "SEE ALSO" font(n), tk(n) .SH KEYWORDS dialog, font, font selection, font chooser, font panel '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/FontId.30000644001000000100000000000662615105057705017075 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_FontId 3 8.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for fonts .SH SYNOPSIS .nf \fB#include \fR .sp Font \fBTk_FontId\fR(\fItkfont\fR) .sp \fBTk_GetFontMetrics\fR(\fItkfont, fmPtr\fR) .sp int \fBTk_PostscriptFontName\fR(\fItkfont, dsPtr\fR) .fi .SH ARGUMENTS .AS Tk_FontMetrics *dsPtr .AP Tk_Font tkfont in Opaque font token being queried. Must have been returned by a previous call to \fBTk_GetFont\fR. .AP Tk_FontMetrics *fmPtr out Pointer to structure in which the font metrics for \fItkfont\fR will be stored. See \fBDATA STRUCTURES\fR below for details. .AP Tcl_DString *dsPtr out Pointer to an initialized \fBTcl_DString\fR to which the name of the Postscript font that corresponds to \fItkfont\fR will be appended. .BE .SH DESCRIPTION .PP Given a \fItkfont\fR, \fBTk_FontId\fR returns the token that should be selected into an XGCValues structure in order to construct a graphics context that can be used to draw text in the specified font. .PP \fBTk_GetFontMetrics\fR computes the ascent, descent, and linespace of the \fItkfont\fR in pixels and stores those values in the structure pointer to by \fIfmPtr\fR. These values can be used in computations such as to space multiple lines of text, to align the baselines of text in different fonts, and to vertically align text in a given region. See the documentation for the \fBfont\fR command for definitions of the terms ascent, descent, and linespace, used in font metrics. .PP \fBTk_PostscriptFontName\fR maps a \fItkfont\fR to the corresponding Postscript font name that should be used when printing. The return value is the size in points of the \fItkfont\fR and the Postscript font name is appended to \fIdsPtr\fR. \fIDsPtr\fR must refer to an initialized \fBTcl_DString\fR. Given a .QW reasonable Postscript printer, the following screen font families should print correctly: .IP \fBAvant Garde\fR, \fBArial\fR, \fBBookman\fR, \fBCourier\fR, \fBCourier New\fR, \fBGeneva\fR, \fBHelvetica\fR, \fBMonaco\fR, \fBNew Century Schoolbook\fR, \fBNew York\fR, \fBPalatino\fR, \fBSymbol\fR, \fBTimes\fR, \fBTimes New Roman\fR, \fBZapf Chancery\fR, and \fBZapf Dingbats\fR. .PP Any other font families may not print correctly because the computed Postscript font name may be incorrect or not exist on the printer. .SH "DATA STRUCTURES" .PP The \fBTk_FontMetrics\fR data structure is used by \fBTk_GetFontMetrics\fR to return information about a font and is defined as follows: .CS typedef struct { int \fIascent\fR; int \fIdescent\fR; int \fIlinespace\fR; } \fBTk_FontMetrics\fR; .CE .PP The \fIascent\fR field is the amount in pixels that the tallest letter sticks up above the baseline, plus any extra blank space added by the designer of the font. .PP The \fIdescent\fR is the largest amount in pixels that any letter sticks below the baseline, plus any extra blank space added by the designer of the font. .PP The \fIlinespace\fR is the sum of the ascent and descent. How far apart two lines of text in the same font should be placed so that none of the characters in one line overlap any of the characters in the other line. .SH "SEE ALSO" font(n), MeasureChar(3) .SH KEYWORDS font, measurement, Postscript tk9.0.3/doc/frame.n0000644001000000100000000001600015105057705017062 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH frame n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME frame \- Create and manipulate 'frame' simple container widgets .SH SYNOPSIS \fBframe\fI pathName\fR ?\fIoptions\fR? .SO \-borderwidth \-highlightcolor \-pady \-cursor \-highlightthickness \-relief \-highlightbackground \-padx \-takefocus .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-background background Background This option is the same as the standard \fB\-background\fR option except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border. .VS "9.0, TIP262" An empty background will disable drawing the background image. .OP \-backgroundimage backgroundImage BackgroundImage This specifies an image to display on the frame's background within the border of the frame (i.e., the image will be clipped by the frame's highlight ring and border, if either are present); subwidgets of the frame will be drawn on top. The image must have been created with the \fBimage create\fR command. If specified as the empty string, no image will be displayed. .VE "9.0, TIP262" .OP \-class class Class Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. The \fB\-class\fR option may not be changed with the \fBconfigure\fR widget command. .OP \-colormap colormap Colormap Specifies a colormap to use for the window. The value may be either \fBnew\fR, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as \fIpathName\fR), in which case the new window will use the colormap from the specified window. If the \fB\-colormap\fR option is not specified, the new window uses the same colormap as its parent. This option may not be changed with the \fBconfigure\fR widget command. .OP \-container container Container The value must be a boolean. If true, it means that this window will be used as a container in which some other application will be embedded (for example, a Tk toplevel can be embedded using the \fB\-use\fR option). The window will support the appropriate window manager protocols for things like geometry requests. The window should not have any children of its own in this application. This option may not be changed with the \fBconfigure\fR widget command. Note that \fB\-borderwidth\fR, \fB\-padx\fR and \fB\-pady\fR are ignored when configured as a container since a container has no border. .OP \-height height Height Specifies the desired height for the window in any of the forms acceptable to \fBTk_GetPixels\fR. If this option is negative or zero then the window will not request any size at all. Note that this sets the total height of the frame, any \fB\-borderwidth\fR or similar is not added. Normally \fB\-height\fR should not be used if a propagating geometry manager, such as \fBgrid\fR or \fBpack\fR, is used within the frame since the geometry manager will override the height of the frame. .OP \-tile tile Tile .VS "9.0, TIP262" This specifies how to draw the background image (see \fB\-backgroundimage\fR) on the frame. If true (according to \fBTcl_GetBoolean\fR), the image will be tiled to fill the whole frame, with the origin of the first copy of the image being the top left of the interior of the frame. If false (the default), the image will be centered within the frame. .VE "9.0, TIP262" .OP \-visual visual Visual Specifies visual information for the new window in any of the forms accepted by \fBTk_GetVisual\fR. If this option is not specified, the new window will use the same visual as its parent. The \fB\-visual\fR option may not be modified with the \fBconfigure\fR widget command. .OP \-width width Width Specifies the desired width for the window in any of the forms acceptable to \fBTk_GetPixels\fR. If this option is negative or zero then the window will not request any size at all. Note that this sets the total width of the frame, any \fB\-borderwidth\fR or similar is not added. Normally \fB\-width\fR should not be used if a propagating geometry manager, such as \fBgrid\fR or \fBpack\fR, is used within the frame since the geometry manager will override the width of the frame. .BE .SH DESCRIPTION .PP The \fBframe\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a frame widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the frame such as its background color and relief. The \fBframe\fR command returns the path name of the new window. .PP A frame is a simple widget. Its primary purpose is to act as a spacer or container for complex window layouts. The only features of a frame are its background and an optional 3-D border to make the frame appear raised or sunken. .SH "WIDGET COMMAND" .PP The \fBframe\fR command creates a new Tcl command whose name is the same as the path name of the frame's window. This command may be used to invoke various operations on the widget. It has the following general form: .PP .CS \fIpathName option \fR?\fIarg ...\fR? .CE .PP \fIPathName\fR is the name of the command, which is the same as the frame widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for frame widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBframe\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBframe\fR command. .SH BINDINGS .PP When a new frame is created, it has no default event bindings: frames are not intended to be interactive. .SH "SEE ALSO" labelframe(n), toplevel(n), ttk::frame(n) .SH KEYWORDS frame, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/GeomReq.30000644001000000100000000001002015105057705017230 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GeometryRequest 3 "8.4" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GeometryRequest, Tk_SetMinimumRequestSize, Tk_SetInternalBorder, Tk_SetInternalBorderEx \- specify desired geometry or internal border for a window .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_GeometryRequest\fR(\fItkwin, reqWidth, reqHeight\fR) .sp \fBTk_SetMinimumRequestSize\fR(\fItkwin, minWidth, minHeight\fR) .sp \fBTk_SetInternalBorder\fR(\fItkwin, width\fR) .sp \fBTk_SetInternalBorderEx\fR(\fItkwin, left, right, top, bottom\fR) .fi .SH ARGUMENTS .AS baseHeight clientData .AP Tk_Window tkwin in Window for which geometry is being requested. .AP int reqWidth in Desired width for \fItkwin\fR, in pixel units. .AP int reqHeight in Desired height for \fItkwin\fR, in pixel units. .AP int minWidth in Desired minimum requested width for \fItkwin\fR, in pixel units. .AP int minHeight in Desired minimum requested height for \fItkwin\fR, in pixel units. .AP int width in Space to leave for internal border for \fItkwin\fR, in pixel units. .AP int left in Space to leave for left side of internal border for \fItkwin\fR, in pixel units. .AP int right in Space to leave for right side of internal border for \fItkwin\fR, in pixel units. .AP int top in Space to leave for top side of internal border for \fItkwin\fR, in pixel units. .AP int bottom in Space to leave for bottom side of internal border for \fItkwin\fR, in pixel units. .BE .SH DESCRIPTION .PP \fBTk_GeometryRequest\fR is called by widget code to indicate its preference for the dimensions of a particular window. The arguments to \fBTk_GeometryRequest\fR are made available to the geometry manager for the window, which then decides on the actual geometry for the window. Although geometry managers generally try to satisfy requests made to \fBTk_GeometryRequest\fR, there is no guarantee that this will always be possible. Widget code should not assume that a geometry request will be satisfied until it receives a \fBConfigureNotify\fR event indicating that the geometry change has occurred. Widget code should never call procedures like \fBTk_ResizeWindow\fR directly. Instead, it should invoke \fBTk_GeometryRequest\fR and leave the final geometry decisions to the geometry manager. .PP If \fItkwin\fR is a top-level window, then the geometry information will be passed to the window manager using the standard ICCCM protocol. .PP \fBTk_SetInternalBorder\fR is called by widget code to indicate that the widget has an internal border. This means that the widget draws a decorative border inside the window instead of using the standard X borders, which are external to the window's area. For example, internal borders are used to draw 3-D effects. \fIWidth\fR specifies the width of the border in pixels. Geometry managers will use this information to avoid placing any children of \fItkwin\fR overlapping the outermost \fIwidth\fR pixels of \fItkwin\fR's area. .PP \fBTk_SetInternalBorderEx\fR works like \fBTk_SetInternalBorder\fR but lets you specify different widths for different sides of the window. .PP \fBTk_SetMinimumRequestSize\fR is called by widget code to indicate that a geometry manager should request at least this size for the widget. This allows a widget to have some control over its size when a propagating geometry manager is used inside it. .PP The information specified in calls to \fBTk_GeometryRequest\fR, \fBTk_SetMinimumRequestSize\fR, \fBTk_SetInternalBorder\fR and \fBTk_SetInternalBorderEx\fR can be retrieved using the macros \fBTk_ReqWidth\fR, \fBTk_ReqHeight\fR, \fBTk_MinReqWidth\fR, \fBTk_MinReqHeight\fR, \fBTk_MinReqWidth\fR, \fBTk_InternalBorderLeft\fR, \fBTk_InternalBorderRight\fR, \fBTk_InternalBorderTop\fR and \fBTk_InternalBorderBottom\fR. See the \fBTk_WindowId\fR manual entry for details. .SH KEYWORDS geometry, request tk9.0.3/doc/GetAnchor.30000644001000000100000000000615115105057705017555 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetAnchorFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_GetAnchorFromObj\fR(\fIinterp, objPtr, anchorPtr\fR) .sp int \fBTk_GetAnchor\fR(\fIinterp, string, anchorPtr\fR) .sp const char * \fBTk_NameOfAnchor\fR(\fIanchor\fR) .fi .SH ARGUMENTS .AS "Tk_Anchor" *anchorPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting, or NULL. .AP Tcl_Obj *objPtr in/out String value contains name of anchor point: .QW \fBn\fR , .QW \fBne\fR , .QW \fBe\fR , .QW \fBse\fR , .QW \fBs\fR , .QW \fBsw\fR , .QW \fBw\fR , .QW \fBnw\fR , or .QW \fBcenter\fR ; internal rep will be modified to cache corresponding Tk_Anchor. In the case of .QW \fBcenter\fR on input, a non-empty abbreviation of it may also be used on input. .AP "const char" *string in Same as \fIobjPtr\fR except description of anchor point is passed as a string. .AP int *anchorPtr out Pointer to location in which to store anchor position corresponding to \fIobjPtr\fR or \fIstring\fR. .AP Tk_Anchor anchor in Anchor position, e.g. \fBTCL_ANCHOR_CENTER\fR. .BE .SH DESCRIPTION .PP \fBTk_GetAnchorFromObj\fR places in \fI*anchorPtr\fR an anchor position (enumerated type \fBTk_Anchor\fR) corresponding to \fIobjPtr\fR's value. The result will be one of \fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR, \fBTK_ANCHOR_E\fR, \fBTK_ANCHOR_SE\fR, \fBTK_ANCHOR_S\fR, \fBTK_ANCHOR_SW\fR, \fBTK_ANCHOR_W\fR, \fBTK_ANCHOR_NW\fR, or \fBTK_ANCHOR_CENTER\fR. Anchor positions are typically used for indicating a point on an object that will be used to position the object, e.g. \fBTK_ANCHOR_N\fR means position the top center point of the object at a particular place. .PP Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. If \fIstring\fR does not contain a valid anchor position or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned, \fI*anchorPtr\fR is unmodified, and an error message is stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. \fBTk_GetAnchorFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetAnchorFromObj\fR with the same \fIobjPtr\fR. .PP \fBTk_GetAnchor\fR is identical to \fBTk_GetAnchorFromObj\fR except that the description of the anchor is specified with a string instead of an object. This prevents \fBTk_GetAnchor\fR from caching the return value, so \fBTk_GetAnchor\fR is less efficient than \fBTk_GetAnchorFromObj\fR. .PP \fBTk_NameOfAnchor\fR is the logical inverse of \fBTk_GetAnchor\fR. Given an anchor position such as \fBTK_ANCHOR_N\fR it returns a statically-allocated string corresponding to \fIanchor\fR. If \fIanchor\fR is not a legal anchor value, then .QW "unknown anchor position" is returned. .SH KEYWORDS anchor position tk9.0.3/doc/GetBitmap.30000644001000000100000000002375115105057705017564 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps .SH SYNOPSIS .nf \fB#include \fR .sp Pixmap \fBTk_AllocBitmapFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp Pixmap \fBTk_GetBitmap\fR(\fIinterp, tkwin, info\fR) .sp Pixmap \fBTk_GetBitmapFromObj\fR(\fItkwin, objPtr\fR) .sp int \fBTk_DefineBitmap\fR(\fIinterp, name, source, width, height\fR) .sp const char * \fBTk_NameOfBitmap\fR(\fIdisplay, bitmap\fR) .sp \fBTk_SizeOfBitmap\fR(\fIdisplay, bitmap, widthPtr, heightPtr\fR) .sp \fBTk_FreeBitmapFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_FreeBitmap\fR(\fIdisplay, bitmap\fR) .fi .SH ARGUMENTS .AS "unsigned long" *pixelPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting; if NULL then no error message is left after errors. .AP Tk_Window tkwin in Token for window in which the bitmap will be used. .AP Tcl_Obj *objPtr in/out String value describes desired bitmap; internal rep will be modified to cache pointer to corresponding Pixmap. .AP "const char" *info in Same as \fIobjPtr\fR except description of bitmap is passed as a string and resulting Pixmap is not cached. .AP "const char" *name in Name for new bitmap to be defined. .AP "const void" *source in Data for bitmap, in standard bitmap format. Must be stored in static memory whose value will never change. .AP "int" width in Width of bitmap. .AP "int" height in Height of bitmap. .AP "int" *widthPtr out Pointer to word to fill in with \fIbitmap\fR's width. .AP "int" *heightPtr out Pointer to word to fill in with \fIbitmap\fR's height. .AP Display *display in Display for which \fIbitmap\fR was allocated. .AP Pixmap bitmap in Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. .BE .SH DESCRIPTION .PP These procedures manage a collection of bitmaps (one-plane pixmaps) being used by an application. The procedures allow bitmaps to be re-used efficiently, thereby avoiding server overhead, and also allow bitmaps to be named with character strings. .PP \fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap that matches the description in \fIobjPtr\fR and is suitable for use in \fItkwin\fR. It re-uses an existing bitmap, if possible, and creates a new one otherwise. \fIObjPtr\fR's value must have one of the following forms: .TP 20 \fB@\fIfileName\fR . \fIFileName\fR must be the name of a file containing a bitmap description in the standard X11 format. .TP 20 \fIname\fR . \fIName\fR must be the name of a bitmap defined previously with a call to \fBTk_DefineBitmap\fR. The following names are pre-defined by Tk: .RS .IP \fBerror\fR 12 The international .QW don't symbol: a circle with a diagonal line across it. .IP \fBgray75\fR 12 75% gray: a checkerboard pattern where three out of four bits are on. .IP \fBgray50\fR 12 50% gray: a checkerboard pattern where every other bit is on. .IP \fBgray25\fR 12 25% gray: a checkerboard pattern where one out of every four bits is on. .IP \fBgray12\fR 12 12.5% gray: a pattern where one-eighth of the bits are on, consisting of every fourth pixel in every other row. .IP \fBhourglass\fR 12 An hourglass symbol. .IP \fBinfo\fR 12 A large letter .QW i . .IP \fBquesthead\fR 12 The silhouette of a human head, with a question mark in it. .IP \fBquestion\fR 12 A large question-mark. .IP \fBwarning\fR 12 A large exclamation point. .PP In addition, the following pre-defined names are available only on the \fBMacintosh\fR platform: .IP \fBdocument\fR 12 A generic document. .IP \fBstationery\fR 12 Document stationery. .IP \fBedition\fR 12 The \fIedition\fR symbol. .IP \fBapplication\fR 12 Generic application icon. .IP \fBaccessory\fR 12 A desk accessory. .IP \fBfolder\fR 12 Generic folder icon. .IP \fBpfolder\fR 12 A locked folder. .IP \fBtrash\fR 12 A trash can. .IP \fBfloppy\fR 12 A floppy disk. .IP \fBramdisk\fR 12 A floppy disk with chip. .IP \fBcdrom\fR 12 A cd disk icon. .IP \fBpreferences\fR 12 A folder with prefs symbol. .IP \fBquerydoc\fR 12 A database document icon. .IP \fBstop\fR 12 A stop sign. .IP \fBnote\fR 12 A face with balloon words. .IP \fBcaution\fR 12 A triangle with an exclamation point. .RE .LP Under normal conditions, \fBTk_AllocBitmapFromObj\fR returns an identifier for the requested bitmap. If an error occurs in creating the bitmap, such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR is returned and an error message is left in \fIinterp\fR's result if \fIinterp\fR is not NULL. \fBTk_AllocBitmapFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to procedures such as \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmapFromObj\fR. .PP \fBTk_GetBitmap\fR is identical to \fBTk_AllocBitmapFromObj\fR except that the description of the bitmap is specified with a string instead of an object. This prevents \fBTk_GetBitmap\fR from caching the return value, so \fBTk_GetBitmap\fR is less efficient than \fBTk_AllocBitmapFromObj\fR. .PP \fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given the window and description used to create the bitmap. \fBTk_GetBitmapFromObj\fR does not actually create the bitmap; the bitmap must already have been created with a previous call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The return value is cached in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetBitmapFromObj\fR with the same \fIobjPtr\fR and \fItkwin\fR. .PP \fBTk_DefineBitmap\fR associates a name with in-memory bitmap data so that the name can be used in later calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The \fInameId\fR argument gives a name for the bitmap; it must not previously have been used in a call to \fBTk_DefineBitmap\fR. The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR describe the bitmap. \fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs (e.g. a bitmap named \fInameId\fR has already been defined) then \fBTCL_ERROR\fR is returned and an error message is left in interpreter \fIinterp\fR's result. Note that \fBTk_DefineBitmap\fR expects the memory pointed to by \fIsource\fR to be static: \fBTk_DefineBitmap\fR does not make a private copy of this memory, but uses the bytes pointed to by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. .PP Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a bitmap file directly into a C program and then referencing the variables defined by the file. For example, suppose there exists a file \fBstip.bitmap\fR, which was created by the \fBbitmap\fR program and contains a stipple pattern. The following code uses \fBTk_DefineBitmap\fR to define a new bitmap named \fBfoo\fR: .CS Pixmap bitmap; #include "stip.bitmap" Tk_DefineBitmap(interp, "foo", stip_bits, stip_width, stip_height); \&... bitmap = Tk_GetBitmap(interp, tkwin, "foo"); .CE This code causes the bitmap file to be read at compile-time and incorporates the bitmap information into the program's executable image. The same bitmap file could be read at run-time using \fBTk_GetBitmap\fR: .CS Pixmap bitmap; bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap"); .CE The second form is a bit more flexible (the file could be modified after the program has been compiled, or a different string could be provided to read a different file), but it is a little slower and requires the bitmap file to exist separately from the program. .PP Tk maintains a database of all the bitmaps that are currently in use. Whenever possible, it will return an existing bitmap rather than creating a new one. When a bitmap is no longer used, Tk will release it automatically. This approach can substantially reduce server overhead, so \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally be used in preference to Xlib procedures like \fBXReadBitmapFile\fR. .PP The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR are shared, so callers should never modify them. If a bitmap must be modified dynamically, then it should be created by calling Xlib procedures such as \fBXReadBitmapFile\fR or \fBXCreatePixmap\fR directly. .PP The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of \fBTk_GetBitmap\fR. Given an X Pixmap argument, it returns the textual description that was passed to \fBTk_GetBitmap\fR when the bitmap was created. \fIBitmap\fR must have been the return value from a previous call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. .PP \fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR argument in the words pointed to by the \fIwidthPtr\fR and \fIheightPtr\fR arguments. As with \fBTk_NameOfBitmap\fR, \fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. .PP When a bitmap is no longer needed, \fBTk_FreeBitmapFromObj\fR or \fBTk_FreeBitmap\fR should be called to release it. For \fBTk_FreeBitmapFromObj\fR the bitmap to release is specified with the same information used to create it; for \fBTk_FreeBitmap\fR the bitmap to release is specified with its Pixmap token. There should be exactly one call to \fBTk_FreeBitmapFromObj\fR or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. .SH BUGS .PP In determining whether an existing bitmap can be used to satisfy a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR consider only the immediate value of the string description. For example, when a file name is passed to \fBTk_GetBitmap\fR, \fBTk_GetBitmap\fR will assume it is safe to re-use an existing bitmap created from the same file name: it will not check to see whether the file itself has changed, or whether the current directory has changed, thereby causing the name to refer to a different file. .SH KEYWORDS bitmap, pixmap tk9.0.3/doc/GetCapStyl.30000644001000000100000000000400415105057705017715 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetCapStyle 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_GetCapStyle\fR(\fIinterp, string, capPtr\fR) .sp const char * \fBTk_NameOfCapStyle\fR(\fIcap\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *capPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP "const char" *string in String containing name of cap style \- one of .QW \fBbutt\fR , .QW \fBprojecting\fR , or .QW \fBround\fR \- or a unique abbreviation of one. .AP int *capPtr out Pointer to location in which to store X cap style corresponding to \fIstring\fR. .AP int cap in Cap style: one of \fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. .BE .SH DESCRIPTION .PP \fBTk_GetCapStyle\fR places in \fI*capPtr\fR the X cap style corresponding to \fIstring\fR. This will be one of the values \fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. Cap styles are typically used in X graphics contexts to indicate how the end-points of lines should be capped. See the X documentation for information on what each style implies. .PP Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. If \fIstring\fR does not contain a valid cap style or an abbreviation of one of these names, then an error message is stored in interpreter \fIinterp\fR's result, \fBTCL_ERROR\fR is returned, and \fI*capPtr\fR is unmodified. .PP \fBTk_NameOfCapStyle\fR is the logical inverse of \fBTk_GetCapStyle\fR. Given a cap style such as \fBCapButt\fR it returns a statically-allocated string corresponding to \fIcap\fR. If \fIcap\fR is not a legal cap style, then .QW "unknown cap style" is returned. .SH KEYWORDS butt, cap style, projecting, round tk9.0.3/doc/GetClrmap.30000644001000000100000000000601315105057705017556 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps .SH SYNOPSIS .nf \fB#include \fR .sp Colormap \fBTk_GetColormap\fR(\fIinterp, tkwin, string\fR) .sp \fBTk_PreserveColormap\fR(\fIdisplay, colormap\fR) .sp \fBTk_FreeColormap\fR(\fIdisplay, colormap\fR) .fi .SH ARGUMENTS .AS "Colormap" colormap .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window in which colormap will be used. .AP "const char" *string in Selects a colormap: either \fBnew\fR or the name of a window with the same screen and visual as \fItkwin\fR. .AP Display *display in Display for which \fIcolormap\fR was allocated. .AP Colormap colormap in Colormap to free or preserve; must have been returned by a previous call to \fBTk_GetColormap\fR or \fBTk_GetVisual\fR. .BE .SH DESCRIPTION .PP These procedures are used to manage colormaps. \fBTk_GetColormap\fR returns a colormap suitable for use in \fItkwin\fR. If its \fIstring\fR argument is \fBnew\fR then a new colormap is created; otherwise \fIstring\fR must be the name of another window with the same screen and visual as \fItkwin\fR, and the colormap from that window is returned. If \fIstring\fR does not make sense, or if it refers to a window on a different screen from \fItkwin\fR or with a different visual than \fItkwin\fR, then \fBTk_GetColormap\fR returns \fBNone\fR and leaves an error message in \fIinterp\fR's result. .PP \fBTk_PreserveColormap\fR increases the internal reference count for a colormap previously returned by \fBTk_GetColormap\fR, which allows the colormap to be stored in several locations without knowing which order they will be released. .PP \fBTk_FreeColormap\fR should be called when a colormap returned by \fBTk_GetColormap\fR is no longer needed. Tk maintains a reference count for each colormap returned by \fBTk_GetColormap\fR, so there should eventually be one call to \fBTk_FreeColormap\fR for each call to \fBTk_GetColormap\fR and each call to \fBTk_PreserveColormap\fR. When a colormap's reference count becomes zero, Tk releases the X colormap. .PP \fBTk_GetVisual\fR and \fBTk_GetColormap\fR work together, in that a new colormap created by \fBTk_GetVisual\fR may later be returned by \fBTk_GetColormap\fR. The reference counting mechanism for colormaps includes both procedures, so callers of \fBTk_GetVisual\fR must also call \fBTk_FreeColormap\fR to release the colormap. If \fBTk_GetColormap\fR is called with a \fIstring\fR value of \fBnew\fR then the resulting colormap will never be returned by \fBTk_GetVisual\fR; however, it can be used in other windows by calling \fBTk_GetColormap\fR with the original window's name as \fIstring\fR. .SH KEYWORDS colormap, visual tk9.0.3/doc/GetColor.30000644001000000100000000001652315076161056017427 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1991 The Regents of the University of California. '\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \- maintain database of colors .SH SYNOPSIS .nf \fB#include \fR .sp XColor * \fBTk_AllocColorFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp XColor * \fBTk_GetColor\fR(\fIinterp, tkwin, name\fR) .sp XColor * \fBTk_GetColorFromObj\fR(\fItkwin, objPtr\fR) .sp XColor * \fBTk_GetColorByValue\fR(\fItkwin, prefPtr\fR) .sp const char * \fBTk_NameOfColor\fR(\fIcolorPtr\fR) .sp GC \fBTk_GCForColor\fR(\fIcolorPtr, drawable\fR) .sp \fBTk_FreeColorFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_FreeColor\fR(\fIcolorPtr\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *colorPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window in which color will be used. .AP Tcl_Obj *objPtr in/out String value describes desired color; internal rep will be modified to cache pointer to corresponding (XColor *). .AP "const char" *name in Same as \fIobjPtr\fR except description of color is passed as a string and resulting (XColor *) is not cached. .AP XColor *prefPtr in Indicates red, green, and blue intensities of desired color. .AP XColor *colorPtr in Pointer to X color information. Must have been allocated by previous call to \fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR, except when passed to \fBTk_NameOfColor\fR. .AP Drawable drawable in Drawable in which the result graphics context will be used. Must have same screen and depth as the window for which the color was allocated. .BE .SH DESCRIPTION .PP These procedures manage the colors being used by a Tk application. They allow colors to be shared whenever possible, so that colormap space is preserved, and they pick closest available colors when colormap space is exhausted. .PP Given a textual description of a color, \fBTk_AllocColorFromObj\fR locates a pixel value that may be used to render the color in a particular window. The desired color is specified with a value whose string value must have one of the following forms: .TP 20 \fIcolorname\fR . Any of the valid textual names for a color defined in the server's color database file, such as \fBred\fR or \fBPeachPuff\fR. .TP 20 \fB#\fIRGB\fR .TP 20 \fB#\fIRRGGBB\fR .TP 20 \fB#\fIRRRGGGBBB\fR .TP 20 \fB#\fIRRRRGGGGBBBB\fR . A numeric specification of the red, green, and blue intensities to use to display the color. Each \fIR\fR, \fIG\fR, or \fIB\fR represents a single hexadecimal digit. The four forms permit colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values. When fewer than 16 bits are provided for each color, they represent the most significant bits of the color, while the lower unfilled bits will be repeatedly replicated from the available higher bits. For example, #3a7 is the same as #3333aaaa7777. .PP \fBTk_AllocColorFromObj\fR returns a pointer to an XColor structure; the structure indicates the exact intensities of the allocated color (which may differ slightly from those requested, depending on the limitations of the screen) and a pixel value that may be used to draw with the color in \fItkwin\fR. If an error occurs in \fBTk_AllocColorFromObj\fR (such as an unknown color name) then NULL is returned and an error message is stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. If the colormap for \fItkwin\fR is full, \fBTk_AllocColorFromObj\fR will use the closest existing color in the colormap. \fBTk_AllocColorFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to procedures such as \fBTk_AllocColorFromObj\fR and \fBTk_GetColorFromObj\fR. .PP \fBTk_GetColor\fR is identical to \fBTk_AllocColorFromObj\fR except that the description of the color is specified with a string instead of a value. This prevents \fBTk_GetColor\fR from caching the return value, so \fBTk_GetColor\fR is less efficient than \fBTk_AllocColorFromObj\fR. .PP \fBTk_GetColorFromObj\fR returns the token for an existing color, given the window and description used to create the color. \fBTk_GetColorFromObj\fR does not actually create the color; the color must already have been created with a previous call to \fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR. The return value is cached in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetColorFromObj\fR with the same \fIobjPtr\fR and \fItkwin\fR. .PP \fBTk_GetColorByValue\fR is similar to \fBTk_GetColor\fR except that the desired color is indicated with the \fIred\fR, \fIgreen\fR, and \fIblue\fR fields of the structure pointed to by \fIcolorPtr\fR. .PP This package maintains a database of all the colors currently in use. If the same color is requested multiple times from \fBTk_GetColor\fR or \fBTk_AllocColorFromObj\fR (e.g. by different windows), or if the same intensities are requested multiple times from \fBTk_GetColorByValue\fR, then existing pixel values will be re-used. Re-using an existing pixel avoids any interaction with the window server, which makes the allocation much more efficient. These procedures also provide a portable interface that works across all platforms. For this reason, you should generally use \fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR instead of lower level procedures like \fBXAllocColor\fR. .PP Since different calls to this package may return the same shared pixel value, callers should never change the color of a pixel returned by the procedures. If you need to change a color value dynamically, you should use \fBXAllocColorCells\fR to allocate the pixel value for the color. .PP The procedure \fBTk_NameOfColor\fR is roughly the inverse of \fBTk_GetColor\fR. If its \fIcolorPtr\fR argument was created by \fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR then the return value is the string that was used to create the color. If \fIcolorPtr\fR was created by a call to \fBTk_GetColorByValue\fR, or by any other mechanism, then the return value is a string that could be passed to \fBTk_GetColor\fR to return the same color. Note: the string returned by \fBTk_NameOfColor\fR is only guaranteed to persist until the next call to \fBTk_NameOfColor\fR. .PP \fBTk_GCForColor\fR returns a graphics context whose \fBforeground\fR field is the pixel allocated for \fIcolorPtr\fR and whose other fields all have default values. This provides an easy way to do basic drawing with a color. The graphics context is cached with the color and will exist only as long as \fIcolorPtr\fR exists; it is freed when the last reference to \fIcolorPtr\fR is freed by calling \fBTk_FreeColor\fR. .PP When a color is no longer needed \fBTk_FreeColorFromObj\fR or \fBTk_FreeColor\fR should be called to release it. For \fBTk_FreeColorFromObj\fR the color to release is specified with the same information used to create it; for \fBTk_FreeColor\fR the color to release is specified with a pointer to its XColor structure. There should be exactly one call to \fBTk_FreeColorFromObj\fR or \fBTk_FreeColor\fR for each call to \fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR. .SH KEYWORDS color, intensity, value, pixel value tk9.0.3/doc/GetCursor.30000644001000000100000000002400115105057705017612 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_AllocCursorFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor \- maintain database of cursors .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Cursor \fBTk_AllocCursorFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp Tk_Cursor \fBTk_GetCursor\fR(\fIinterp, tkwin, name\fR) .sp Tk_Cursor \fBTk_GetCursorFromObj\fR(\fItkwin, objPtr\fR) .sp Tk_Cursor \fBTk_GetCursorFromData\fR(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fR) .sp const char * \fBTk_NameOfCursor\fR(\fIdisplay, cursor\fR) .sp \fBTk_FreeCursorFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_FreeCursor\fR(\fIdisplay, cursor\fR) .fi .SH ARGUMENTS .AS "unsigned long" *pixelPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window in which the cursor will be used. .AP Tcl_Obj *objPtr in/out Description of cursor; see below for possible values. Internal rep will be modified to cache pointer to corresponding Tk_Cursor. .AP "const char" *name in Same as \fIobjPtr\fR except description of cursor is passed as a string and resulting Tk_Cursor is not cached. .AP "const char" *source in Data for cursor cursor, in standard cursor format. .AP "const char" *mask in Data for mask cursor, in standard cursor format. .AP "int" width in Width of \fIsource\fR and \fImask\fR. .AP "int" height in Height of \fIsource\fR and \fImask\fR. .AP "int" xHot in X-location of cursor hot-spot. .AP "int" yHot in Y-location of cursor hot-spot. .AP "const char" *fg in Textual description of foreground color for cursor. .AP "const char" *bg in Textual description of background color for cursor. .AP Display *display in Display for which \fIcursor\fR was allocated. .AP Tk_Cursor cursor in Opaque Tk identifier for cursor. If passed to \fBTk_FreeCursor\fR, must have been returned by some previous call to \fBTk_GetCursor\fR or \fBTk_GetCursorFromData\fR. .BE .SH DESCRIPTION .PP These procedures manage a collection of cursors being used by an application. The procedures allow cursors to be re-used efficiently, thereby avoiding server overhead, and also allow cursors to be named with character strings. .PP \fBTk_AllocCursorFromObj\fR takes as argument an object describing a cursor, and returns an opaque Tk identifier for a cursor corresponding to the description. It re-uses an existing cursor if possible and creates a new one otherwise. \fBTk_AllocCursorFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to procedures such as \fBTk_AllocCursorFromObj\fR and \fBTk_GetCursorFromObj\fR. If an error occurs in creating the cursor, such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR is returned and an error message will be stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. \fIObjPtr\fR must contain a standard Tcl list with one of the following forms: .TP \fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]] . \fIName\fR is the name of a cursor in the standard X cursor cursor, i.e., any of the names defined in \fBcursorcursor.h\fR, without the \fBXC_\fR. Some example values are \fBX_cursor\fR, \fBhand2\fR, or \fBleft_ptr\fR. Appendix B of .QW "The X Window System" by Scheifler & Gettys has illustrations showing what each of these cursors looks like. If \fIfgColor\fR and \fIbgColor\fR are both specified, they give the foreground and background colors to use for the cursor (any of the forms acceptable to \fBTk_GetColor\fR may be used). If only \fIfgColor\fR is specified, then there will be no background color: the background will be transparent. If no colors are specified, then the cursor will use black for its foreground color and white for its background color. .RS .PP The Macintosh version of Tk supports all of the X cursors and will also accept any of the standard Mac cursors including \fBibeam\fR, \fBcrosshair\fR, \fBwatch\fR, \fBplus\fR, and \fBarrow\fR. In addition, Tk will load Macintosh cursor resources of the types \fBcrsr\fR (color) and \fBCURS\fR (black and white) by the name of the resource. The application and all its open dynamic library's resource files will be searched for the named cursor. If there are conflicts color cursors will always be loaded in preference to black and white cursors. .RE .TP \fB@\fIsourceName\0maskName\0fgColor\0bgColor\fR . In this form, \fIsourceName\fR and \fImaskName\fR are the names of files describing cursors for the cursor's source bits and mask. Each file must be in standard X11 cursor format. \fIFgColor\fR and \fIbgColor\fR indicate the colors to use for the cursor, in any of the forms acceptable to \fBTk_GetColor\fR. This form of the command will not work on Macintosh or Windows computers. .TP \fB@\fIsourceName\0fgColor\fR . This form is similar to the one above, except that the source is used as mask also. This means that the cursor's background is transparent. This form of the command will not work on Macintosh or Windows computers. .TP \fB@\fIsourceName\fR . This form only works on Windows, and will load a Windows system cursor (\fB.ani\fR or \fB.cur\fR) from the file specified in \fIsourceName\fR. .PP \fBTk_GetCursor\fR is identical to \fBTk_AllocCursorFromObj\fR except that the description of the cursor is specified with a string instead of an object. This prevents \fBTk_GetCursor\fR from caching the return value, so \fBTk_GetCursor\fR is less efficient than \fBTk_AllocCursorFromObj\fR. .PP \fBTk_GetCursorFromObj\fR returns the token for an existing cursor, given the window and description used to create the cursor. \fBTk_GetCursorFromObj\fR does not actually create the cursor; the cursor must already have been created with a previous call to \fBTk_AllocCursorFromObj\fR or \fBTk_GetCursor\fR. The return value is cached in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetCursorFromObj\fR with the same \fIobjPtr\fR and \fItkwin\fR. .PP \fBTk_GetCursorFromData\fR allows cursors to be created from in-memory descriptions of their source and mask cursors. \fISource\fR points to standard cursor data for the cursor's source bits, and \fImask\fR points to standard cursor data describing which pixels of \fIsource\fR are to be drawn and which are to be considered transparent. \fIWidth\fR and \fIheight\fR give the dimensions of the cursor, \fIxHot\fR and \fIyHot\fR indicate the location of the cursor's hot-spot (the point that is reported when an event occurs), and \fIfg\fR and \fIbg\fR describe the cursor's foreground and background colors textually (any of the forms suitable for \fBTk_GetColor\fR may be used). Typically, the arguments to \fBTk_GetCursorFromData\fR are created by including a cursor file directly into the source code for a program, as in the following example: .CS Tk_Cursor cursor; #include "source.cursor" #include "mask.cursor" cursor = Tk_GetCursorFromData(interp, tkwin, source_bits, mask_bits, source_width, source_height, source_x_hot, source_y_hot, "red", "blue"); .CE .PP Under normal conditions \fBTk_GetCursorFromData\fR will return an identifier for the requested cursor. If an error occurs in creating the cursor then \fBNone\fR is returned and an error message will be stored in \fIinterp\fR's result. .PP \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, and \fBTk_GetCursorFromData\fR maintain a database of all the cursors they have created. Whenever possible, a call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, or \fBTk_GetCursorFromData\fR will return an existing cursor rather than creating a new one. This approach can substantially reduce server overhead, so the Tk procedures should generally be used in preference to Xlib procedures like \fBXCreateFontCursor\fR or \fBXCreatePixmapCursor\fR, which create a new cursor on each call. The Tk procedures are also more portable than the lower-level X procedures. .PP The procedure \fBTk_NameOfCursor\fR is roughly the inverse of \fBTk_GetCursor\fR. If its \fIcursor\fR argument was created by \fBTk_GetCursor\fR, then the return value is the \fIname\fR argument that was passed to \fBTk_GetCursor\fR to create the cursor. If \fIcursor\fR was created by a call to \fBTk_GetCursorFromData\fR, or by any other mechanism, then the return value is a hexadecimal string giving the X identifier for the cursor. Note that the string returned by \fBTk_NameOfCursor\fR is only guaranteed to persist until the next call to \fBTk_NameOfCursor\fR. Also, this call is not portable except for cursors returned by \fBTk_GetCursor\fR. .PP When a cursor returned by \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, or \fBTk_GetCursorFromData\fR is no longer needed, \fBTk_FreeCursorFromObj\fR or \fBTk_FreeCursor\fR should be called to release it. For \fBTk_FreeCursorFromObj\fR the cursor to release is specified with the same information used to create it; for \fBTk_FreeCursor\fR the cursor to release is specified with its Tk_Cursor token. There should be exactly one call to \fBTk_FreeCursor\fR for each call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, or \fBTk_GetCursorFromData\fR. .SH BUGS .PP In determining whether an existing cursor can be used to satisfy a new request, \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, and \fBTk_GetCursorFromData\fR consider only the immediate values of their arguments. For example, when a file name is passed to \fBTk_GetCursor\fR, \fBTk_GetCursor\fR will assume it is safe to re-use an existing cursor created from the same file name: it will not check to see whether the file itself has changed, or whether the current directory has changed, thereby causing the name to refer to a different file. Similarly, \fBTk_GetCursorFromData\fR assumes that if the same \fIsource\fR pointer is used in two different calls, then the pointers refer to the same data; it does not check to see if the actual data values have changed. .SH KEYWORDS cursor tk9.0.3/doc/GetDash.30000644001000000100000000000512615076161056017225 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1989-1993 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetDash 3 8.3 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetDash \- convert from string to valid dash structure. .SH SYNOPSIS .nf \fB#include \fR int \fBTk_GetDash\fR(\fIinterp, string, dashPtr\fR) .fi .SH ARGUMENTS .AS Tk_Dash *dashPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP "const char" *string in Textual value to be converted. .AP Tk_Dash *dashPtr out Points to place to store the dash pattern value converted from \fIstring\fR. Must not be NULL. .BE .SH DESCRIPTION .PP These procedure parses the string and fills in the result in the Tk_Dash structure. The string can be a list of integers or a character string containing only .QW \fB.,-_\fR and spaces. If all goes well, \fBTCL_OK\fR is returned and a dash descriptor is stored in the variable pointed to by \fIdashPtr\fR. If \fIstring\fR does not have the proper syntax then \fBTCL_ERROR\fR is returned, an error message is left in the interpreter's result, and nothing is stored at *\fIdashPtr\fR. .PP The first possible syntax is a list of integers. Each element represents the number of pixels of a line segment. Only the odd segments are drawn using the .QW outline color. The other segments are drawn transparent. .PP The second possible syntax is a character list containing only 5 possible characters .QW "\fB.,-_ \fR" . The space can be used to enlarge the space between other line elements, and can not occur in the first position of the string. Some examples: .PP .CS \-dash . = \-dash {2 4} \-dash - = \-dash {6 4} \-dash -. = \-dash {6 4 2 4} \-dash -.. = \-dash {6 4 2 4 2 4} \-dash {. } = \-dash {2 8} \-dash , = \-dash {4 4} .CE .PP The main difference between this syntax and the numeric is that it is shape-conserving. This means that all values in the dash list will be multiplied by the line width before display. This ensures that .QW . will always be displayed as a dot and .QW - always as a dash regardless of the line width. .PP On systems where only a limited set of dash patterns, the dash pattern will be displayed as the most close dash pattern that is available. For example, on Windows only the first 4 of the above examples are available; the last 2 examples will be displayed identically to the first one. .SH "SEE ALSO" canvas(n), Tk_CreateItemType(3) .SH KEYWORDS dash, conversion tk9.0.3/doc/GetFont.30000644001000000100000000001115115105057705017245 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1992 The Regents of the University of California. '\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_AllocFontFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FontGetDescription, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Font \fBTk_AllocFontFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp Tk_Font \fBTk_GetFont\fR(\fIinterp, tkwin, string\fR) .sp Tk_Font \fBTk_GetFontFromObj\fR(\fItkwin, objPtr\fR) .sp Tcl_Obj * \fBTk_FontGetDescription\fR(\fItkfont\fR) .sp const char * \fBTk_NameOfFont\fR(\fItkfont\fR) .sp Tk_Font \fBTk_FreeFontFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_FreeFont\fR(\fItkfont\fR) .fi .SH ARGUMENTS .AS "const char" *tkfont .AP "Tcl_Interp" *interp in Interpreter to use for error reporting. If \fBNULL\fR, then no error messages are left after errors. .AP Tk_Window tkwin in Token for window in which font will be used. .AP Tcl_Obj *objPtr in/out Gives name or description of font. See documentation for the \fBfont\fR command for details on acceptable formats. Internal rep will be modified to cache corresponding Tk_Font. .AP "const char" *string in Same as \fIobjPtr\fR except description of font is passed as a string and resulting Tk_Font is not cached. .AP Tk_Font tkfont in Opaque font token. .BE .SH DESCRIPTION .PP \fBTk_AllocFontFromObj\fR finds the font indicated by \fIobjPtr\fR and returns a token that represents the font. The return value can be used in subsequent calls to procedures such as \fBTk_GetFontMetrics\fR, \fBTk_MeasureChars\fR, and \fBTk_FreeFont\fR. The Tk_Font token will remain valid until \fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR is called to release it. \fIObjPtr\fR can contain either a symbolic name or a font description; see the documentation for the \fBfont\fR command for a description of the valid formats. If \fBTk_AllocFontFromObj\fR is unsuccessful (because, for example, \fIobjPtr\fR did not contain a valid font specification) then it returns \fBNULL\fR and leaves an error message in \fIinterp\fR's result if \fIinterp\fR is not \fBNULL\fR. \fBTk_AllocFontFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to procedures such as \fBTk_AllocFontFromObj\fR and \fBTk_GetFontFromObj\fR. .PP \fBTk_GetFont\fR is identical to \fBTk_AllocFontFromObj\fR except that the description of the font is specified with a string instead of an object. This prevents \fBTk_GetFont\fR from caching the matching Tk_Font, so \fBTk_GetFont\fR is less efficient than \fBTk_AllocFontFromObj\fR. .PP \fBTk_GetFontFromObj\fR returns the token for an existing font, given the window and description used to create the font. \fBTk_GetFontFromObj\fR does not actually create the font; the font must already have been created with a previous call to \fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR. The return value is cached in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetFontFromObj\fR with the same \fIobjPtr\fR and \fItkwin\fR. .PP \fBTk_AllocFontFromObj\fR and \fBTk_GetFont\fR maintain a database of all fonts they have allocated. If the same font is requested multiple times (e.g. by different windows or for different purposes), then a single Tk_Font will be shared for all uses. The underlying resources will be freed automatically when no-one is using the font anymore. .PP The procedure \fBTk_FontGetDescription\fR returns information about the font description as a Tcl list. One possible result is .QW "{{DejaVu Sans} -16 bold underline}" . .PP The procedure \fBTk_NameOfFont\fR is roughly the inverse of \fBTk_GetFont\fR. Given a \fItkfont\fR that was created by \fBTk_GetFont\fR (or \fBTk_AllocFontFromObj\fR), the return value is the \fIstring\fR argument that was passed to \fBTk_GetFont\fR to create the font. The string returned by \fBTk_NameOfFont\fR is only guaranteed to persist until the \fItkfont\fR is deleted. The caller must not modify this string. .PP When a font is no longer needed, \fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR should be called to release it. For \fBTk_FreeFontFromObj\fR the font to release is specified with the same information used to create it; for \fBTk_FreeFont\fR the font to release is specified with its Tk_Font token. There should be exactly one call to \fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR for each call to \fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR. .SH "SEE ALSO" Tk_FontId(3) .SH KEYWORDS font tk9.0.3/doc/GetGC.30000644001000000100000000000531715105057705016637 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetGC 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetGC, Tk_FreeGC \- maintain database of read-only graphics contexts .SH SYNOPSIS .nf \fB#include \fR .sp GC \fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR) .sp \fBTk_FreeGC\fR(\fIdisplay, gc\fR) .fi .SH ARGUMENTS .AS "unsigned long" valueMask .AP Tk_Window tkwin in Token for window in which the graphics context will be used. .AP "unsigned long" valueMask in Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR) indicating which fields of \fI*valuePtr\fR are valid. .AP XGCValues *valuePtr in Pointer to structure describing the desired values for the graphics context. .AP Display *display in Display for which \fIgc\fR was allocated. .AP GC gc in X identifier for graphics context that is no longer needed. Must have been allocated by \fBTk_GetGC\fR. .BE .SH DESCRIPTION .PP \fBTk_GetGC\fR and \fBTk_FreeGC\fR manage a collection of graphics contexts being used by an application. The procedures allow graphics contexts to be shared, thereby avoiding the server overhead that would be incurred if a separate GC were created for each use. \fBTk_GetGC\fR takes arguments describing the desired graphics context and returns an X identifier for a GC that fits the description. The graphics context that is returned will have default values in all of the fields not specified explicitly by \fIvalueMask\fR and \fIvaluePtr\fR. .PP \fBTk_GetGC\fR maintains a database of all the graphics contexts it has created. Whenever possible, a call to \fBTk_GetGC\fR will return an existing graphics context rather than creating a new one. This approach can substantially reduce server overhead, so \fBTk_GetGC\fR should generally be used in preference to the Xlib procedure \fBXCreateGC\fR, which creates a new graphics context on each call. .PP Since the return values of \fBTk_GetGC\fR are shared, callers should never modify the graphics contexts returned by \fBTk_GetGC\fR. If a graphics context must be modified dynamically, then it should be created by calling \fBXCreateGC\fR instead of \fBTk_GetGC\fR. .PP When a graphics context is no longer needed, \fBTk_FreeGC\fR should be called to release it. There should be exactly one call to \fBTk_FreeGC\fR for each call to \fBTk_GetGC\fR. When a graphics context is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) \fBTk_FreeGC\fR will release it to the X server and delete it from the database. .SH KEYWORDS graphics context tk9.0.3/doc/GetHINSTANCE.30000644001000000100000000000101715105057705017653 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tk_GetHISTANCE 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetHINSTANCE \- retrieve the global application instance handle .SH SYNOPSIS .nf \fB#include \fR .sp HINSTANCE \fBTk_GetHINSTANCE\fR() .fi .BE .SH DESCRIPTION .PP \fBTk_GetHINSTANCE\fR returns the Windows application instance handle for the Tk application. This function is only available on Windows platforms. .SH KEYWORDS identifier, instance tk9.0.3/doc/GetHWND.30000644001000000100000000000152115105057705017077 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH HWND 3 8.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetHWND, Tk_AttachHWND \- manage interactions between the Windows handle and an X window .SH SYNOPSIS .nf \fB#include \fR .sp HWND \fBTk_GetHWND\fR(\fIwindow\fR) .sp Window \fBTk_AttachHWND\fR(\fItkwin, hwnd\fR) .fi .SH ARGUMENTS .AP Window window in X token for window. .AP Tk_Window tkwin in Tk window for window. .AP HWND hwnd in Windows HWND for window. .BE .SH DESCRIPTION .PP \fBTk_GetHWND\fR returns the Windows HWND identifier for X Windows window given by \fIwindow\fR. .PP \fBTk_AttachHWND\fR binds the Windows HWND identifier to the specified Tk_Window given by \fItkwin\fR. It returns an X Windows window that encapsulates the HWND. .SH KEYWORDS identifier, window tk9.0.3/doc/GetImage.30000644001000000100000000001167015105057705017367 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \- use an image in a widget .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Image \fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR) .sp \fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR) .sp \fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR) .sp \fBTk_FreeImage\fR(\fIimage\fR) .fi .SH ARGUMENTS .AS Tk_ImageChangedProc *changeProc .AP Tcl_Interp *interp in Place to leave error message. .AP Tk_Window tkwin in Window in which image will be used. .AP "const char" *name in Name of image. .AP Tk_ImageChangedProc *changeProc in Procedure for Tk to invoke whenever image content or size changes. .AP void *clientData in One-word value for Tk to pass to \fIchangeProc\fR. .AP Tk_Image image in Token for image instance; must have been returned by a previous call to \fBTk_GetImage\fR. .AP int imageX in X-coordinate of upper-left corner of region of image to redisplay (measured in pixels from the image's upper-left corner). .AP int imageY in Y-coordinate of upper-left corner of region of image to redisplay (measured in pixels from the image's upper-left corner). .AP "int" width (in) Width of region of image to redisplay. .AP "int" height (in) Height of region of image to redisplay. .AP Drawable drawable in Where to display image. Must either be window specified to \fBTk_GetImage\fR or a pixmap compatible with that window. .AP int drawableX in Where to display image in \fIdrawable\fR: this is the x-coordinate in \fIdrawable\fR where x-coordinate \fIimageX\fR of the image should be displayed. .AP int drawableY in Where to display image in \fIdrawable\fR: this is the y-coordinate in \fIdrawable\fR where y-coordinate \fIimageY\fR of the image should be displayed. .AP "int" widthPtr out Store width of \fIimage\fR (in pixels) here. .AP "int" heightPtr out Store height of \fIimage\fR (in pixels) here. .BE .SH DESCRIPTION .PP These procedures are invoked by widgets that wish to display images. \fBTk_GetImage\fR is invoked by a widget when it first decides to display an image. \fIname\fR gives the name of the desired image and \fItkwin\fR identifies the window where the image will be displayed. \fBTk_GetImage\fR looks up the image in the table of existing images and returns a token for a new instance of the image. If the image does not exist then \fBTk_GetImage\fR returns NULL and leaves an error message in interpreter \fIinterp\fR's result. .PP When a widget wishes to actually display an image it must call \fBTk_RedrawImage\fR, identifying the image (\fIimage\fR), a region within the image to redisplay (\fIimageX\fR, \fIimageY\fR, \fIwidth\fR, and \fIheight\fR), and a place to display the image (\fIdrawable\fR, \fIdrawableX\fR, and \fIdrawableY\fR). Tk will then invoke the appropriate image manager, which will display the requested portion of the image before returning. .PP A widget can find out the dimensions of an image by calling \fBTk_SizeOfImage\fR: the width and height will be stored in the locations given by \fIwidthPtr\fR and \fIheightPtr\fR, respectively. .PP When a widget is finished with an image (e.g., the widget is being deleted or it is going to use a different image instead of the current one), it must call \fBTk_FreeImage\fR to release the image instance. The widget should never again use the image token after passing it to \fBTk_FreeImage\fR. There must be exactly one call to \fBTk_FreeImage\fR for each call to \fBTk_GetImage\fR. .PP If the contents or size of an image changes, then any widgets using the image will need to find out about the changes so that they can redisplay themselves. The \fIchangeProc\fR and \fIclientData\fR arguments to \fBTk_GetImage\fR are used for this purpose. \fIchangeProc\fR will be called by Tk whenever a change occurs in the image; it must match the following prototype: .CS typedef void \fBTk_ImageChangedProc\fR( void *\fIclientData\fR, int \fIx\fR, int \fIy\fR, int \fIwidth\fR, int \fIheight\fR, int \fIimageWidth\fR, int \fIimageHeight\fR); .CE The \fIclientData\fR argument to \fIchangeProc\fR is the same as the \fIclientData\fR argument to \fBTk_GetImage\fR. It is usually a pointer to the widget record for the widget or some other data structure managed by the widget. The arguments \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR identify a region within the image that must be redisplayed; they are specified in pixels measured from the upper-left corner of the image. The arguments \fIimageWidth\fR and \fIimageHeight\fR give the image's (new) size. .SH "SEE ALSO" Tk_CreateImageType .SH KEYWORDS images, redisplay tk9.0.3/doc/GetJoinStl.30000644001000000100000000000402315105057705017721 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetJoinStyle 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_GetJoinStyle\fR(\fIinterp, string, joinPtr\fR) .sp const char * \fBTk_NameOfJoinStyle\fR(\fIjoin\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *joinPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP "const char" *string in String containing name of join style \- one of .QW \fBbevel\fR , .QW \fBmiter\fR , or .QW \fBround\fR \- or a unique abbreviation of one. .AP int *joinPtr out Pointer to location in which to store X join style corresponding to \fIstring\fR. .AP int join in Join style: one of \fBJoinBevel\fR, \fBJoinMiter\fR, \fBJoinRound\fR. .BE .SH DESCRIPTION .PP \fBTk_GetJoinStyle\fR places in \fI*joinPtr\fR the X join style corresponding to \fIstring\fR, which will be one of \fBJoinBevel\fR, \fBJoinMiter\fR, or \fBJoinRound\fR. Join styles are typically used in X graphics contexts to indicate how adjacent line segments should be joined together. See the X documentation for information on what each style implies. .PP Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. If \fIstring\fR does not contain a valid join style or an abbreviation of one of these names, then an error message is stored in interpreter \fIinterp\fR's result, \fBTCL_ERROR\fR is returned, and \fI*joinPtr\fR is unmodified. .PP \fBTk_NameOfJoinStyle\fR is the logical inverse of \fBTk_GetJoinStyle\fR. Given a join style such as \fBJoinBevel\fR it returns a statically-allocated string corresponding to \fIjoin\fR. If \fIjoin\fR is not a legal join style, then .QW "unknown join style" is returned. .SH KEYWORDS bevel, join style, miter, round tk9.0.3/doc/GetJustify.30000644001000000100000000000612115105057705017775 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetJustifyFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_GetJustifyFromObj\fR(\fIinterp, objPtr, justifyPtr\fR) .sp int \fBTk_GetJustify\fR(\fIinterp, string, justifyPtr\fR) .sp const char * \fBTk_NameOfJustify\fR(\fIjustify\fR) .fi .SH ARGUMENTS .AS "Tk_Justify" *justifyPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting, or NULL. .AP Tcl_Obj *objPtr in/out String value contains name of justification style \- one of .QW \fBleft\fR , .QW \fBright\fR , or .QW \fBcenter\fR \- or a unique abbreviation of one. The internal rep will be modified to cache corresponding justify value. .AP "const char" *string in Same as \fIobjPtr\fR except description of justification style is passed as a string. .AP int *justifyPtr out Pointer to location in which to store justify value corresponding to \fIobjPtr\fR or \fIstring\fR. .AP Tk_Justify justify in Justification style (one of the values listed below). .BE .SH DESCRIPTION .PP \fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value corresponding to \fIobjPtr\fR's value. This value will be one of the following: .IP \fBTK_JUSTIFY_LEFT\fR Means that the text on each line should start at the left edge of the line; as a result, the right edges of lines may be ragged. .IP \fBTK_JUSTIFY_RIGHT\fR Means that the text on each line should end at the right edge of the line; as a result, the left edges of lines may be ragged. .IP \fBTK_JUSTIFY_CENTER\fR Means that the text on each line should be centered; as a result, both the left and right edges of lines may be ragged. .PP Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. If \fIobjPtr\fR does not contain a valid justification style or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned, \fI*justifyPtr\fR is unmodified, and an error message is stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. \fBTk_GetJustifyFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetJustifyFromObj\fR with the same \fIobjPtr\fR. .PP \fBTk_GetJustify\fR is identical to \fBTk_GetJustifyFromObj\fR except that the description of the justification is specified with a string instead of an object. This prevents \fBTk_GetJustify\fR from caching the return value, so \fBTk_GetJustify\fR is less efficient than \fBTk_GetJustifyFromObj\fR. .PP \fBTk_NameOfJustify\fR is the logical inverse of \fBTk_GetJustify\fR. Given a justify value it returns a statically-allocated string corresponding to \fIjustify\fR. If \fIjustify\fR is not a legal justify value, then .QW "unknown justification style" is returned. .SH KEYWORDS center, fill, justification, string tk9.0.3/doc/getOpenFile.n0000644001000000100000000002113115076161056020174 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk_getOpenFile n 4.2 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_getOpenFile, tk_getSaveFile \- pop up a dialog box for the user to select a file to open or save. .SH SYNOPSIS .nf \fBtk_getOpenFile \fR?\fIoption value ...\fR? \fBtk_getSaveFile \fR?\fIoption value ...\fR? .fi .BE .SH DESCRIPTION .PP The procedures \fBtk_getOpenFile\fR and \fBtk_getSaveFile\fR pop up a dialog box for the user to select a file to open or save. The \fBtk_getOpenFile\fR command is usually associated with the \fBOpen\fR command in the \fBFile\fR menu. Its purpose is for the user to select an existing file \fIonly\fR. If the user enters a non-existent file, the dialog box gives the user an error prompt and requires the user to give an alternative selection. If an application allows the user to create new files, it should do so by providing a separate \fBNew\fR menu command. .PP The \fBtk_getSaveFile\fR command is usually associated with the \fBSave as\fR command in the \fBFile\fR menu. If the user enters a file that already exists, the dialog box prompts the user for confirmation whether the existing file should be overwritten or not. .PP The following \fIoption\-value\fR pairs are possible as command line arguments to these two commands: .\" OPTION: -command .TP \fB\-command\fI string\fR . Specifies the prefix of a Tcl command to invoke when the user closes the dialog after having selected an item. This callback is not called if the user cancelled the dialog. The actual command consists of \fIstring\fR followed by a space and the value selected by the user in the dialog. This is only available on macOS. .\" OPTION: -confirmoverwrite .TP \fB\-confirmoverwrite\fI boolean\fR . Configures how the Save dialog reacts when the selected file already exists, and saving would overwrite it. A true value requests a confirmation dialog be presented to the user. A false value requests that the overwrite take place without confirmation. Default value is true. .\" OPTION: -defaultextension .TP \fB\-defaultextension\fI extension\fR . Specifies a string that will be appended to the filename if the user enters a filename without an extension. The default value is the empty string, which means no extension will be appended to the filename in any case. This option is ignored on macOS, which does not require extensions to filenames, and the UNIX implementation guesses reasonable values for this from the \fB\-filetypes\fR option when this is not supplied. .\" OPTION: -filetypes .TP \fB\-filetypes\fI filePatternList\fR . If a \fBFile types\fR listbox exists in the file dialog on the particular platform, this option gives the \fIfiletype\fRs in this listbox. When the user choose a filetype in the listbox, only the files of that type are listed. If this option is unspecified, or if it is set to the empty list, or if the \fBFile types\fR listbox is not supported by the particular platform then all files are listed regardless of their types. See the section \fBSPECIFYING FILE PATTERNS\fR below for a discussion on the contents of \fIfilePatternList\fR. .\" OPTION: -initialdir .TP \fB\-initialdir\fI directory\fR . Specifies that the files in \fIdirectory\fR should be displayed when the dialog pops up. If this parameter is not specified, the initial directory defaults to the current working directory on non-Windows systems and on Windows systems prior to Vista. On Vista and later systems, the initial directory defaults to the last user-selected directory for the application. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. .\" OPTION: -initialfile .TP \fB\-initialfile\fI filename\fR . Specifies a filename to be displayed in the dialog when it pops up. .\" OPTION: -message .TP \fB\-message\fI string\fR . Specifies a message to include in the client area of the dialog. This is only available on macOS. .\" OPTION: -multiple .TP \fB\-multiple\fI boolean\fR . Allows the user to choose multiple files from the Open dialog. .\" OPTION: -parent .TP \fB\-parent\fI window\fR . Makes \fIwindow\fR the logical parent of the file dialog. The file dialog is displayed on top of its parent window. On macOS, this turns the file dialog into a sheet attached to the parent window. .\" OPTION: -title .TP \fB\-title\fI titleString\fR . Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title is displayed. .\" OPTION: -typevariable .TP \fB\-typevariable\fI variableName\fR . The global variable \fIvariableName\fR is used to preselect which filter is used from \fIfilterList\fR when the dialog box is opened and is updated when the dialog box is closed, to the last selected filter. The variable is read once at the beginning to select the appropriate filter. If the variable does not exist, or its value does not match any filter typename, or is empty (\fB{}\fR), the dialog box will revert to the default behavior of selecting the first filter in the list. If the dialog is canceled, the variable is not modified. .PP If the user selects a file, both \fBtk_getOpenFile\fR and \fBtk_getSaveFile\fR return the full pathname of this file. If the user cancels the operation, both commands return the empty string. .SH "SPECIFYING FILE PATTERNS" .PP The \fIfilePatternList\fR value given by the \fB\-filetypes\fR option is a list of file patterns. Each file pattern is a list of the form .CS \fItypeName\fR {\fIextension\fR ?\fIextension ...\fR?} ?{\fImacType\fR ?\fImacType ...\fR?}? .CE \fItypeName\fR is the name of the file type described by this file pattern and is the text string that appears in the \fBFile types\fR listbox. \fIextension\fR is a file extension for this file pattern. \fImacType\fR is a four-character Macintosh file type. The list of \fImacType\fRs is optional and may be omitted for applications that do not need to execute on the Macintosh platform. .PP Several file patterns may have the same \fItypeName,\fR in which case they refer to the same file type and share the same entry in the listbox. When the user selects an entry in the listbox, all the files that match at least one of the file patterns corresponding to that entry are listed. Usually, each file pattern corresponds to a distinct type of file. The use of more than one file pattern for one type of file is only necessary on the Macintosh platform. .PP On the Macintosh platform, a file matches a file pattern if its name matches at least one of the \fIextension\fR(s) AND it belongs to at least one of the \fImacType\fR(s) of the file pattern. For example, the \fBC Source Files\fR file pattern in the sample code matches with files that have a \fB\.c\fR extension AND belong to the \fImacType\fR \fBTEXT\fR. To use the OR rule instead, you can use two file patterns, one with the \fIextensions\fR only and the other with the \fImacType\fR only. The \fBGIF Files\fR file type in the sample code matches files that \fIeither\fR have a \fB\.gif\fR extension OR belong to the \fImacType\fR \fBGIFF\fR. .PP On the Unix and Windows platforms, a file matches a file pattern if its name matches at least one of the \fIextension\fR(s) of the file pattern. The \fImacType\fRs are ignored. .SH "SPECIFYING EXTENSIONS" .PP On the Unix and Macintosh platforms, extensions are matched using glob-style pattern matching. On the Windows platform, extensions are matched by the underlying operating system. The types of possible extensions are: .IP (1) the special extension .QW * matches any file; .IP (2) the special extension .MT matches any files that do not have an extension (i.e., the filename contains no full stop character); .IP (3) any character string that does not contain any wild card characters (* and ?). .PP Due to the different pattern matching rules on the various platforms, to ensure portability, wild card characters are not allowed in the extensions, except as in the special extension .QW * . Extensions without a full stop character (e.g. .QW ~ ) are allowed but may not work on all platforms. .SH EXAMPLE .PP .CS set types { {{Text Files} {.txt} } {{TCL Scripts} {.tcl} } {{C Source Files} {.c} TEXT} {{GIF Files} {.gif} } {{GIF Files} {} GIFF} {{All Files} * } } set filename [\fBtk_getOpenFile\fR -filetypes $types] if {$filename ne ""} { # Open the file ... } .CE .SH "SEE ALSO" tk_chooseDirectory .SH KEYWORDS file selection dialog '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/GetOption.30000644001000000100000000000256715105057705017622 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetOption 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetOption \- retrieve an option from the option database .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Uid \fBTk_GetOption\fR(\fItkwin, name, class\fR) .fi .SH ARGUMENTS .AS Tk_Window *class .AP Tk_Window tkwin in Token for window. .AP "const char" *name in Name of desired option. .AP "const char" *class in Class of desired option. Null means there is no class for this option; do lookup based on name only. .BE .SH DESCRIPTION .PP This procedure is invoked to retrieve an option from the database associated with \fItkwin\fR's main window. If there is an option for \fItkwin\fR that matches the given \fIname\fR or \fIclass\fR, then it is returned in the form of a Tk_Uid. If multiple options match \fIname\fR and \fIclass\fR, then the highest-priority one is returned. If no option matches, then NULL is returned. .PP \fBTk_GetOption\fR caches options related to \fItkwin\fR so that successive calls for the same \fItkwin\fR will execute much more quickly than successive calls for different windows. .SH KEYWORDS class, name, option, retrieve tk9.0.3/doc/GetPixels.30000644001000000100000000000710715105057705017611 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetPixelsFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM, Tk_GetDoublePixelsFromObj \- translate between strings and screen units .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_GetPixelsFromObj\fR(\fIinterp, tkwin, objPtr, intPtr\fR) .sp int \fBTk_GetDoublePixelsFromObj\fR(\fIinterp, tkwin, objPtr, doublePtr\fR) .sp int \fBTk_GetPixels\fR(\fIinterp, tkwin, string, intPtr\fR) .sp int \fBTk_GetMMFromObj\fR(\fIinterp, tkwin, objPtr, doublePtr\fR) .sp int \fBTk_GetScreenMM\fR(\fIinterp, tkwin, string, doublePtr\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *joinPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Window whose screen geometry determines the conversion between absolute units and pixels. .AP Tcl_Obj *objPtr in/out String value specifies a distance on the screen; internal rep will be modified to cache converted distance. .AP "const char" *string in Same as \fIobjPtr\fR except specification of distance is passed as a string. .AP int *intPtr out Pointer to location in which to store converted distance in pixels. .AP double *doublePtr out Pointer to location in which to store converted distance in millimeters. .BE .SH DESCRIPTION .PP These procedures take as argument a specification of distance on the screen (\fIobjPtr\fR or \fIstring\fR) and compute the corresponding distance either in integer pixels or floating-point millimeters. In either case, \fIobjPtr\fR or \fIstring\fR specifies a screen distance as a floating-point number followed by one of the following characters that indicates units: .IP The number specifies a distance in pixels. .IP \fBc\fR The number specifies a distance in centimeters on the screen. .IP \fBi\fR The number specifies a distance in inches on the screen. .IP \fBm\fR The number specifies a distance in millimeters on the screen. .IP \fBp\fR The number specifies a distance in printer's points (1/72 inch) on the screen. .PP \fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the nearest even number of pixels and stores that value at \fI*intPtr\fR. It returns \fBTCL_OK\fR under normal circumstances. If an error occurs (e.g. \fIobjPtr\fR contains a number followed by a character that is not one of the ones above) then \fBTCL_ERROR\fR is returned and an error message is left in \fIinterp\fR's result if \fIinterp\fR is not NULL. \fBTk_GetPixelsFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetPixelsFromObj\fR with the same \fIobjPtr\fR. .PP \fBTk_GetDoublePixelsFromObj\fR is identical to \fBTk_GetPixelsFromObj\fR except it returns a double not rounded to the nearest integer. .PP \fBTk_GetPixels\fR is identical to \fBTk_GetPixelsFromObj\fR except that the screen distance is specified with a string instead of an object. This prevents \fBTk_GetPixels\fR from caching the return value, so \fBTk_GetPixels\fR is less efficient than \fBTk_GetPixelsFromObj\fR. .PP \fBTk_GetMMFromObj\fR and \fBTk_GetScreenMM\fR are similar to \fBTk_GetPixelsFromObj\fR and \fBTk_GetPixels\fR (respectively) except that they convert the screen distance to millimeters and store a double-precision floating-point result at \fI*doublePtr\fR. .SH KEYWORDS centimeters, convert, inches, millimeters, pixels, points, screen units tk9.0.3/doc/GetPixmap.30000644001000000100000000000321215105057705017574 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetPixmap 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps .SH SYNOPSIS .nf \fB#include \fR .sp Pixmap \fBTk_GetPixmap\fR(\fIdisplay, d, width, height, depth\fR) .sp \fBTk_FreePixmap\fR(\fIdisplay, pixmap\fR) .fi .SH ARGUMENTS .AS "Drawable" *pixelPtr .AP Display *display in X display for the pixmap. .AP Drawable d in Pixmap or window where the new pixmap will be used for drawing. .AP "int" width in Width of pixmap. .AP "int" height in Height of pixmap. .AP "int" depth in Number of bits per pixel in pixmap. .AP Pixmap pixmap in Pixmap to destroy. .BE .SH DESCRIPTION .PP These procedures are identical to the Xlib procedures \fBXCreatePixmap\fR and \fBXFreePixmap\fR, except that they have extra code to manage X resource identifiers so that identifiers for deleted pixmaps can be reused in the future. It is important for Tk applications to use these procedures rather than \fBXCreatePixmap\fR and \fBXFreePixmap\fR; otherwise long-running applications may run out of resource identifiers. .PP \fBTk_GetPixmap\fR creates a pixmap suitable for drawing in \fId\fR, with dimensions given by \fIwidth\fR, \fIheight\fR, and \fIdepth\fR, and returns its identifier. \fBTk_FreePixmap\fR destroys the pixmap given by \fIpixmap\fR and makes its resource identifier available for reuse. .SH KEYWORDS pixmap, resource identifier tk9.0.3/doc/GetRelief.30000644001000000100000000000555115076161056017556 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetReliefFromObj 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_GetReliefFromObj\fR(\fIinterp, objPtr, reliefPtr\fR) .sp int \fBTk_GetRelief\fR(\fIinterp, name, reliefPtr\fR) .sp const char * \fBTk_NameOfRelief\fR(\fIrelief\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *reliefPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tcl_Obj *objPtr in/out String value contains name of relief, one of .QW \fBflat\fR , .QW \fBgroove\fR , .QW \fBraised\fR , .QW \fBridge\fR , .QW \fBsolid\fR , or .QW \fBsunken\fR (or any unique abbreviation thereof on input); the internal rep will be modified to cache corresponding relief value. .AP "const char" *name in Same as \fIobjPtr\fR except description of relief is passed as a string. .AP int *reliefPtr out Pointer to location in which to store relief value corresponding to \fIobjPtr\fR or \fIname\fR. .AP int relief in Relief value (one of \fBTK_RELIEF_FLAT\fR, \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR). .BE .SH DESCRIPTION .PP \fBTk_GetReliefFromObj\fR places in \fI*reliefPtr\fR the relief value corresponding to the value of \fIobjPtr\fR. This value will be one of \fBTK_RELIEF_FLAT\fR, \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR. Under normal circumstances the return value is \fBTCL_OK\fR and \fIinterp\fR is unused. If \fIobjPtr\fR does not contain one of the valid relief names or an abbreviation of one of them, then \fBTCL_ERROR\fR is returned, \fI*reliefPtr\fR is unmodified, and an error message is stored in \fIinterp\fR's result if \fIinterp\fR is not NULL. \fBTk_GetReliefFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetReliefFromObj\fR with the same \fIobjPtr\fR. .PP \fBTk_GetRelief\fR is identical to \fBTk_GetReliefFromObj\fR except that the description of the relief is specified with a string instead of an object. This prevents \fBTk_GetRelief\fR from caching the return value, so \fBTk_GetRelief\fR is less efficient than \fBTk_GetReliefFromObj\fR. .PP \fBTk_NameOfRelief\fR is the logical inverse of \fBTk_GetRelief\fR. Given a relief value it returns the corresponding string (\fBflat\fR, \fBraised\fR, \fBsunken\fR, \fBgroove\fR, \fBsolid\fR, or \fBridge\fR). If \fIrelief\fR is not a legal relief value, then .QW "unknown relief" is returned. .SH KEYWORDS name, relief, string tk9.0.3/doc/GetRootCrd.30000644001000000100000000000246215105057705017720 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetRootCoords 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetRootCoords \- Compute root-window coordinates of window .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_GetRootCoords\fR(\fItkwin, xPtr, yPtr\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in Token for window. .AP int *xPtr out Pointer to location in which to store root-window x-coordinate corresponding to left edge of \fItkwin\fR's border. .AP int *yPtr out Pointer to location in which to store root-window y-coordinate corresponding to top edge of \fItkwin\fR's border. .BE .SH DESCRIPTION .PP This procedure scans through the structural information maintained by Tk to compute the root-window coordinates corresponding to the upper-left corner of \fItkwin\fR's border. If \fItkwin\fR has no border, then \fBTk_GetRootCoords\fR returns the root-window coordinates corresponding to location (0,0) in \fItkwin\fR. \fBTk_GetRootCoords\fR is relatively efficient, since it does not have to communicate with the X server. .SH KEYWORDS coordinates, root window tk9.0.3/doc/GetScroll.30000644001000000100000000000552515105057705017605 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetScrollInfo 3 8.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetScrollInfoObj, Tk_GetScrollInfo \- parse arguments for scrolling commands .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_GetScrollInfoObj\fR(\fIinterp, objc, objv, fractionPtr, stepsPtr\fR) .sp int \fBTk_GetScrollInfo\fR(\fIinterp, argc, argv, fractionPtr, stepsPtr\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *fractionPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tcl_Size objc in Number of Tcl_Obj's in \fIobjv\fR array. .AP "Tcl_Obj *const *" objv in Argument objects. These represent the entire widget command, of which the first word is typically the widget name and the second word is typically \fBxview\fR or \fByview\fR. .AP int argc in Number of strings in \fIargv\fR array. .AP "const char **" argv in Argument strings. These represent the entire widget command, of which the first word is typically the widget name and the second word is typically \fBxview\fR or \fByview\fR. .AP double *fractionPtr out Filled in with fraction from \fBmoveto\fR option, if any. .AP int *stepsPtr out Filled in with line or page count from \fBscroll\fR option, if any. The value may be negative. .BE .SH DESCRIPTION .PP \fBTk_GetScrollInfoObj\fR parses the arguments expected by widget scrolling commands such as \fBxview\fR and \fByview\fR. It receives the entire list of words that make up a widget command and parses the words starting with \fIobjv\fR[2]. The words starting with \fIobjv\fR[2] must have one of the following forms: .CS \fBmoveto \fIfraction\fR \fBscroll \fInumber\fB pages\fR \fBscroll \fInumber\fB units\fR .CE .LP Any of the \fBmoveto\fR, \fBscroll\fR, \fBpages\fR, and \fBunits\fR keywords may be abbreviated. If \fIobjv\fR has the \fBmoveto\fR form, \fBTK_SCROLL_MOVETO\fR is returned as result and \fI*fractionPtr\fR is filled in with the \fIfraction\fR argument to the command, which must be a proper real value. If \fIobjv\fR has the \fBscroll\fR form, \fBTK_SCROLL_PAGES\fR or \fBTK_SCROLL_UNITS\fR is returned and \fI*stepsPtr\fR is filled in with the \fInumber\fR value, which must be a integer or a float, but if it is a float then it is converted to an integer, rounded away from 0. If an error occurs in parsing the arguments, \fBTK_SCROLL_ERROR\fR is returned and an error message is left in interpreter \fIinterp\fR's result. .PP \fBTk_GetScrollInfo\fR is identical in function to \fBTk_GetScrollInfoObj\fR. However, \fBTk_GetScrollInfo\fR accepts string arguments, making it more appropriate for use with legacy widgets. .SH KEYWORDS parse, scrollbar, scrolling command, xview, yview tk9.0.3/doc/GetSelect.30000644001000000100000000000603615105057705017564 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetSelection 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetSelection \- retrieve the contents of a selection .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR) .fi .SH ARGUMENTS .AS Tk_GetSelProc clientData .AP Tcl_Interp *interp in Interpreter to use for reporting errors. .AP Tk_Window tkwin in Window on whose behalf to retrieve the selection (determines display from which to retrieve). .AP Atom selection in The name of the selection to be retrieved. .AP Atom target in Form in which to retrieve selection. .AP Tk_GetSelProc *proc in Procedure to invoke to process pieces of the selection as they are retrieved. .AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION .PP \fBTk_GetSelection\fR retrieves the selection specified by the atom \fIselection\fR in the format specified by \fItarget\fR. The selection may actually be retrieved in several pieces; as each piece is retrieved, \fIproc\fR is called to process the piece. \fIProc\fR should have arguments and result that match the type \fBTk_GetSelProc\fR: .PP .CS typedef int \fBTk_GetSelProc\fR( void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, char *\fIportion\fR); .CE .PP The \fIclientData\fR and \fIinterp\fR parameters to \fIproc\fR will be copies of the corresponding arguments to \fBTk_GetSelection\fR. \fIPortion\fR will be a pointer to a string containing part or all of the selection. For large selections, \fIproc\fR will be called several times with successive portions of the selection. The X Inter-Client Communication Conventions Manual allows a selection to be returned in formats other than strings, e.g. as an array of atoms or integers. If this happens, Tk converts the selection back into a string before calling \fIproc\fR. If a selection is returned as an array of atoms, Tk converts it to a string containing the atom names separated by white space. For any other format besides string, Tk converts a selection to a string containing hexadecimal values separated by white space. .PP \fBTk_GetSelection\fR returns to its caller when the selection has been completely retrieved and processed by \fIproc\fR, or when a fatal error has occurred (e.g. the selection owner did not respond promptly). \fBTk_GetSelection\fR normally returns \fBTCL_OK\fR; if an error occurs, it returns \fBTCL_ERROR\fR and leaves an error message in interpreter \fIinterp\fR's result. \fIProc\fR should also return either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fIproc\fR encounters an error in dealing with the selection, it should leave an error message in the interpreter result and return \fBTCL_ERROR\fR; this will abort the selection retrieval. .SH KEYWORDS format, get, selection retrieval tk9.0.3/doc/GetUid.30000644001000000100000000000304615105057705017064 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetUid 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetUid, Tk_Uid \- convert from string to unique identifier .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Uid \fBTk_GetUid\fR(\fIstring\fR) .fi .SH ARGUMENTS .AP char *string in String for which the corresponding unique identifier is desired. .BE .SH DESCRIPTION .PP \fBTk_GetUid\fR returns the unique identifier corresponding to \fIstring\fR. Unique identifiers are similar to atoms in Lisp, and are used in Tk to speed up comparisons and searches. A unique identifier (type Tk_Uid) is a string pointer and may be used anywhere that a variable of type .QW "char *" could be used. However, there is guaranteed to be exactly one unique identifier for any given string value. If \fBTk_GetUid\fR is called twice, once with string \fIa\fR and once with string \fIb\fR, and if \fIa\fR and \fIb\fR have the same string value (strcmp(a, b) == 0), then \fBTk_GetUid\fR will return exactly the same Tk_Uid value for each call (Tk_GetUid(a) == Tk_GetUid(b)). This means that variables of type Tk_Uid may be compared directly (x == y) without having to call \fBstrcmp\fR. In addition, the return value from \fBTk_GetUid\fR will have the same string value as its argument (strcmp(Tk_GetUid(a), a) == 0). .SH KEYWORDS atom, unique identifier tk9.0.3/doc/GetVisual.30000644001000000100000000000674615105057705017620 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetVisual 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetVisual \- translate from string to visual .SH SYNOPSIS .nf \fB#include \fR .sp Visual * \fBTk_GetVisual\fR(\fIinterp, tkwin, string, depthPtr, colormapPtr\fR) .fi .SH ARGUMENTS .AS "Tcl_Interp" *colormapPtr .AP Tcl_Interp *interp in Interpreter to use for error reporting. .AP Tk_Window tkwin in Token for window in which the visual will be used. .AP "const char" *string in String that identifies the desired visual. See below for valid formats. .AP int *depthPtr out Depth of returned visual gets stored here. .AP Colormap *colormapPtr out If non-NULL then a suitable colormap for visual is found and its identifier is stored here. .BE .SH DESCRIPTION .PP \fBTk_GetVisual\fR takes a string description of a visual and finds a suitable X Visual for use in \fItkwin\fR, if there is one. It returns a pointer to the X Visual structure for the visual and stores the number of bits per pixel for it at \fI*depthPtr\fR. If \fIstring\fR is unrecognizable or if no suitable visual could be found, then NULL is returned and \fBTk_GetVisual\fR leaves an error message in interpreter \fIinterp\fR's result. If \fIcolormap\fR is non-NULL then \fBTk_GetVisual\fR also locates an appropriate colormap for use with the result visual and stores its X identifier at \fI*colormapPtr\fR. .PP The \fIstring\fR argument specifies the desired visual in one of the following ways: .TP 15 \fIclass depth\fR . The string consists of a class name followed by an integer depth, with any amount of white space (including none) in between. \fIclass\fR selects what sort of visual is desired and must be one of \fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or \fBtruecolor\fR, or a unique abbreviation. \fIdepth\fR specifies how many bits per pixel are needed for the visual. If possible, \fBTk_GetVisual\fR will return a visual with this depth; if there is no visual of the desired depth then \fBTk_GetVisual\fR looks first for a visual with greater depth, then one with less depth. .TP 15 \fBdefault\fR . Use the default visual for \fItkwin\fR's screen. .TP 15 \fIpathName\fR . Use the visual for the window given by \fIpathName\fR. \fIpathName\fR must be the name of a window on the same screen as \fItkwin\fR. .TP 15 \fInumber\fR . Use the visual whose X identifier is \fInumber\fR. .TP 15 \fBbest\fR ?\fIdepth\fR? . Choose the .QW "best possible" visual, using the following rules, in decreasing order of priority: .RS .IP (a) a visual that has exactly the desired depth is best, followed by a visual with greater depth than requested (but as little extra as possible), followed by a visual with less depth than requested (but as great a depth as possible); .IP (b) if no \fIdepth\fR is specified, then the deepest available visual is chosen; .IP (c) \fBpseudocolor\fR is better than \fBtruecolor\fR or \fBdirectcolor\fR, which are better than \fBstaticcolor\fR, which is better than \fBstaticgray\fR or \fBgrayscale\fR; .IP (d) the default visual for the screen is better than any other visual. .RE .SH CREDITS .PP The idea for \fBTk_GetVisual\fR, and the first implementation, came from Paul Mackerras. .SH KEYWORDS colormap, screen, visual tk9.0.3/doc/GetVRoot.30000644001000000100000000000336115105057705017414 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_GetVRootGeometry 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetVRootGeometry \- Get location and size of virtual root for window .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_GetVRootGeometry\fR(\fItkwin, xPtr, yPtr, widthPtr, heightPtr\fR) .fi .SH ARGUMENTS .AS Tk_Window heightPtr .AP Tk_Window tkwin in Token for window whose virtual root is to be queried. .AP int xPtr out Points to word in which to store x-offset of virtual root. .AP int yPtr out Points to word in which to store y-offset of virtual root. .AP "int" widthPtr out Points to word in which to store width of virtual root. .AP "int" heightPtr out Points to word in which to store height of virtual root. .BE .SH DESCRIPTION .PP \fBTk_GetVRootGeometry\fR returns geometry information about the virtual root window associated with \fItkwin\fR. The .QW associated virtual root is the one in which \fItkwin\fR's nearest top-level ancestor (or \fItkwin\fR itself if it is a top-level window) has been reparented by the window manager. This window is identified by a \fB__SWM_ROOT\fR or \fB__WM_ROOT\fR property placed on the top-level window by the window manager. If \fItkwin\fR is not associated with a virtual root (e.g. because the window manager does not use virtual roots) then *\fIxPtr\fR and *\fIyPtr\fR will be set to 0 and *\fIwidthPtr\fR and *\fIheightPtr\fR will be set to the dimensions of the screen containing \fItkwin\fR. .SH KEYWORDS geometry, height, location, virtual root, width, window manager tk9.0.3/doc/Grab.30000644001000000100000000000442315105057705016556 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tk_Grab 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_Grab, Tk_Ungrab \- manipulate grab state in an application .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR) .sp \fBTk_Ungrab\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AP Tcl_Interp *interp in Interpreter to use for error reporting .AP Tk_Window tkwin in Window on whose behalf the pointer is to be grabbed or released .AP int grabGlobal in Boolean indicating whether the grab is global or application local .BE .SH DESCRIPTION .PP These functions are used to set or release a global or application local grab. When a grab is set on a particular window in a Tk application, mouse and keyboard events can only be received by that window and its descendants. Mouse and keyboard events for windows outside the tree rooted at \fItkwin\fR will be redirected to \fItkwin\fR. If the grab is global, then all mouse and keyboard events for windows outside the tree rooted at \fItkwin\fR (even those intended for windows in other applications) will be redirected to \fItkwin\fR. If the grab is application local, only mouse and keyboard events intended for a windows within the same application (but outside the tree rooted at \fItkwin\fR) will be redirected. .PP \fBTk_Grab\fR sets a grab on a particular window. \fITkwin\fR specifies the window on whose behalf the pointer is to be grabbed. \fIGrabGlobal\fR indicates whether the grab should be global or application local; if it is non-zero, it means the grab should be global. Normally, \fBTk_Grab\fR returns \fBTCL_OK\fR; if an error occurs and the grab cannot be set, \fBTCL_ERROR\fR is returned and an error message is left if \fIinterp\fR's result. Once this call completes successfully, no window outside the tree rooted at \fItkwin\fR will receive pointer- or keyboard-related events until the next call to Tk_Ungrab. If a previous grab was in effect within the application, then it is replaced with a new one. .PP \fBTk_Ungrab\fR releases a grab on the mouse pointer and keyboard, if there is one set on the window given by \fItkwin\fR. Once a grab is released, pointer and keyboard events will start being delivered to other windows again. .SH KEYWORDS grab, window tk9.0.3/doc/grab.n0000644001000000100000000001445715105057705016721 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH grab n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME grab \- Confine pointer and keyboard events to a window sub-tree .SH SYNOPSIS .nf \fBgrab \fR?\fB\-global\fR? \fIwindow\fR \fBgrab \fIoption \fR?\fIarg \fR...? .fi .BE .SH DESCRIPTION .PP This command implements simple pointer and keyboard grabs for Tk. Tk's grabs are different than the grabs described in the Xlib documentation. When a grab is set for a particular window, Tk restricts all pointer events to the grab window and its descendants in Tk's window hierarchy. Whenever the pointer is within the grab window's subtree, the pointer will behave exactly the same as if there had been no grab at all and all events will be reported in the normal fashion. When the pointer is outside \fIwindow\fR's tree, button presses and releases and mouse motion events are reported to \fIwindow\fR, and window entry and window exit events are ignored. The grab subtree .QW owns the pointer: windows outside the grab subtree will be visible on the screen but they will be insensitive until the grab is released. The tree of windows underneath the grab window can include top-level windows, in which case all of those top-level windows and their descendants will continue to receive mouse events during the grab. .PP Two forms of grabs are possible: local and global. A local grab affects only the grabbing application: events will be reported to other applications as if the grab had never occurred. Grabs are local by default. A global grab locks out all applications on the screen, so that only the given subtree of the grabbing application will be sensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, and window exits). During global grabs the window manager will not receive pointer events either. .PP During local grabs, keyboard events (key presses and key releases) are delivered as usual: the window manager controls which application receives keyboard events, and if they are sent to any window in the grabbing application then they are redirected to the focus window. During a global grab Tk grabs the keyboard so that all keyboard events are always sent to the grabbing application. The \fBfocus\fR command is still used to determine which window in the application receives the keyboard events. The keyboard grab is released when the grab is released. .PP On macOS a global grab affects all windows created by one Tk process. No window in that process other than the grab window can even be focused, hence no other window receives key or mouse events. A local grab on macOS affects all windows created by one Tcl interpreter. It is possible to focus any window belonging to the Tk process during a local grab but the grab window is the only window created by its interpreter which receives key or mouse events. Windows belonging to the same process but created by different interpreters continue to receive key and mouse events normally. .PP Grabs apply to particular displays. If an application has windows on multiple displays then it can establish a separate grab on each display. The grab on a particular display affects only the windows on that display. It is possible for different applications on a single display to have simultaneous local grabs, but only one application can have a global grab on a given display at once. .PP The \fBgrab\fR command can take any of the following forms: .TP \fBgrab \fR?\fB\-global\fR? \fIwindow\fR . Same as \fBgrab set\fR, described below. .\" METHOD: current .TP \fBgrab current \fR?\fIwindow\fR? . If \fIwindow\fR is specified, returns the name of the current grab window in this application for \fIwindow\fR's display, or an empty string if there is no such window. If \fIwindow\fR is omitted, the command returns a list whose elements are all of the windows grabbed by this application for all displays, or an empty string if the application has no grabs. .\" METHOD: release .TP \fBgrab release \fIwindow\fR . Releases the grab on \fIwindow\fR if there is one, otherwise does nothing. Returns an empty string. .\" METHOD: set .TP \fBgrab set \fR?\fB\-global\fR? \fIwindow\fR . Sets a grab on \fIwindow\fR. If \fB\-global\fR is specified then the grab is global, otherwise it is local. If a grab was already in effect for this application on \fIwindow\fR's display then it is automatically released. If there is already a grab on \fIwindow\fR and it has the same global/local form as the requested grab, then the command does nothing. Returns an empty string. .\" METHOD: status .TP \fBgrab status \fIwindow\fR . Returns \fBnone\fR if no grab is currently set on \fIwindow\fR, \fBlocal\fR if a local grab is set on \fIwindow\fR, and \fBglobal\fR if a global grab is set. .SH WARNING .PP It is very easy to use global grabs to render a display completely unusable (e.g. by setting a grab on a widget which does not respond to events and not providing any mechanism for releasing the grab). Take \fIextreme\fR care when using them! .SH BUGS .PP It took an incredibly complex and gross implementation to produce the simple grab effect described above. Given the current implementation, it is not safe for applications to use the Xlib grab facilities at all except through the Tk grab procedures. If applications try to manipulate X's grab mechanisms directly, things will probably break. .PP If a single process is managing several different Tk applications, only one of those applications can have a local grab for a given display at any given time. If the applications are in different processes, this restriction does not exist. .SH EXAMPLE .PP Set a grab so that only one button may be clicked out of a group. The other buttons are unresponsive to the mouse until the middle button is clicked. .CS pack [button .b1 -text "Click me! #1" -command {destroy .b1}] pack [button .b2 -text "Click me! #2" -command {destroy .b2}] pack [button .b3 -text "Click me! #3" -command {destroy .b3}] \fBgrab\fR .b2 .CE .SH "SEE ALSO" busy(n) .SH KEYWORDS grab, keyboard events, pointer events, window '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/grid.n0000644001000000100000000005101015105057705016715 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH grid n 8.5 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME grid \- Geometry manager that arranges widgets in a grid .SH SYNOPSIS \fBgrid \fIoption arg \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBgrid\fR command is used to communicate with the grid geometry manager that arranges widgets in rows and columns inside of another window, called the geometry container (or container window). The \fBgrid\fR command can have any of several forms, depending on the \fIoption\fR argument: .TP \fBgrid \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? . If the first argument to \fBgrid\fR is suitable as the first window argument to \fBgrid configure\fR, either a window name (any value starting with \fB.\fR) or one of the characters \fBx\fR or \fB^\fR (see the \fBRELATIVE PLACEMENT\fR section below), then the command is processed in the same way as \fBgrid configure\fR. .\" METHOD: anchor .TP \fBgrid anchor \fIwindow\fR ?\fIanchor\fR? . The anchor value controls how to place the grid within the container window when no row/column has any weight. See \fBTHE GRID ALGORITHM\fR below for further details. The default \fIanchor\fR is \fInw\fR. .\" METHOD: bbox .TP \fBgrid bbox \fIwindow\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? . With no arguments, the bounding box (in pixels) of the grid is returned. The return value consists of 4 integers. The first two are the pixel offset from the container window (x then y) of the top-left corner of the grid, and the second two integers are the width and height of the grid, also in pixels. If a single \fIcolumn\fR and \fIrow\fR is specified on the command line, then the bounding box for that cell is returned, where the top left cell is numbered from zero. If both \fIcolumn\fR and \fIrow\fR arguments are specified, then the bounding box spanning the rows and columns indicated is returned. .\" METHOD: columnconfigure .TP \fBgrid columnconfigure \fIwindow index \fR?\fI\-option value...\fR? . Query or set the column properties of the \fIindex\fR column of the geometry container, \fIwindow\fR. The valid options are \fB\-minsize\fR, \fB\-weight\fR, \fB\-uniform\fR and \fB\-pad\fR. If one or more options are provided, then \fIindex\fR may be given as a list of column indices to which the configuration options will operate on. Indices may be integers, window names or the keyword \fIall\fR. For \fIall\fR the options apply to all columns currently occupied be content windows. For a window name, that window must be a content of this container and the options apply to all columns currently occupied be the content. The \fB\-minsize\fR option sets the minimum size, in screen units, that will be permitted for this column. The \fB\-weight\fR option (an integer value) sets the relative weight for apportioning any extra spaces among columns. A weight of zero (0) indicates the column will not deviate from its requested size. A column whose weight is two will grow at twice the rate as a column of weight one when extra space is allocated to the layout. The \fB\-uniform\fR option, when a non-empty value is supplied, places the column in a \fIuniform group\fR with other columns that have the same value for \fB\-uniform\fR. The space for columns belonging to a uniform group is allocated so that their sizes are always in strict proportion to their \fB\-weight\fR values. See \fBTHE GRID ALGORITHM\fR below for further details. The \fB\-pad\fR option specifies the number of screen units that will be added to the largest window contained completely in that column when the grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the container window and index is specified, all the current settings are returned in a list of .QW "\fI\-option value\fR" pairs. .\" METHOD: configure .TP \fBgrid configure \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? . The arguments consist of the names of one or more content windows followed by pairs of arguments that specify how to manage the content. The characters \fB\-\fR, \fBx\fR and \fB^\fR, can be specified instead of a window name to alter the default location of a \fIwindow\fR, as described in the \fBRELATIVE PLACEMENT\fR section, below. The following options are supported: .RS .\" OPTION: -column .TP \fB\-column \fIn\fR . Insert the window so that it occupies the \fIn\fRth column in the grid. Column numbers start with 0. If this option is not supplied, then the window is arranged just to the right of previous window specified on this call to \fBgrid\fR, or column .QW 0 if it is the first window. For each \fBx\fR that immediately precedes the \fIwindow\fR, the column position is incremented by one. Thus the \fBx\fR represents a blank column for this row in the grid. .\" OPTION: -columnspan .TP \fB\-columnspan \fIn\fR . Insert the window so that it occupies \fIn\fR columns in the grid. The default is one column, unless the window name is followed by a \fB\-\fR, in which case the columnspan is incremented once for each immediately following \fB\-\fR. .\" OPTION: -in .TP \fB\-in \fIcontainer\fR . Insert the window(s) in the container window given by \fIcontainer\fR. The default is the first window's parent window. .\" OPTION: -ipadx .TP \fB\-ipadx \fIamount\fR . The \fIamount\fR specifies how much horizontal internal padding to leave on each side of the content. This is space is added inside the content border. The \fIamount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. It defaults to 0. .\" OPTION: -ipady .TP \fB\-ipady \fIamount\fR . The \fIamount\fR specifies how much vertical internal padding to leave on the top and bottom of the content. This space is added inside the content border. The \fIamount\fR defaults to 0. .\" OPTION: -padx .TP \fB\-padx \fIamount\fR . The \fIamount\fR specifies how much horizontal external padding to leave on each side of the content, in screen units. \fIAmount\fR may be a list of two values to specify padding for left and right separately. The \fIamount\fR defaults to 0. This space is added outside the content border. .\" OPTION: -pady .TP \fB\-pady \fIamount\fR . The \fIamount\fR specifies how much vertical external padding to leave on the top and bottom of the content, in screen units. \fIAmount\fR may be a list of two values to specify padding for top and bottom separately. The \fIamount\fR defaults to 0. This space is added outside the content border. .\" OPTION: -row .TP \fB\-row \fIn\fR . Insert the content so that it occupies the \fIn\fRth row in the grid. Row numbers start with 0. If this option is not supplied, then the content is arranged on the same row as the previous content specified on this call to \fBgrid\fR, or the next row after the highest occupied row if this is the first content. .\" OPTION: -rowspan .TP \fB\-rowspan \fIn\fR . Insert the content so that it occupies \fIn\fR rows in the grid. The default is one row. If the next \fBgrid\fR command contains \fB^\fR characters instead of \fIcontent\fR that line up with the columns of this \fIcontent\fR, then the \fBrowspan\fR of this \fIcontent\fR is extended by one. .\" OPTION: -sticky .TP \fB\-sticky \fIstyle\fR . If a content's cell is larger than its requested dimensions, this option may be used to position (or stretch) the content within its cell. \fIStyle\fR is a string that contains zero or more of the characters \fBn\fR, \fBs\fR, \fBe\fR or \fBw\fR. The string can optionally contain spaces or commas, but they are ignored. Each letter refers to a side (north, south, east, or west) that the content will .QW stick to. If both \fBn\fR and \fBs\fR (or \fBe\fR and \fBw\fR) are specified, the content will be stretched to fill the entire height (or width) of its cavity. The \fB\-sticky\fR option subsumes the combination of \fB\-anchor\fR and \fB\-fill\fR that is used by \fBpack\fR. The default is .QW "" , which causes the content to be centered in its cavity, at its requested size. .LP If any of the content is already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values. .RE .\" METHOD: content .TP \fBgrid content \fIwindow\fR ?\fI\-option value\fR? . If no options are supplied, a list of all of the content in \fIwindow\fR is returned, most recently managed first. \fIOption\fR can be either \fB\-row\fR or \fB\-column\fR which causes only the content in the row (or column) specified by \fIvalue\fR to be returned. .\" METHOD: forget .TP \fBgrid forget \fIwindow \fR?\fIwindow ...\fR? . Removes each of the \fIwindow\fRs from grid for its container and unmaps their windows. The content will no longer be managed by the grid geometry manager. The configuration options for that window are forgotten, so that if the window is managed once more by the grid geometry manager, the initial default settings are used. .RS .PP .VS "TIP 518" If the last content window of the container becomes unmanaged, this will also send the virtual event \fB<>\fR to the container; the container may choose to resize itself (or otherwise respond) to such a change. .VE "TIP 518" .RE .\" METHOD: info .TP \fBgrid info \fIwindow\fR . Returns a list whose elements are the current configuration state of the content given by \fIwindow\fR in the same option-value form that might be specified to \fBgrid configure\fR. The first two elements of the list are .QW "\fB\-in \fIcontainer\fR" where \fIcontainer\fR is the windows's container window. .\" METHOD: location .TP \fBgrid location \fIwindow x y\fR . Given \fIx\fR and \fIy\fR values in screen units relative to the container window, the column and row number at that \fIx\fR and \fIy\fR location is returned. For locations that are above or to the left of the grid, \fB\-1\fR is returned. .\" METHOD: propagate .TP \fBgrid propagate \fIwindow\fR ?\fIboolean\fR? . If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR then propagation is enabled for \fIwindow\fR, which must be a window name (see \fBGEOMETRY PROPAGATION\fR below). If \fIboolean\fR has a false boolean value then propagation is disabled for \fIwindow\fR. In either of these cases an empty string is returned. If \fIboolean\fR is omitted then the command returns \fB0\fR or \fB1\fR to indicate whether propagation is currently enabled for \fIwindow\fR. .RS .PP Propagation is enabled by default. .RE .\" METHOD: rowconfigure .TP \fBgrid rowconfigure \fIwindow index \fR?\fI\-option value...\fR? . Query or set the row properties of the \fIindex\fR row of the geometry container, \fIwindow\fR. The valid options are \fB\-minsize\fR, \fB\-weight\fR, \fB\-uniform\fR and \fB\-pad\fR. If one or more options are provided, then \fIindex\fR may be given as a list of row indices to which the configuration options will operate on. Indices may be integers, window names or the keyword \fIall\fR. For \fIall\fR the options apply to all rows currently occupied by content windows. For a window name, that window must be a content window of this container and the options apply to all rows currently occupied by the container window. The \fB\-minsize\fR option sets the minimum size, in screen units, that will be permitted for this row. The \fB\-weight\fR option (an integer value) sets the relative weight for apportioning any extra spaces among rows. A weight of zero (0) indicates the row will not deviate from its requested size. A row whose weight is two will grow at twice the rate as a row of weight one when extra space is allocated to the layout. The \fB\-uniform\fR option, when a non-empty value is supplied, places the row in a \fIuniform group\fR with other rows that have the same value for \fB\-uniform\fR. The space for rows belonging to a uniform group is allocated so that their sizes are always in strict proportion to their \fB\-weight\fR values. See \fBTHE GRID ALGORITHM\fR below for further details. The \fB\-pad\fR option specifies the number of screen units that will be added to the largest window contained completely in that row when the grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the container window and index is specified, all the current settings are returned in a list of .QW "-option value" pairs. .\" METHOD: remove .TP \fBgrid remove \fIwindow \fR?\fIwindow ...\fR? . Removes each of the \fIwindow\fRs from grid for its container and unmaps their windows. The content will no longer be managed by the grid geometry manager. However, the configuration options for that window are remembered, so that if the content window is managed once more by the grid geometry manager, the previous values are retained. .RS .PP .VS "TIP 518" If the last content window of the container becomes unmanaged, this will also send the virtual event \fB<>\fR to the container; the container may choose to resize itself (or otherwise respond) to such a change. .VE "TIP 518" .RE .\" METHOD: size .TP \fBgrid size \fIcontainer\fR . Returns the size of the grid (in columns then rows) for \fIcontainer\fR. The size is determined either by the \fIcontent\fR occupying the largest row or column, or the largest column or row with a \fB\-minsize\fR, \fB\-weight\fR, or \fB\-pad\fR that is non-zero. .\" METHOD: slaves .TP \fBgrid slaves \fIwindow\fR ?\fI\-option value\fR? . Synonym for \fBgrid content \fIwindow\fR ?\fI\-option value\fR?. .SH "RELATIVE PLACEMENT" .PP The \fBgrid\fR command contains a limited set of capabilities that permit layouts to be created without specifying the row and column information for each content. This permits content to be rearranged, added, or removed without the need to explicitly specify row and column information. When no column or row information is specified for a \fIcontent\fR, default values are chosen for \fB\-column\fR, \fB\-row\fR, \fB\-columnspan\fR and \fB\-rowspan\fR at the time the \fIcontent\fR is managed. The values are chosen based upon the current layout of the grid, the position of the \fIcontent\fR relative to other \fIcontent\fRs in the same grid command, and the presence of the characters \fB\-\fR, \fBx\fR, and \fB^\fR in \fBgrid\fR command where \fIcontent\fR names are normally expected. .RS .IP \fB\-\fR This increases the \fB\-columnspan\fR of the \fIcontent\fR to the left. Several \fB\-\fR's in a row will successively increase the number of columns spanned. A \fB\-\fR may not follow a \fB^\fR or a \fBx\fR, nor may it be the first \fIcontent\fR argument to \fBgrid configure\fR. .IP \fBx\fR This leaves an empty column between the \fIcontent\fR on the left and the \fIcontent\fR on the right. .IP \fB^\fR This extends the \fB\-rowspan\fR of the \fIcontent\fR above the \fB^\fR's in the grid. The number of \fB^\fR's in a row must match the number of columns spanned by the \fIcontent\fR above it. .RE .SH "THE GRID ALGORITHM" .PP The grid geometry manager lays out its content in three steps. In the first step, the minimum size needed to fit all of the content is computed, then (if propagation is turned on), a request is made of the container window to become that size. In the second step, the requested size is compared against the actual size of the container. If the sizes are different, then spaces is added to or taken away from the layout as needed. For the final step, each content is positioned in its row(s) and column(s) based on the setting of its \fIsticky\fR flag. .PP To compute the minimum size of a layout, the grid geometry manager first looks at all content whose \fB\-columnspan\fR and \fB\-rowspan\fR values are one, and computes the nominal size of each row or column to be either the \fIminsize\fR for that row or column, or the sum of the \fIpad\fRding plus the size of the largest content, whichever is greater. After that the rows or columns in each uniform group adapt to each other. Then the content whose row-spans or column-spans are greater than one are examined. If a group of rows or columns need to be increased in size in order to accommodate these content, then extra space is added to each row or column in the group according to its \fIweight\fR. For each group whose weights are all zero, the additional space is apportioned equally. .PP When multiple rows or columns belong to a uniform group, the space allocated to them is always in proportion to their weights. (A weight of zero is considered to be 1.) In other words, a row or column configured with \fB\-weight 1 \-uniform a\fR will have exactly the same size as any other row or column configured with \fB\-weight 1 \-uniform a\fR. A row or column configured with \fB\-weight 2 \-uniform b\fR will be exactly twice as large as one that is configured with \fB\-weight 1 \-uniform b\fR. .PP More technically, each row or column in the group will have a size equal to \fIk*weight\fR for some constant \fIk\fR. The constant \fIk\fR is chosen so that no row or column becomes smaller than its minimum size. For example, if all rows or columns in a group have the same weight, then each row or column will have the same size as the largest row or column in the group. .PP For containers whose size is larger than the requested layout, the additional space is apportioned according to the row and column weights. If all of the weights are zero, the layout is placed within its container according to the \fIanchor\fR value. For containers whose size is smaller than the requested layout, space is taken away from columns and rows according to their weights. However, once a column or row shrinks to its minsize, its weight is taken to be zero. If more space needs to be removed from a layout than would be permitted, as when all the rows or columns are at their minimum sizes, the layout is placed and clipped according to the \fIanchor\fR value. .SH "GEOMETRY PROPAGATION" .PP The grid geometry manager normally computes how large a container must be to just exactly meet the needs of its content, and it sets the requested width and height of the container to these dimensions. This causes geometry information to propagate up through a window hierarchy to a top-level window so that the entire sub-tree sizes itself to fit the needs of the leaf windows. However, the \fBgrid propagate\fR command may be used to turn off propagation for one or more containers. If propagation is disabled then grid will not set the requested width and height of the container window. This may be useful if, for example, you wish for a container window to have a fixed size that you specify. .SH "RESTRICTIONS ON CONTAINER WINDOWS" .PP The container for each content must either be the content's parent (the default) or a descendant of the content's parent. This restriction is necessary to guarantee that the content can be placed over any part of its container that is visible without danger of the content being clipped by its parent. In addition, all content in one call to \fBgrid\fR must have the same container. .SH "STACKING ORDER" .PP If the container for a content is not its parent then you must make sure that the content is higher in the stacking order than the container. Otherwise the container will obscure the content and it will appear as if the content has not been managed correctly. The easiest way to make sure the content is higher than the container is to create the container window first: the most recently created window will be highest in the stacking order. .SH CREDITS .PP The \fBgrid\fR command is based on ideas taken from the \fIGridBag\fR geometry manager written by Doug. Stein, and the \fBblt_table\fR geometry manager, written by George Howlett. .SH EXAMPLES .PP A toplevel window containing a text widget and two scrollbars: .PP .CS # Make the widgets toplevel .t text .t.txt -wrap none -xscroll {.t.h set} -yscroll {.t.v set} scrollbar .t.v -orient vertical -command {.t.txt yview} scrollbar .t.h -orient horizontal -command {.t.txt xview} # Lay them out \fBgrid\fR .t.txt .t.v -sticky nsew \fBgrid\fR .t.h -sticky nsew # Tell the text widget to take all the extra room \fBgrid rowconfigure\fR .t .t.txt -weight 1 \fBgrid columnconfigure\fR .t .t.txt -weight 1 .CE .PP Three widgets of equal width, despite their different .QW natural widths: .PP .CS button .b -text "Foo" entry .e -textvariable foo ; set foo "Hello World!" label .l -text "This is a fairly long piece of text" \fBgrid\fR .b .e .l -sticky ew \fBgrid columnconfigure\fR . "all" -uniform allTheSame .CE .SH "SEE ALSO" pack(n), place(n) .SH KEYWORDS geometry manager, location, grid, cell, propagation, size, pack '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/HandleEvent.30000644001000000100000000000320315105057705020073 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_HandleEvent 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_HandleEvent \- invoke event handlers for window system events .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_HandleEvent\fR(\fIeventPtr\fR) .fi .SH ARGUMENTS .AS XEvent *eventPtr .AP XEvent *eventPtr in Pointer to X event to dispatch to relevant handler(s). It is important that all unused fields of the structure be set to zero. .BE .SH DESCRIPTION .PP \fBTk_HandleEvent\fR is a lower-level procedure that deals with window events. It is called by \fBTcl_ServiceEvent\fR (and indirectly by \fBTcl_DoOneEvent\fR), and in a few other cases within Tk. It makes callbacks to any window event handlers (created by calls to \fBTk_CreateEventHandler\fR) that match \fIeventPtr\fR and then returns. In some cases it may be useful for an application to bypass the Tk event queue and call \fBTk_HandleEvent\fR directly instead of calling \fBTcl_QueueEvent\fR followed by \fBTcl_ServiceEvent\fR. .PP This procedure may be invoked recursively. For example, it is possible to invoke \fBTk_HandleEvent\fR recursively from a handler called by \fBTk_HandleEvent\fR. This sort of operation is useful in some modal situations, such as when a notifier has been popped up and an application wishes to wait for the user to click a button in the notifier before doing anything else. .SH KEYWORDS callback, event, handler, window tk9.0.3/doc/HWNDToWindow.30000644001000000100000000000116115105057705020132 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tk_HWNDToWindow 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_HWNDToWindow \- Find Tk's window information for a Windows window .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Window \fBTk_HWNDToWindow\fR(\fIhwnd\fR) .fi .SH ARGUMENTS .AP HWND hwnd in Windows handle for the window. .BE .SH DESCRIPTION .PP Given a Windows HWND window identifier, this procedure returns the corresponding Tk_Window handle. If there is no Tk_Window corresponding to \fIhwnd\fR then NULL is returned. .SH KEYWORDS Windows window id tk9.0.3/doc/IdToWindow.30000644001000000100000000000146615105057705017736 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_IdToWindow 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_IdToWindow \- Find Tk's window information for an X window .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Window \fBTk_IdToWindow\fR(\fIdisplay, window\fR) .fi .SH ARGUMENTS .AS Tk_Window display .AP Display *display in X display containing the window. .AP Window window in X id for window. .BE .SH DESCRIPTION .PP Given an X window identifier and the X display it corresponds to, this procedure returns the corresponding Tk_Window handle. If there is no Tk_Window corresponding to \fIwindow\fR then NULL is returned. .SH KEYWORDS X window id tk9.0.3/doc/image.n0000644001000000100000000001121615105057705017056 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH image n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME image \- Create and manipulate images .SH SYNOPSIS \fBimage\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBimage\fR command is used to create, delete, and query images. It can take several different forms, depending on the \fIoption\fR argument. The legal forms are: .\" METHOD: create .TP \fBimage create \fItype \fR?\fIname\fR? ?\fIoption value ...\fR? . Creates a new image and a command with the same name and returns its name. \fItype\fR specifies the type of the image, which must be one of the types currently defined (e.g., \fBbitmap\fR). \fIname\fR specifies the name for the image; if it is omitted then Tk picks a name of the form \fBimage\fIx\fR, where \fIx\fR is an integer. There may be any number of \fIoption\fR\-\fIvalue\fR pairs, which provide configuration options for the new image. The legal set of options is defined separately for each image type; see below for details on the options for built-in image types. If an image already exists by the given name then it is replaced with the new image and any instances of that image will redisplay with the new contents. It is important to note that the image command will silently overwrite any procedure that may currently be defined by the given name, so choose the name wisely. It is recommended to use a separate namespace for image names (e.g., \fB::img::logo\fR, \fB::img::large\fR). .\" METHOD: delete .TP \fBimage delete \fR?\fIname name\fR ...? . Deletes each of the named images and returns an empty string. If there are instances of the images displayed in widgets, the images will not actually be deleted until all of the instances are released. However, the association between the instances and the image manager will be dropped. Existing instances will retain their sizes but redisplay as empty areas. If a deleted image is recreated with another call to \fBimage create\fR, the existing instances will use the new image. .\" METHOD: height .TP \fBimage height \fIname\fR . Returns a decimal string giving the height of image \fIname\fR in pixels. .\" METHOD: inuse .TP \fBimage inuse \fIname\fR . Returns a boolean value indicating whether or not the image given by \fIname\fR is in use by any widgets. .\" METHOD: names .TP \fBimage names\fR . Returns a list containing the names of all existing images. .\" METHOD: type .TP \fBimage type \fIname\fR . Returns the type of image \fIname\fR (the value of the \fItype\fR argument to \fBimage create\fR when the image was created). .\" METHOD: types .TP \fBimage types\fR . Returns a list whose elements are all of the valid image types (i.e., all of the values that may be supplied for the \fItype\fR argument to \fBimage create\fR). .\" METHOD: width .TP \fBimage width \fIname\fR . Returns a decimal string giving the width of image \fIname\fR in pixels. .PP Additional operations (e.g. writing the image to a file) may be available as subcommands of the image instance command. See the manual page for the particular image type for details. .SH "BUILT-IN IMAGE TYPES" .PP The following image types are defined by Tk so they will be available in any Tk application. Individual applications or extensions may define additional types. .IP \fBbitmap\fR Each pixel in the image displays a foreground color, a background color, or nothing. See the \fBbitmap\fR manual entry for more information. .IP \fBphoto\fR Displays a variety of full-color images, using dithering to approximate colors on displays with limited color capabilities. See the \fBphoto\fR manual entry for more information. .IP \fBnsimage\fR This type is only available in the Aqua platform. It is a full-color image which may be created from a named system image. It has options designed to facilitate the use of these images in buttons. An \fBnsimage\fR can be based on an a \fItemplate image\fR, which is an anti-aliased 2-color image format that automatically interchanges black and white in response to changes between the light and dark modes on macOS. An \fBnsimage\fR can also generate an alternate \fIpressed\fR variant which is lighter in dark mode and darker in light mode. These are for use in image buttons. See the \fBnsimage\fR manual entry for more information. .SH "SEE ALSO" bitmap(n), options(n), photo(n), nsimage(n) .SH KEYWORDS height, image, types of images, width '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ImgChanged.30000644001000000100000000000450515105057705017672 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_ImageChanged 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_ImageChanged \- notify widgets that image needs to be redrawn .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_ImageChanged\fR(\fImodel, x, y, width, height, imageWidth, imageHeight\fR) .fi .SH ARGUMENTS .AS Tk_ImageModel imageHeight .AP Tk_ImageModel model in Token for image, which was passed to image's \fIcreateProc\fR when the image was created. .AP int x in X-coordinate of upper-left corner of region that needs redisplay (measured from upper-left corner of image). .AP int y in Y-coordinate of upper-left corner of region that needs redisplay (measured from upper-left corner of image). .AP "int" width in Width of region that needs to be redrawn, in pixels. .AP "int" height in Height of region that needs to be redrawn, in pixels. .AP "int" imageWidth in Current width of image, in pixels. .AP "int" imageHeight in Current height of image, in pixels. .BE .SH DESCRIPTION .PP An image manager calls \fBTk_ImageChanged\fR for an image whenever anything happens that requires the image to be redrawn. As a result of calling \fBTk_ImageChanged\fR, any widgets using the image are notified so that they can redisplay themselves appropriately. The \fImodel\fR argument identifies the image, and \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular region within the image that needs to be redrawn. \fIimageWidth\fR and \fIimageHeight\fR specify the image's (new) size. .PP An image manager should call \fBTk_ImageChanged\fR during its \fIcreateProc\fR to specify the image's initial size and to force redisplay if there are existing instances for the image. If any of the pixel values in the image should change later on, \fBTk_ImageChanged\fR should be called again with \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR values that cover all the pixels that changed. If the size of the image should change, then \fBTk_ImageChanged\fR must be called to indicate the new size, even if no pixels need to be redisplayed. .SH "SEE ALSO" Tk_CreateImageType .SH KEYWORDS images, redisplay, image size changes tk9.0.3/doc/Inactive.30000644001000000100000000000204215105057705017440 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH Tk_GetUserInactiveTime 3 8.5 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_GetUserInactiveTime, Tk_ResetUserInactiveTime \- discover user inactivity time .SH SYNOPSIS .nf \fB#include \fR .sp long \fBTk_GetUserInactiveTime\fR(\fIdisplay\fR) .sp \fBTk_ResetUserInactiveTime\fR(\fIdisplay\fR) .fi .SH ARGUMENTS .AS Display *display .AP Display *display in The display on which the user inactivity timer is to be queried or reset. .BE .SH DESCRIPTION .PP \fBTk_GetUserInactiveTime\fR returns the number of milliseconds that have passed since the last user interaction (usually via keyboard or mouse) with the respective display. On systems and displays that do not support querying the user inactivity time, \fB\-1\fR is returned. \fBTk_ResetUserInactiveTime\fR resets the user inactivity timer of the given display to zero. On windowing systems that do not support multiple displays \fIdisplay\fR can be passed as \fBNULL\fR. .SH KEYWORDS idle, inactive tk9.0.3/doc/InternAtom.30000644001000000100000000000360115105057705017760 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_InternAtom 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms .SH SYNOPSIS .nf \fB#include \fR .sp Atom \fBTk_InternAtom\fR(\fItkwin, name\fR) .sp const char * \fBTk_GetAtomName\fR(\fItkwin, atom\fR) .fi .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window. Used to map atom or name relative to a particular display. .AP "const char" *name in String name for which atom is desired. .AP Atom atom in Atom for which corresponding string name is desired. .BE .SH DESCRIPTION .PP These procedures are similar to the Xlib procedures \fBXInternAtom\fR and \fBXGetAtomName\fR. \fBTk_InternAtom\fR returns the atom identifier associated with string given by \fIname\fR; the atom identifier is only valid for the display associated with \fItkwin\fR. \fBTk_GetAtomName\fR returns the string associated with \fIatom\fR on \fItkwin\fR's display. The string returned by \fBTk_GetAtomName\fR is in Tk's storage: the caller need not free this space when finished with the string, and the caller should not modify the contents of the returned string. If there is no atom \fIatom\fR on \fItkwin\fR's display, then \fBTk_GetAtomName\fR returns the string .QW "?bad atom?" . .PP Tk caches the information returned by \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR so that future calls for the same information can be serviced from the cache without contacting the server. Thus \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR are generally much faster than their Xlib counterparts, and they should be used in place of the Xlib procedures. .SH KEYWORDS atom, cache, display tk9.0.3/doc/keysyms.n0000644001000000100000000024041015105057705017500 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" .TH keysyms n 8.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME keysyms \- keysyms recognized by Tk .BE .SH DESCRIPTION .PP Tk recognizes many keysyms when specifying key bindings (e.g., .QW "\fBbind\fR \fB. <\fR\fIkeysym\fR\fB>\fR" ). The following list enumerates the keysyms that will be recognized by Tk. Note that not all keysyms will be valid on all platforms, and some keysyms are also available on platforms that have a different native name for that key. For example, on Unix systems, the presence of a particular keysym is dependent on the configuration of the keyboard modifier map. This list shows keysyms along with their decimal and hexadecimal values. .PP .CS space 32 0x20 ! (exclam) 33 0x21 quotedbl 34 0x22 numbersign 35 0x23 dollar 36 0x24 % (percent) 37 0x25 & (ampersand) 38 0x26 ' (apostrophe) 39 0x27 ( (parenleft) 40 0x28 ) (parenright) 41 0x29 * (asterisk) 42 0x2A + (plus) 43 0x2B , (comma) 44 0x2C minus 45 0x2D . (period) 46 0x2E / (slash) 47 0x2F 0 48 0x30 1 49 0x31 2 50 0x32 3 51 0x33 4 52 0x34 5 53 0x35 6 54 0x36 7 55 0x37 8 56 0x38 9 57 0x39 : (colon) 58 0x3A semicolon 59 0x3B less 60 0x3C = (equal) 61 0x3D greater 62 0x3E ? (question) 63 0x3F @ (at) 64 0x40 A 65 0x41 B 66 0x42 C 67 0x43 D 68 0x44 E 69 0x45 F 70 0x46 G 71 0x47 H 72 0x48 I 73 0x49 J 74 0x4A K 75 0x4B L 76 0x4C M 77 0x4D N 78 0x4E O 79 0x4F P 80 0x50 Q 81 0x51 R 82 0x52 S 83 0x53 T 84 0x54 U 85 0x55 V 86 0x56 W 87 0x57 X 88 0x58 Y 89 0x59 Z 90 0x5A bracketleft 91 0x5B backslash 92 0x5C bracketright 93 0x5D ^ (asciicircum) 94 0x5E _ (underscore) 95 0x5F ` (grave) 96 0x60 a 97 0x61 b 98 0x62 c 99 0x63 d 100 0x64 e 101 0x65 f 102 0x66 g 103 0x67 h 104 0x68 i 105 0x69 j 106 0x6A k 107 0x6B l 108 0x6C m 109 0x6D n 110 0x6E o 111 0x6F p 112 0x70 q 113 0x71 r 114 0x72 s 115 0x73 t 116 0x74 u 117 0x75 v 118 0x76 w 119 0x77 x 120 0x78 y 121 0x79 z 122 0x7A braceleft 123 0x7B | (bar) 124 0x7C braceright 125 0x7D ~ (asciitilde) 126 0x7E nobreakspace 160 0xA0 \(r! (exclamdown) 161 0xA1 \(ct (cent) 162 0xA2 \(Po (sterling) 163 0xA3 \(Cs (currency) 164 0xA4 \(Ye (yen) 165 0xA5 \(bb (brokenbar) 166 0xA6 \(sc (section) 167 0xA7 \(ad (diaeresis) 168 0xA8 \(co (copyright) 169 0xA9 \(Of (ordfeminine) 170 0xAA \(Fo (guillemetleft) 171 0xAB \(no (notsign) 172 0xAC hyphen 173 0xAD \(rg (registered) 174 0xAE \(a- (macron) 175 0xAF \(de (degree) 176 0xB0 \(+- (plusminus) 177 0xB1 \(S2 (twosuperior) 178 0xB2 \(S3 (threesuperior) 179 0xB3 \(aa (acute) 180 0xB4 \(mc (mu) 181 0xB5 \(ps (paragraph) 182 0xB6 \(pc (periodcentered) 183 0xB7 \(ac (cedilla) 184 0xB8 \(S1 (onesuperior) 185 0xB9 \(Om (ordmasculine) 186 0xBA \(Fc (guillemetright) 187 0xBB \(14 (onequarter) 188 0xBC \(12 (onehalf) 189 0xBD \(34 (threequarters) 190 0xBE \(r? (questiondown) 191 0xBF \(`A (Agrave) 192 0xC0 \('A (Aacute) 193 0xC1 \(^A (Acircumflex) 194 0xC2 \(~A (Atilde) 195 0xC3 \(:A (Adiaeresis) 196 0xC4 \(oA (Aring) 197 0xC5 \(AE (AE) 198 0xC6 \(,C (Ccedilla) 199 0xC7 \(`E (Egrave) 200 0xC8 \('E (Eacute) 201 0xC9 \(^E (Ecircumflex) 202 0xCA \(:E (Ediaeresis) 203 0xCB \(`I (Igrave) 204 0xCC \('I (Iacute) 205 0xCD \(^I (Icircumflex) 206 0xCE \(:I (Idiaeresis) 207 0xCF \(-D (ETH) 208 0xD0 \(~N (Ntilde) 209 0xD1 \(`O (Ograve) 210 0xD2 \('O (Oacute) 211 0xD3 \(^O (Ocircumflex) 212 0xD4 \(~O (Otilde) 213 0xD5 \(:O (Odiaeresis) 214 0xD6 \(mu (multiply) 215 0xD7 \(/O (Oslash) 216 0xD8 \(`U (Ugrave) 217 0xD9 \('U (Uacute) 218 0xDA \(^U (Ucircumflex) 219 0xDB \(:U (Udiaeresis) 220 0xDC \('Y (Yacute) 221 0xDD \(TP (THORN) 222 0xDE \(ss (ssharp) 223 0xDF \(`a (agrave) 224 0xE0 \('a (aacute) 225 0xE1 \(^a (acircumflex) 226 0xE2 \(~a (atilde) 227 0xE3 \(:a (adiaeresis) 228 0xE4 \(oa (aring) 229 0xE5 \(ae (ae) 230 0xE6 \(,c (ccedilla) 231 0xE7 \(`e (egrave) 232 0xE8 \('e (eacute) 233 0xE9 \(^e (ecircumflex) 234 0xEA \(:e (ediaeresis) 235 0xEB \(`i (igrave) 236 0xEC \('i (iacute) 237 0xED \(^i (icircumflex) 238 0xEE \(:i (idiaeresis) 239 0xEF \(Sd (eth) 240 0xF0 \(~n (ntilde) 241 0xF1 \(`o (ograve) 242 0xF2 \('o (oacute) 243 0xF3 \(^o (ocircumflex) 244 0xF4 \(~o (otilde) 245 0xF5 \(:o (odiaeresis) 246 0xF6 \(di (division) 247 0xF7 \(/o (oslash) 248 0xF8 \(`u (ugrave) 249 0xF9 \('u (uacute) 250 0xFA \(^u (ucircumflex) 251 0xFB \(:u (udiaeresis) 252 0xFC \('y (yacute) 253 0xFD \(Tp (thorn) 254 0xFE \(:y (ydiaeresis) 255 0xFF .CE .CS Aogonek 417 0x1A1 breve 418 0x1A2 Lstroke 419 0x1A3 Lcaron 421 0x1A5 Sacute 422 0x1A6 Scaron 425 0x1A9 Scedilla 426 0x1AA Tcaron 427 0x1AB Zacute 428 0x1AC Zcaron 430 0x1AE Zabovedot 431 0x1AF aogonek 433 0x1B1 ogonek 434 0x1B2 lstroke 435 0x1B3 lcaron 437 0x1B5 sacute 438 0x1B6 caron 439 0x1B7 scaron 441 0x1B9 scedilla 442 0x1BA tcaron 443 0x1BB zacute 444 0x1BC doubleacute 445 0x1BD zcaron 446 0x1BE zabovedot 447 0x1BF Racute 448 0x1C0 Abreve 451 0x1C3 Lacute 453 0x1C5 Cacute 454 0x1C6 Ccaron 456 0x1C8 Eogonek 458 0x1CA Ecaron 460 0x1CC Dcaron 463 0x1CF Dstroke 464 0x1D0 Nacute 465 0x1D1 Ncaron 466 0x1D2 Odoubleacute 469 0x1D5 Rcaron 472 0x1D8 Uring 473 0x1D9 Udoubleacute 475 0x1DB Tcedilla 478 0x1DE racute 480 0x1E0 abreve 483 0x1E3 lacute 485 0x1E5 cacute 486 0x1E6 ccaron 488 0x1E8 eogonek 490 0x1EA ecaron 492 0x1EC dcaron 495 0x1EF dstroke 496 0x1F0 nacute 497 0x1F1 ncaron 498 0x1F2 odoubleacute 501 0x1F5 rcaron 504 0x1F8 uring 505 0x1F9 udoubleacute 507 0x1FB tcedilla 510 0x1FE abovedot 511 0x1FF Hstroke 673 0x2A1 Hcircumflex 678 0x2A6 Iabovedot 681 0x2A9 Gbreve 683 0x2AB Jcircumflex 684 0x2AC hstroke 689 0x2B1 hcircumflex 694 0x2B6 idotless 697 0x2B9 gbreve 699 0x2BB jcircumflex 700 0x2BC Cabovedot 709 0x2C5 Ccircumflex 710 0x2C6 Gabovedot 725 0x2D5 Gcircumflex 728 0x2D8 Ubreve 733 0x2DD Scircumflex 734 0x2DE cabovedot 741 0x2E5 ccircumflex 742 0x2E6 gabovedot 757 0x2F5 gcircumflex 760 0x2F8 ubreve 765 0x2FD scircumflex 766 0x2FE kra 930 0x3A2 Rcedilla 931 0x3A3 Itilde 933 0x3A5 Lcedilla 934 0x3A6 Emacron 938 0x3AA Gcedilla 939 0x3AB Tslash 940 0x3AC rcedilla 947 0x3B3 itilde 949 0x3B5 lcedilla 950 0x3B6 emacron 954 0x3BA gcedilla 955 0x3BB tslash 956 0x3BC ENG 957 0x3BD eng 959 0x3BF Amacron 960 0x3C0 Iogonek 967 0x3C7 Eabovedot 972 0x3CC Imacron 975 0x3CF Ncedilla 977 0x3D1 Omacron 978 0x3D2 Kcedilla 979 0x3D3 Uogonek 985 0x3D9 Utilde 989 0x3DD Umacron 990 0x3DE amacron 992 0x3E0 iogonek 999 0x3E7 eabovedot 1004 0x3EC imacron 1007 0x3EF ncedilla 1009 0x3F1 omacron 1010 0x3F2 kcedilla 1011 0x3F3 uogonek 1017 0x3F9 utilde 1021 0x3FD umacron 1022 0x3FE overline 1150 0x47E kana_fullstop 1185 0x4A1 kana_openingbracket 1186 0x4A2 kana_closingbracket 1187 0x4A3 kana_comma 1188 0x4A4 kana_conjunctive 1189 0x4A5 kana_WO 1190 0x4A6 kana_a 1191 0x4A7 kana_i 1192 0x4A8 kana_u 1193 0x4A9 kana_e 1194 0x4AA kana_o 1195 0x4AB kana_ya 1196 0x4AC kana_yu 1197 0x4AD kana_yo 1198 0x4AE kana_tsu 1199 0x4AF prolongedsound 1200 0x4B0 kana_A 1201 0x4B1 kana_I 1202 0x4B2 kana_U 1203 0x4B3 kana_E 1204 0x4B4 kana_O 1205 0x4B5 kana_KA 1206 0x4B6 kana_KI 1207 0x4B7 kana_KU 1208 0x4B8 kana_KE 1209 0x4B9 kana_KO 1210 0x4BA kana_SA 1211 0x4BB kana_SHI 1212 0x4BC kana_SU 1213 0x4BD kana_SE 1214 0x4BE kana_SO 1215 0x4BF kana_TA 1216 0x4C0 kana_CHI 1217 0x4C1 kana_TSU 1218 0x4C2 kana_TE 1219 0x4C3 kana_TO 1220 0x4C4 kana_NA 1221 0x4C5 kana_NI 1222 0x4C6 kana_NU 1223 0x4C7 kana_NE 1224 0x4C8 kana_NO 1225 0x4C9 kana_HA 1226 0x4CA kana_HI 1227 0x4CB kana_FU 1228 0x4CC kana_HE 1229 0x4CD kana_HO 1230 0x4CE kana_MA 1231 0x4CF kana_MI 1232 0x4D0 kana_MU 1233 0x4D1 kana_ME 1234 0x4D2 kana_MO 1235 0x4D3 kana_YA 1236 0x4D4 kana_YU 1237 0x4D5 kana_YO 1238 0x4D6 kana_RA 1239 0x4D7 kana_RI 1240 0x4D8 kana_RU 1241 0x4D9 kana_RE 1242 0x4DA kana_RO 1243 0x4DB kana_WA 1244 0x4DC kana_N 1245 0x4DD voicedsound 1246 0x4DE semivoicedsound 1247 0x4DF .CE .CS Arabic_comma 1452 0x5AC Arabic_semicolon 1467 0x5BB Arabic_question_mark 1471 0x5BF Arabic_hamza 1473 0x5C1 Arabic_maddaonalef 1474 0x5C2 Arabic_hamzaonalef 1475 0x5C3 Arabic_hamzaonwaw 1476 0x5C4 Arabic_hamzaunderalef 1477 0x5C5 Arabic_hamzaonyeh 1478 0x5C6 Arabic_alef 1479 0x5C7 Arabic_beh 1480 0x5C8 Arabic_tehmarbuta 1481 0x5C9 Arabic_teh 1482 0x5CA Arabic_theh 1483 0x5CB Arabic_jeem 1484 0x5CC Arabic_hah 1485 0x5CD Arabic_khah 1486 0x5CE Arabic_dal 1487 0x5CF Arabic_thal 1488 0x5D0 Arabic_ra 1489 0x5D1 Arabic_zain 1490 0x5D2 Arabic_seen 1491 0x5D3 Arabic_sheen 1492 0x5D4 Arabic_sad 1493 0x5D5 Arabic_dad 1494 0x5D6 Arabic_tah 1495 0x5D7 Arabic_zah 1496 0x5D8 Arabic_ain 1497 0x5D9 Arabic_ghain 1498 0x5DA Arabic_tatweel 1504 0x5E0 Arabic_feh 1505 0x5E1 Arabic_qaf 1506 0x5E2 Arabic_kaf 1507 0x5E3 Arabic_lam 1508 0x5E4 Arabic_meem 1509 0x5E5 Arabic_noon 1510 0x5E6 Arabic_ha 1511 0x5E7 Arabic_waw 1512 0x5E8 Arabic_alefmaksura 1513 0x5E9 Arabic_yeh 1514 0x5EA Arabic_fathatan 1515 0x5EB Arabic_dammatan 1516 0x5EC Arabic_kasratan 1517 0x5ED Arabic_fatha 1518 0x5EE Arabic_damma 1519 0x5EF Arabic_kasra 1520 0x5F0 Arabic_shadda 1521 0x5F1 Arabic_sukun 1522 0x5F2 Serbian_dje 1697 0x6A1 Macedonia_gje 1698 0x6A2 Cyrillic_io 1699 0x6A3 Ukrainian_ie 1700 0x6A4 Macedonia_dse 1701 0x6A5 Ukrainian_i 1702 0x6A6 Ukrainian_yi 1703 0x6A7 Cyrillic_je 1704 0x6A8 Cyrillic_lje 1705 0x6A9 Cyrillic_nje 1706 0x6AA Serbian_tshe 1707 0x6AB Macedonia_kje 1708 0x6AC Ukrainian_ghe_with_upturn 1709 0x6AD Byelorussian_shortu 1710 0x6AE Cyrillic_dzhe 1711 0x6AF numerosign 1712 0x6B0 Serbian_DJE 1713 0x6B1 Macedonia_GJE 1714 0x6B2 Cyrillic_IO 1715 0x6B3 Ukrainian_IE 1716 0x6B4 Macedonia_DSE 1717 0x6B5 Ukrainian_I 1718 0x6B6 Ukrainian_YI 1719 0x6B7 Cyrillic_JE 1720 0x6B8 Cyrillic_LJE 1721 0x6B9 Cyrillic_NJE 1722 0x6BA Serbian_TSHE 1723 0x6BB Macedonia_KJE 1724 0x6BC Ukrainian_GHE_WITH_UPTURN 1725 0x6BD Byelorussian_SHORTU 1726 0x6BE Cyrillic_DZHE 1727 0x6BF Cyrillic_yu 1728 0x6C0 Cyrillic_a 1729 0x6C1 Cyrillic_be 1730 0x6C2 Cyrillic_tse 1731 0x6C3 Cyrillic_de 1732 0x6C4 Cyrillic_ie 1733 0x6C5 Cyrillic_ef 1734 0x6C6 Cyrillic_ghe 1735 0x6C7 Cyrillic_ha 1736 0x6C8 Cyrillic_i 1737 0x6C9 Cyrillic_shorti 1738 0x6CA Cyrillic_ka 1739 0x6CB Cyrillic_el 1740 0x6CC Cyrillic_em 1741 0x6CD Cyrillic_en 1742 0x6CE Cyrillic_o 1743 0x6CF Cyrillic_pe 1744 0x6D0 Cyrillic_ya 1745 0x6D1 Cyrillic_er 1746 0x6D2 Cyrillic_es 1747 0x6D3 Cyrillic_te 1748 0x6D4 Cyrillic_u 1749 0x6D5 Cyrillic_zhe 1750 0x6D6 Cyrillic_ve 1751 0x6D7 Cyrillic_softsign 1752 0x6D8 Cyrillic_yeru 1753 0x6D9 Cyrillic_ze 1754 0x6DA Cyrillic_sha 1755 0x6DB Cyrillic_e 1756 0x6DC Cyrillic_shcha 1757 0x6DD Cyrillic_che 1758 0x6DE Cyrillic_hardsign 1759 0x6DF Cyrillic_YU 1760 0x6E0 Cyrillic_A 1761 0x6E1 Cyrillic_BE 1762 0x6E2 Cyrillic_TSE 1763 0x6E3 Cyrillic_DE 1764 0x6E4 Cyrillic_IE 1765 0x6E5 Cyrillic_EF 1766 0x6E6 Cyrillic_GHE 1767 0x6E7 Cyrillic_HA 1768 0x6E8 Cyrillic_I 1769 0x6E9 Cyrillic_SHORTI 1770 0x6EA Cyrillic_KA 1771 0x6EB Cyrillic_EL 1772 0x6EC Cyrillic_EM 1773 0x6ED Cyrillic_EN 1774 0x6EE Cyrillic_O 1775 0x6EF Cyrillic_PE 1776 0x6F0 Cyrillic_YA 1777 0x6F1 Cyrillic_ER 1778 0x6F2 Cyrillic_ES 1779 0x6F3 Cyrillic_TE 1780 0x6F4 Cyrillic_U 1781 0x6F5 Cyrillic_ZHE 1782 0x6F6 Cyrillic_VE 1783 0x6F7 Cyrillic_SOFTSIGN 1784 0x6F8 Cyrillic_YERU 1785 0x6F9 Cyrillic_ZE 1786 0x6FA Cyrillic_SHA 1787 0x6FB Cyrillic_E 1788 0x6FC Cyrillic_SHCHA 1789 0x6FD Cyrillic_CHE 1790 0x6FE Cyrillic_HARDSIGN 1791 0x6FF Greek_ALPHAaccent 1953 0x7A1 Greek_EPSILONaccent 1954 0x7A2 Greek_ETAaccent 1955 0x7A3 Greek_IOTAaccent 1956 0x7A4 Greek_IOTAdieresis 1957 0x7A5 Greek_IOTAaccentdiaeresis 1958 0x7A6 Greek_OMICRONaccent 1959 0x7A7 Greek_UPSILONaccent 1960 0x7A8 Greek_UPSILONdieresis 1961 0x7A9 Greek_UPSILONaccentdieresis 1962 0x7AA Greek_OMEGAaccent 1963 0x7AB Greek_accentdieresis 1966 0x7AE Greek_horizbar 1967 0x7AF Greek_alphaaccent 1969 0x7B1 Greek_epsilonaccent 1970 0x7B2 Greek_etaaccent 1971 0x7B3 Greek_iotaaccent 1972 0x7B4 Greek_iotadieresis 1973 0x7B5 Greek_iotaaccentdieresis 1974 0x7B6 Greek_omicronaccent 1975 0x7B7 Greek_upsilonaccent 1976 0x7B8 Greek_upsilondieresis 1977 0x7B9 Greek_upsilonaccentdieresis 1978 0x7BA Greek_omegaaccent 1979 0x7BB Greek_ALPHA 1985 0x7C1 Greek_BETA 1986 0x7C2 Greek_GAMMA 1987 0x7C3 Greek_DELTA 1988 0x7C4 Greek_EPSILON 1989 0x7C5 Greek_ZETA 1990 0x7C6 Greek_ETA 1991 0x7C7 Greek_THETA 1992 0x7C8 Greek_IOTA 1993 0x7C9 Greek_KAPPA 1994 0x7CA Greek_LAMBDA 1995 0x7CB Greek_MU 1996 0x7CC Greek_NU 1997 0x7CD Greek_XI 1998 0x7CE Greek_OMICRON 1999 0x7CF Greek_PI 2000 0x7D0 Greek_RHO 2001 0x7D1 Greek_SIGMA 2002 0x7D2 Greek_TAU 2004 0x7D4 Greek_UPSILON 2005 0x7D5 Greek_PHI 2006 0x7D6 Greek_CHI 2007 0x7D7 Greek_PSI 2008 0x7D8 Greek_OMEGA 2009 0x7D9 Greek_alpha 2017 0x7E1 Greek_beta 2018 0x7E2 Greek_gamma 2019 0x7E3 Greek_delta 2020 0x7E4 Greek_epsilon 2021 0x7E5 Greek_zeta 2022 0x7E6 Greek_eta 2023 0x7E7 Greek_theta 2024 0x7E8 Greek_iota 2025 0x7E9 Greek_kappa 2026 0x7EA Greek_lambda 2027 0x7EB Greek_mu 2028 0x7EC Greek_nu 2029 0x7ED Greek_xi 2030 0x7EE Greek_omicron 2031 0x7EF Greek_pi 2032 0x7F0 Greek_rho 2033 0x7F1 Greek_sigma 2034 0x7F2 Greek_finalsmallsigma 2035 0x7F3 Greek_tau 2036 0x7F4 Greek_upsilon 2037 0x7F5 Greek_phi 2038 0x7F6 Greek_chi 2039 0x7F7 Greek_psi 2040 0x7F8 Greek_omega 2041 0x7F9 .CE .CS leftradical 2209 0x8A1 topleftradical 2210 0x8A2 horizconnector 2211 0x8A3 topintegral 2212 0x8A4 botintegral 2213 0x8A5 vertconnector 2214 0x8A6 topleftsqbracket 2215 0x8A7 botleftsqbracket 2216 0x8A8 toprightsqbracket 2217 0x8A9 botrightsqbracket 2218 0x8AA topleftparens 2219 0x8AB botleftparens 2220 0x8AC toprightparens 2221 0x8AD botrightparens 2222 0x8AE leftmiddlecurlybrace 2223 0x8AF rightmiddlecurlybrace 2224 0x8B0 topleftsummation 2225 0x8B1 botleftsummation 2226 0x8B2 topvertsummationconnector 2227 0x8B3 botvertsummationconnector 2228 0x8B4 toprightsummation 2229 0x8B5 botrightsummation 2230 0x8B6 rightmiddlesummation 2231 0x8B7 lessthanequal 2236 0x8BC notequal 2237 0x8BD greaterthanequal 2238 0x8BE integral 2239 0x8BF therefore 2240 0x8C0 variation 2241 0x8C1 infinity 2242 0x8C2 nabla 2245 0x8C5 approximate 2248 0x8C8 similarequal 2249 0x8C9 ifonlyif 2253 0x8CD implies 2254 0x8CE identical 2255 0x8CF radical 2262 0x8D6 includedin 2266 0x8DA includes 2267 0x8DB intersection 2268 0x8DC union 2269 0x8DD logicaland 2270 0x8DE logicalor 2271 0x8DF partialderivative 2287 0x8EF function 2294 0x8F6 leftarrow 2299 0x8FB uparrow 2300 0x8FC rightarrow 2301 0x8FD downarrow 2302 0x8FE blank 2527 0x9DF soliddiamond 2528 0x9E0 checkerboard 2529 0x9E1 ht 2530 0x9E2 ff 2531 0x9E3 cr 2532 0x9E4 lf 2533 0x9E5 nl 2536 0x9E8 vt 2537 0x9E9 lowrightcorner 2538 0x9EA uprightcorner 2539 0x9EB upleftcorner 2540 0x9EC lowleftcorner 2541 0x9ED crossinglines 2542 0x9EE horizlinescan1 2543 0x9EF horizlinescan3 2544 0x9F0 horizlinescan5 2545 0x9F1 horizlinescan7 2546 0x9F2 horizlinescan9 2547 0x9F3 leftt 2548 0x9F4 rightt 2549 0x9F5 bott 2550 0x9F6 topt 2551 0x9F7 vertbar 2552 0x9F8 emspace 2721 0xAA1 enspace 2722 0xAA2 em3space 2723 0xAA3 em4space 2724 0xAA4 digitspace 2725 0xAA5 punctspace 2726 0xAA6 thinspace 2727 0xAA7 hairspace 2728 0xAA8 emdash 2729 0xAA9 endash 2730 0xAAA signifblank 2732 0xAAC ellipsis 2734 0xAAE doubbaselinedot 2735 0xAAF onethird 2736 0xAB0 twothirds 2737 0xAB1 onefifth 2738 0xAB2 twofifths 2739 0xAB3 threefifths 2740 0xAB4 fourfifths 2741 0xAB5 onesixth 2742 0xAB6 fivesixths 2743 0xAB7 careof 2744 0xAB8 figdash 2747 0xABB leftanglebracket 2748 0xABC decimalpoint 2749 0xABD rightanglebracket 2750 0xABE marker 2751 0xABF oneeighth 2755 0xAC3 threeeighths 2756 0xAC4 fiveeighths 2757 0xAC5 seveneighths 2758 0xAC6 trademark 2761 0xAC9 signaturemark 2762 0xACA trademarkincircle 2763 0xACB leftopentriangle 2764 0xACC rightopentriangle 2765 0xACD emopencircle 2766 0xACE emopenrectangle 2767 0xACF leftsinglequotemark 2768 0xAD0 rightsinglequotemark 2769 0xAD1 leftdoublequotemark 2770 0xAD2 rightdoublequotemark 2771 0xAD3 prescription 2772 0xAD4 permille 2773 0xAD5 minutes 2774 0xAD6 seconds 2775 0xAD7 latincross 2777 0xAD9 hexagram 2778 0xADA filledrectbullet 2779 0xADB filledlefttribullet 2780 0xADC filledrighttribullet 2781 0xADD emfilledcircle 2782 0xADE emfilledrect 2783 0xADF enopencircbullet 2784 0xAE0 enopensquarebullet 2785 0xAE1 openrectbullet 2786 0xAE2 opentribulletup 2787 0xAE3 opentribulletdown 2788 0xAE4 openstar 2789 0xAE5 enfilledcircbullet 2790 0xAE6 enfilledsqbullet 2791 0xAE7 filledtribulletup 2792 0xAE8 filledtribulletdown 2793 0xAE9 leftpointer 2794 0xAEA rightpointer 2795 0xAEB club 2796 0xAEC diamond 2797 0xAED heart 2798 0xAEE maltesecross 2800 0xAF0 dagger 2801 0xAF1 doubledagger 2802 0xAF2 checkmark 2803 0xAF3 ballotcross 2804 0xAF4 musicalsharp 2805 0xAF5 musicalflat 2806 0xAF6 malesymbol 2807 0xAF7 femalesymbol 2808 0xAF8 telephone 2809 0xAF9 telephonerecorder 2810 0xAFA phonographcopyright 2811 0xAFB caret 2812 0xAFC singlelowquotemark 2813 0xAFD doublelowquotemark 2814 0xAFE cursor 2815 0xAFF leftcaret 2979 0xBA3 rightcaret 2982 0xBA6 downcaret 2984 0xBA8 upcaret 2985 0xBA9 overbar 3008 0xBC0 downtack 3010 0xBC2 upshoe 3011 0xBC3 downstile 3012 0xBC4 underbar 3014 0xBC6 jot 3018 0xBCA quad 3020 0xBCC uptack 3022 0xBCE circle 3023 0xBCF upstile 3027 0xBD3 downshoe 3030 0xBD6 rightshoe 3032 0xBD8 leftshoe 3034 0xBDA lefttack 3036 0xBDC righttack 3068 0xBFC hebrew_doublelowline 3295 0xCDF hebrew_aleph 3296 0xCE0 hebrew_bet 3297 0xCE1 hebrew_gimel 3298 0xCE2 hebrew_dalet 3299 0xCE3 hebrew_he 3300 0xCE4 hebrew_waw 3301 0xCE5 hebrew_zain 3302 0xCE6 hebrew_chet 3303 0xCE7 hebrew_tet 3304 0xCE8 hebrew_yod 3305 0xCE9 hebrew_finalkaph 3306 0xCEA hebrew_kaph 3307 0xCEB hebrew_lamed 3308 0xCEC hebrew_finalmem 3309 0xCED hebrew_mem 3310 0xCEE hebrew_finalnun 3311 0xCEF hebrew_nun 3312 0xCF0 hebrew_samech 3313 0xCF1 hebrew_ayin 3314 0xCF2 hebrew_finalpe 3315 0xCF3 hebrew_pe 3316 0xCF4 hebrew_finalzade 3317 0xCF5 hebrew_zade 3318 0xCF6 hebrew_qoph 3319 0xCF7 hebrew_resh 3320 0xCF8 hebrew_shin 3321 0xCF9 hebrew_taw 3322 0xCFA .CE .CS Thai_kokai 3489 0xDA1 Thai_khokhai 3490 0xDA2 Thai_khokhuat 3491 0xDA3 Thai_khokhwai 3492 0xDA4 Thai_khokhon 3493 0xDA5 Thai_khorakhang 3494 0xDA6 Thai_ngongu 3495 0xDA7 Thai_chochan 3496 0xDA8 Thai_choching 3497 0xDA9 Thai_chochang 3498 0xDAA Thai_soso 3499 0xDAB Thai_chochoe 3500 0xDAC Thai_yoying 3501 0xDAD Thai_dochada 3502 0xDAE Thai_topatak 3503 0xDAF Thai_thothan 3504 0xDB0 Thai_thonangmontho 3505 0xDB1 Thai_thophuthao 3506 0xDB2 Thai_nonen 3507 0xDB3 Thai_dodek 3508 0xDB4 Thai_totao 3509 0xDB5 Thai_thothung 3510 0xDB6 Thai_thothahan 3511 0xDB7 Thai_thothong 3512 0xDB8 Thai_nonu 3513 0xDB9 Thai_bobaimai 3514 0xDBA Thai_popla 3515 0xDBB Thai_phophung 3516 0xDBC Thai_fofa 3517 0xDBD Thai_phophan 3518 0xDBE Thai_fofan 3519 0xDBF Thai_phosamphao 3520 0xDC0 Thai_moma 3521 0xDC1 Thai_yoyak 3522 0xDC2 Thai_rorua 3523 0xDC3 Thai_ru 3524 0xDC4 Thai_loling 3525 0xDC5 Thai_lu 3526 0xDC6 Thai_wowaen 3527 0xDC7 Thai_sosala 3528 0xDC8 Thai_sorusi 3529 0xDC9 Thai_sosua 3530 0xDCA Thai_hohip 3531 0xDCB Thai_lochula 3532 0xDCC Thai_oang 3533 0xDCD Thai_honokhuk 3534 0xDCE Thai_paiyannoi 3535 0xDCF Thai_saraa 3536 0xDD0 Thai_maihanakat 3537 0xDD1 Thai_saraaa 3538 0xDD2 Thai_saraam 3539 0xDD3 Thai_sarai 3540 0xDD4 Thai_saraii 3541 0xDD5 Thai_saraue 3542 0xDD6 Thai_sarauee 3543 0xDD7 Thai_sarau 3544 0xDD8 Thai_sarauu 3545 0xDD9 Thai_phinthu 3546 0xDDA Thai_maihanakat_maitho 3550 0xDDE Thai_baht 3551 0xDDF Thai_sarae 3552 0xDE0 Thai_saraae 3553 0xDE1 Thai_sarao 3554 0xDE2 Thai_saraaimaimuan 3555 0xDE3 Thai_saraaimaimalai 3556 0xDE4 Thai_lakkhangyao 3557 0xDE5 Thai_maiyamok 3558 0xDE6 Thai_maitaikhu 3559 0xDE7 Thai_maiek 3560 0xDE8 Thai_maitho 3561 0xDE9 Thai_maitri 3562 0xDEA Thai_maichattawa 3563 0xDEB Thai_thanthakhat 3564 0xDEC Thai_nikhahit 3565 0xDED Thai_leksun 3568 0xDF0 Thai_leknung 3569 0xDF1 Thai_leksong 3570 0xDF2 Thai_leksam 3571 0xDF3 Thai_leksi 3572 0xDF4 Thai_lekha 3573 0xDF5 Thai_lekhok 3574 0xDF6 Thai_lekchet 3575 0xDF7 Thai_lekpaet 3576 0xDF8 Thai_lekkao 3577 0xDF9 Hangul_Kiyeog 3745 0xEA1 Hangul_SsangKiyeog 3746 0xEA2 Hangul_KiyeogSios 3747 0xEA3 Hangul_Nieun 3748 0xEA4 Hangul_NieunJieuj 3749 0xEA5 Hangul_NieunHieuh 3750 0xEA6 Hangul_Dikeud 3751 0xEA7 Hangul_SsangDikeud 3752 0xEA8 Hangul_Rieul 3753 0xEA9 Hangul_RieulKiyeog 3754 0xEAA Hangul_RieulMieum 3755 0xEAB Hangul_RieulPieub 3756 0xEAC Hangul_RieulSios 3757 0xEAD Hangul_RieulTieut 3758 0xEAE Hangul_RieulPhieuf 3759 0xEAF Hangul_RieulHieuh 3760 0xEB0 Hangul_Mieum 3761 0xEB1 Hangul_Pieub 3762 0xEB2 Hangul_SsangPieub 3763 0xEB3 Hangul_PieubSios 3764 0xEB4 Hangul_Sios 3765 0xEB5 Hangul_SsangSios 3766 0xEB6 Hangul_Ieung 3767 0xEB7 Hangul_Jieuj 3768 0xEB8 Hangul_SsangJieuj 3769 0xEB9 Hangul_Cieuc 3770 0xEBA Hangul_Khieuq 3771 0xEBB Hangul_Tieut 3772 0xEBC Hangul_Phieuf 3773 0xEBD Hangul_Hieuh 3774 0xEBE Hangul_A 3775 0xEBF Hangul_AE 3776 0xEC0 Hangul_YA 3777 0xEC1 Hangul_YAE 3778 0xEC2 Hangul_EO 3779 0xEC3 Hangul_E 3780 0xEC4 Hangul_YEO 3781 0xEC5 Hangul_YE 3782 0xEC6 Hangul_O 3783 0xEC7 Hangul_WA 3784 0xEC8 Hangul_WAE 3785 0xEC9 Hangul_OE 3786 0xECA Hangul_YO 3787 0xECB Hangul_U 3788 0xECC Hangul_WEO 3789 0xECD Hangul_WE 3790 0xECE Hangul_WI 3791 0xECF Hangul_YU 3792 0xED0 Hangul_EU 3793 0xED1 Hangul_YI 3794 0xED2 Hangul_I 3795 0xED3 Hangul_J_Kiyeog 3796 0xED4 Hangul_J_SsangKiyeog 3797 0xED5 Hangul_J_KiyeogSios 3798 0xED6 Hangul_J_Nieun 3799 0xED7 Hangul_J_NieunJieuj 3800 0xED8 Hangul_J_NieunHieuh 3801 0xED9 Hangul_J_Dikeud 3802 0xEDA Hangul_J_Rieul 3803 0xEDB Hangul_J_RieulKiyeog 3804 0xEDC Hangul_J_RieulMieum 3805 0xEDD Hangul_J_RieulPieub 3806 0xEDE Hangul_J_RieulSios 3807 0xEDF Hangul_J_RieulTieut 3808 0xEE0 Hangul_J_RieulPhieuf 3809 0xEE1 Hangul_J_RieulHieuh 3810 0xEE2 Hangul_J_Mieum 3811 0xEE3 Hangul_J_Pieub 3812 0xEE4 Hangul_J_PieubSios 3813 0xEE5 Hangul_J_Sios 3814 0xEE6 Hangul_J_SsangSios 3815 0xEE7 Hangul_J_Ieung 3816 0xEE8 Hangul_J_Jieuj 3817 0xEE9 Hangul_J_Cieuc 3818 0xEEA Hangul_J_Khieuq 3819 0xEEB Hangul_J_Tieut 3820 0xEEC Hangul_J_Phieuf 3821 0xEED Hangul_J_Hieuh 3822 0xEEE Hangul_RieulYeorinHieuh 3823 0xEEF Hangul_SunkyeongeumMieum 3824 0xEF0 Hangul_SunkyeongeumPieub 3825 0xEF1 Hangul_PanSios 3826 0xEF2 Hangul_KkogjiDalrinIeung 3827 0xEF3 Hangul_SunkyeongeumPhieuf 3828 0xEF4 Hangul_YeorinHieuh 3829 0xEF5 Hangul_AraeA 3830 0xEF6 Hangul_AraeAE 3831 0xEF7 Hangul_J_PanSios 3832 0xEF8 Hangul_J_KkogjiDalrinIeung 3833 0xEF9 Hangul_J_YeorinHieuh 3834 0xEFA Korean_Won 3839 0xEFF OE 5052 0x13BC oe 5053 0x13BD Ydiaeresis 5054 0x13BE \(eu (EuroSign) 8364 0x20AC .CE .CS ISO_Lock 65025 0xFE01 ISO_Level2_Latch 65026 0xFE02 ISO_Level3_Shift 65027 0xFE03 ISO_Level3_Latch 65028 0xFE04 ISO_Level3_Lock 65029 0xFE05 ISO_Group_Latch 65030 0xFE06 ISO_Group_Lock 65031 0xFE07 ISO_Next_Group 65032 0xFE08 ISO_Next_Group_Lock 65033 0xFE09 ISO_Prev_Group 65034 0xFE0A ISO_Prev_Group_Lock 65035 0xFE0B ISO_First_Group 65036 0xFE0C ISO_First_Group_Lock 65037 0xFE0D ISO_Last_Group 65038 0xFE0E ISO_Last_Group_Lock 65039 0xFE0F ISO_Level5_Shift 65041 0xFE11 ISO_Level5_Latch 65042 0xFE12 ISO_Level5_Lock 65043 0xFE13 ISO_Left_Tab 65056 0xFE20 ISO_Move_Line_Up 65057 0xFE21 ISO_Move_Line_Down 65058 0xFE22 ISO_Partial_Line_Up 65059 0xFE23 ISO_Partial_Line_Down 65060 0xFE24 ISO_Partial_Space_Left 65061 0xFE25 ISO_Partial_Space_Right 65062 0xFE26 ISO_Set_Margin_Left 65063 0xFE27 ISO_Set_Margin_Right 65064 0xFE28 ISO_Release_Margin_Left 65065 0xFE29 ISO_Release_Margin_Right 65066 0xFE2A ISO_Release_Both_Margins 65067 0xFE2B ISO_Fast_Cursor_Left 65068 0xFE2C ISO_Fast_Cursor_Right 65069 0xFE2D ISO_Fast_Cursor_Up 65070 0xFE2E ISO_Fast_Cursor_Down 65071 0xFE2F ISO_Continuous_Underline 65072 0xFE30 ISO_Discontinuous_Underline 65073 0xFE31 ISO_Emphasize 65074 0xFE32 ISO_Center_Object 65075 0xFE33 ISO_Enter 65076 0xFE34 dead_grave 65104 0xFE50 dead_acute 65105 0xFE51 dead_circumflex 65106 0xFE52 dead_tilde 65107 0xFE53 dead_macron 65108 0xFE54 dead_breve 65109 0xFE55 dead_abovedot 65110 0xFE56 dead_diaeresis 65111 0xFE57 dead_abovering 65112 0xFE58 dead_doubleacute 65113 0xFE59 dead_caron 65114 0xFE5A dead_cedilla 65115 0xFE5B dead_ogonek 65116 0xFE5C dead_iota 65117 0xFE5D dead_voiced_sound 65118 0xFE5E dead_semivoiced_sound 65119 0xFE5F dead_belowdot 65120 0xFE60 dead_hook 65121 0xFE61 dead_horn 65122 0xFE62 dead_stroke 65123 0xFE63 dead_abovecomma 65124 0xFE64 dead_abovereversedcomma 65125 0xFE65 dead_doublegrave 65126 0xFE66 dead_belowring 65127 0xFE67 dead_belowmacron 65128 0xFE68 dead_belowcircumflex 65129 0xFE69 dead_belowtilde 65130 0xFE6A dead_belowbreve 65131 0xFE6B dead_belowdiaeresis 65132 0xFE6C dead_invertedbreve 65133 0xFE6D dead_belowcomma 65134 0xFE6E dead_currency 65135 0xFE6F AccessX_Enable 65136 0xFE70 AccessX_Feedback_Enable 65137 0xFE71 RepeatKeys_Enable 65138 0xFE72 SlowKeys_Enable 65139 0xFE73 BounceKeys_Enable 65140 0xFE74 StickyKeys_Enable 65141 0xFE75 MouseKeys_Enable 65142 0xFE76 MouseKeys_Accel_Enable 65143 0xFE77 Overlay1_Enable 65144 0xFE78 Overlay2_Enable 65145 0xFE79 AudibleBell_Enable 65146 0xFE7A dead_a 65152 0xFE80 dead_A 65153 0xFE81 dead_e 65154 0xFE82 dead_E 65155 0xFE83 dead_i 65156 0xFE84 dead_I 65157 0xFE85 dead_o 65158 0xFE86 dead_O 65159 0xFE87 dead_u 65160 0xFE88 dead_U 65161 0xFE89 dead_schwa 65162 0xFE8A dead_SCHWA 65163 0xFE8B dead_greek 65164 0xFE8C dead_hamza 65165 0xFE8D dead_lowline 65168 0xFE90 dead_aboveverticalline 65169 0xFE91 dead_belowverticalline 65170 0xFE92 dead_longsolidusoverlay 65171 0xFE93 ch 65184 0xFEA0 Ch 65185 0xFEA1 CH 65186 0xFEA2 c_h 65187 0xFEA3 C_h 65188 0xFEA4 C_H 65189 0xFEA5 First_Virtual_Screen 65232 0xFED0 Prev_Virtual_Screen 65233 0xFED1 Next_Virtual_Screen 65234 0xFED2 Last_Virtual_Screen 65236 0xFED4 Terminate_Server 65237 0xFED5 Pointer_Left 65248 0xFEE0 Pointer_Right 65249 0xFEE1 Pointer_Up 65250 0xFEE2 Pointer_Down 65251 0xFEE3 Pointer_UpLeft 65252 0xFEE4 Pointer_UpRight 65253 0xFEE5 Pointer_DownLeft 65254 0xFEE6 Pointer_DownRight 65255 0xFEE7 Pointer_Button_Dflt 65256 0xFEE8 Pointer_Button1 65257 0xFEE9 Pointer_Button2 65258 0xFEEA Pointer_Button3 65259 0xFEEB Pointer_Button4 65260 0xFEEC Pointer_Button5 65261 0xFEED Pointer_DblClick_Dflt 65262 0xFEEE Pointer_DblClick1 65263 0xFEEF Pointer_DblClick2 65264 0xFEF0 Pointer_DblClick3 65265 0xFEF1 Pointer_DblClick4 65266 0xFEF2 Pointer_DblClick5 65267 0xFEF3 Pointer_Drag_Dflt 65268 0xFEF4 Pointer_Drag1 65269 0xFEF5 Pointer_Drag2 65270 0xFEF6 Pointer_Drag3 65271 0xFEF7 Pointer_Drag4 65272 0xFEF8 Pointer_EnableKeys 65273 0xFEF9 Pointer_Accelerate 65274 0xFEFA Pointer_DfltBtnNext 65275 0xFEFB Pointer_DfltBtnPrev 65276 0xFEFC Pointer_Drag5 65277 0xFEFD .CE .CS BackSpace 65288 0xFF08 Tab 65289 0xFF09 Linefeed 65290 0xFF0A Clear 65291 0xFF0B Return 65293 0xFF0D Pause 65299 0xFF13 Scroll_Lock 65300 0xFF14 Sys_Req 65301 0xFF15 Escape 65307 0xFF1B Multi_key 65312 0xFF20 Kanji 65313 0xFF21 Muhenkan 65314 0xFF22 Henkan 65315 0xFF23 Romaji 65316 0xFF24 Hiragana 65317 0xFF25 Katakana 65318 0xFF26 Hiragana_Katakana 65319 0xFF27 Zenkaku 65320 0xFF28 Hankaku 65321 0xFF29 Zenkaku_Hankaku 65322 0xFF2A Touroku 65323 0xFF2B Massyo 65324 0xFF2C Kana_Lock 65325 0xFF2D Kana_Shift 65326 0xFF2E Eisu_Shift 65327 0xFF2F Eisu_toggle 65328 0xFF30 Hangul 65329 0xFF31 Hangul_Start 65330 0xFF32 Hangul_End 65331 0xFF33 Hangul_Hanja 65332 0xFF34 Hangul_Jamo 65333 0xFF35 Hangul_Romaja 65334 0xFF36 Codeinput 65335 0xFF37 Hangul_Jeonja 65336 0xFF38 Hangul_Banja 65337 0xFF39 Hangul_PreHanja 65338 0xFF3A Hangul_PostHanja 65339 0xFF3B SingleCandidate 65340 0xFF3C MultipleCandidate 65341 0xFF3D PreviousCandidate 65342 0xFF3E Hangul_Special 65343 0xFF3F Home 65360 0xFF50 Left 65361 0xFF51 Up 65362 0xFF52 Right 65363 0xFF53 Down 65364 0xFF54 Prior 65365 0xFF55 Next 65366 0xFF56 End 65367 0xFF57 Begin 65368 0xFF58 Select 65376 0xFF60 Print 65377 0xFF61 Execute 65378 0xFF62 Insert 65379 0xFF63 Undo 65381 0xFF65 Redo 65382 0xFF66 Menu (App) 65383 0xFF67 Find 65384 0xFF68 Cancel 65385 0xFF69 Help 65386 0xFF6A Break 65387 0xFF6B Mode_switch 65406 0xFF7E Num_Lock 65407 0xFF7F KP_Space 65408 0xFF80 KP_Tab 65417 0xFF89 KP_Enter 65421 0xFF8D KP_F1 65425 0xFF91 KP_F2 65426 0xFF92 KP_F3 65427 0xFF93 KP_F4 65428 0xFF94 KP_Home 65429 0xFF95 KP_Left 65430 0xFF96 KP_Up 65431 0xFF97 KP_Right 65432 0xFF98 KP_Down 65433 0xFF99 KP_Prior 65434 0xFF9A KP_Next 65435 0xFF9B KP_End 65436 0xFF9C KP_Begin 65437 0xFF9D KP_Insert 65438 0xFF9E KP_Delete 65439 0xFF9F KP_Multiply 65450 0xFFAA KP_Add 65451 0xFFAB KP_Separator 65452 0xFFAC KP_Subtract 65453 0xFFAD KP_Decimal 65454 0xFFAE KP_Divide 65455 0xFFAF KP_0 65456 0xFFB0 KP_1 65457 0xFFB1 KP_2 65458 0xFFB2 KP_3 65459 0xFFB3 KP_4 65460 0xFFB4 KP_5 65461 0xFFB5 KP_6 65462 0xFFB6 KP_7 65463 0xFFB7 KP_8 65464 0xFFB8 KP_9 65465 0xFFB9 KP_Equal 65469 0xFFBD F1 65470 0xFFBE F2 65471 0xFFBF F3 65472 0xFFC0 F4 65473 0xFFC1 F5 65474 0xFFC2 F6 65475 0xFFC3 F7 65476 0xFFC4 F8 65477 0xFFC5 F9 65478 0xFFC6 F10 65479 0xFFC7 F11 65480 0xFFC8 F12 65481 0xFFC9 F13 65482 0xFFCA F14 65483 0xFFCB F15 65484 0xFFCC F16 65485 0xFFCD F17 65486 0xFFCE F18 65487 0xFFCF F19 65488 0xFFD0 F20 65489 0xFFD1 F21 65490 0xFFD2 F22 65491 0xFFD3 F23 65492 0xFFD4 F24 65493 0xFFD5 F25 65494 0xFFD6 F26 65495 0xFFD7 F27 65496 0xFFD8 F28 65497 0xFFD9 F29 65498 0xFFDA F30 65499 0xFFDB F31 65500 0xFFDC F32 65501 0xFFDD F33 65502 0xFFDE F34 65503 0xFFDF F35 65504 0xFFE0 Shift_L 65505 0xFFE1 Shift_R 65506 0xFFE2 Control_L 65507 0xFFE3 Control_R 65508 0xFFE4 Caps_Lock 65509 0xFFE5 Shift_Lock 65510 0xFFE6 Meta_L 65511 0xFFE7 Meta_R 65512 0xFFE8 Alt_L 65513 0xFFE9 Alt_R 65514 0xFFEA Super_L (Win_L) 65515 0xFFEB Super_R (Win_R) 65516 0xFFEC Hyper_L 65517 0xFFED Hyper_R 65518 0xFFEE braille_dot_1 65521 0xFFF1 braille_dot_2 65522 0xFFF2 braille_dot_3 65523 0xFFF3 braille_dot_4 65524 0xFFF4 braille_dot_5 65525 0xFFF5 braille_dot_6 65526 0xFFF6 braille_dot_7 65527 0xFFF7 braille_dot_8 65528 0xFFF8 braille_dot_9 65529 0xFFF9 braille_dot_10 65530 0xFFFA Delete 65535 0xFFFF .CE .CS SunFA_Grave 268828416 0x1005FF00 SunFA_Circum 268828417 0x1005FF01 SunFA_Tilde 268828418 0x1005FF02 SunFA_Acute 268828419 0x1005FF03 SunFA_Diaeresis 268828420 0x1005FF04 SunFA_Cedilla 268828421 0x1005FF05 SunF36 268828432 0x1005FF10 SunF37 268828433 0x1005FF11 SunSys_Req 268828512 0x1005FF60 SunProps 268828528 0x1005FF70 SunFront 268828529 0x1005FF71 SunCopy 268828530 0x1005FF72 SunOpen 268828531 0x1005FF73 SunPaste 268828532 0x1005FF74 SunCut 268828533 0x1005FF75 SunPowerSwitch 268828534 0x1005FF76 SunAudioLowerVolume 268828535 0x1005FF77 SunAudioMute 268828536 0x1005FF78 SunAudioRaiseVolume 268828537 0x1005FF79 SunVideoDegauss 268828538 0x1005FF7A SunVideoLowerBrightness 268828539 0x1005FF7B SunVideoRaiseBrightness 268828540 0x1005FF7C SunPowerSwitchShift 268828541 0x1005FF7D XF86BrightnessAuto 268964084 0x100810F4 XF86DisplayOff 268964085 0x100810F5 XF86Info 268964198 0x10081166 XF86AspectRatio 268964215 0x10081177 XF86DVD 268964229 0x10081185 XF86Audio 268964232 0x10081188 XF86ChannelUp 268964242 0x10081192 XF86ChannelDown 268964243 0x10081193 XF86Break 268964251 0x1008119B XF86VideoPhone 268964256 0x100811A0 XF86ZoomReset 268964260 0x100811A4 XF86Editor 268964262 0x100811A6 XF86GraphicsEditor 268964264 0x100811A8 XF86Presentation 268964265 0x100811A9 XF86Database 268964266 0x100811AA XF86Voicemail 268964268 0x100811AC XF86Addressbook 268964269 0x100811AD XF86DisplayToggle 268964271 0x100811AF XF86SpellCheck 268964272 0x100811B0 XF86ContextMenu 268964278 0x100811B6 XF86MediaRepeat 268964279 0x100811B7 XF8610ChannelsUp 268964280 0x100811B8 XF8610ChannelsDown 268964281 0x100811B9 XF86Images 268964282 0x100811BA XF86NotificationCenter 268964284 0x100811BC XF86PickupPhone 268964285 0x100811BD XF86HangupPhone 268964286 0x100811BE XF86Fn 268964304 0x100811D0 XF86Fn_Esc 268964305 0x100811D1 XF86FnRightShift 268964325 0x100811E5 XF86Numeric0 268964352 0x10081200 XF86Numeric1 268964353 0x10081201 XF86Numeric2 268964354 0x10081202 XF86Numeric3 268964355 0x10081203 XF86Numeric4 268964356 0x10081204 XF86Numeric5 268964357 0x10081205 XF86Numeric6 268964358 0x10081206 XF86Numeric7 268964359 0x10081207 XF86Numeric8 268964360 0x10081208 XF86Numeric9 268964361 0x10081209 XF86NumericStar 268964362 0x1008120A XF86NumericPound 268964363 0x1008120B XF86NumericA 268964364 0x1008120C XF86NumericB 268964365 0x1008120D XF86NumericC 268964366 0x1008120E XF86NumericD 268964367 0x1008120F XF86CameraFocus 268964368 0x10081210 XF86WPSButton 268964369 0x10081211 XF86CameraZoomIn 268964373 0x10081215 XF86CameraZoomOut 268964374 0x10081216 XF86CameraUp 268964375 0x10081217 XF86CameraDown 268964376 0x10081218 XF86CameraLeft 268964377 0x10081219 XF86CameraRight 268964378 0x1008121A XF86AttendantOn 268964379 0x1008121B XF86AttendantOff 268964380 0x1008121C XF86AttendantToggle 268964381 0x1008121D XF86LightsToggle 268964382 0x1008121E XF86ALSToggle 268964400 0x10081230 XF86Buttonconfig 268964416 0x10081240 XF86Taskmanager 268964417 0x10081241 XF86Journal 268964418 0x10081242 XF86ControlPanel 268964419 0x10081243 XF86AppSelect 268964420 0x10081244 XF86Screensaver 268964421 0x10081245 XF86VoiceCommand 268964422 0x10081246 XF86Assistant 268964423 0x10081247 XF86EmojiPicker 268964425 0x10081249 XF86Dictate 268964426 0x1008124A XF86BrightnessMin 268964432 0x10081250 XF86BrightnessMax 268964433 0x10081251 XF86KbdInputAssistPrev 268964448 0x10081260 XF86KbdInputAssistNext 268964449 0x10081261 XF86KbdInputAssistPrevgroup 268964450 0x10081262 XF86KbdInputAssistNextgroup 268964451 0x10081263 XF86KbdInputAssistAccept 268964452 0x10081264 XF86KbdInputAssistCancel 268964453 0x10081265 XF86RightUp 268964454 0x10081266 XF86RightDown 268964455 0x10081267 XF86LeftUp 268964456 0x10081268 XF86LeftDown 268964457 0x10081269 XF86RootMenu 268964458 0x1008126A XF86MediaTopMenu 268964459 0x1008126B XF86Numeric11 268964460 0x1008126C XF86Numeric12 268964461 0x1008126D XF86AudioDesc 268964462 0x1008126E XF863DMode 268964463 0x1008126F XF86NextFavorite 268964464 0x10081270 XF86StopRecord 268964465 0x10081271 XF86PauseRecord 268964466 0x10081272 XF86VOD 268964467 0x10081273 XF86Unmute 268964468 0x10081274 XF86FastReverse 268964469 0x10081275 XF86SlowReverse 268964470 0x10081276 XF86Data 268964471 0x10081277 XF86OnScreenKeyboard 268964472 0x10081278 XF86PrivacyScreenToggle 268964473 0x10081279 XF86SelectiveScreenshot 268964474 0x1008127A XF86Macro1 268964496 0x10081290 XF86Macro2 268964497 0x10081291 XF86Macro3 268964498 0x10081292 XF86Macro4 268964499 0x10081293 XF86Macro5 268964500 0x10081294 XF86Macro6 268964501 0x10081295 XF86Macro7 268964502 0x10081296 XF86Macro8 268964503 0x10081297 XF86Macro9 268964504 0x10081298 XF86Macro10 268964505 0x10081299 XF86Macro11 268964506 0x1008129A XF86Macro12 268964507 0x1008129B XF86Macro13 268964508 0x1008129C XF86Macro14 268964509 0x1008129D XF86Macro15 268964510 0x1008129E XF86Macro16 268964511 0x1008129F XF86Macro17 268964512 0x100812A0 XF86Macro18 268964513 0x100812A1 XF86Macro19 268964514 0x100812A2 XF86Macro20 268964515 0x100812A3 XF86Macro21 268964516 0x100812A4 XF86Macro22 268964517 0x100812A5 XF86Macro23 268964518 0x100812A6 XF86Macro24 268964519 0x100812A7 XF86Macro25 268964520 0x100812A8 XF86Macro26 268964521 0x100812A9 XF86Macro27 268964522 0x100812AA XF86Macro28 268964523 0x100812AB XF86Macro29 268964524 0x100812AC XF86Macro30 268964525 0x100812AD XF86MacroRecordStart 268964528 0x100812B0 XF86MacroRecordStop 268964529 0x100812B1 XF86MacroPresetCycle 268964530 0x100812B2 XF86MacroPreset1 268964531 0x100812B3 XF86MacroPreset2 268964532 0x100812B4 XF86MacroPreset3 268964533 0x100812B5 XF86KbdLcdMenu1 268964536 0x100812B8 XF86KbdLcdMenu2 268964537 0x100812B9 XF86KbdLcdMenu3 268964538 0x100812BA XF86KbdLcdMenu4 268964539 0x100812BB XF86KbdLcdMenu5 268964540 0x100812BC XF86Switch_VT_1 269024769 0x1008FE01 XF86Switch_VT_2 269024770 0x1008FE02 XF86Switch_VT_3 269024771 0x1008FE03 XF86Switch_VT_4 269024772 0x1008FE04 XF86Switch_VT_5 269024773 0x1008FE05 XF86Switch_VT_6 269024774 0x1008FE06 XF86Switch_VT_7 269024775 0x1008FE07 XF86Switch_VT_8 269024776 0x1008FE08 XF86Switch_VT_9 269024777 0x1008FE09 XF86Switch_VT_10 269024778 0x1008FE0A XF86Switch_VT_11 269024779 0x1008FE0B XF86Switch_VT_12 269024780 0x1008FE0C .CE .CS XF86Ungrab 269024800 0x1008FE20 XF86ClearGrab 269024801 0x1008FE21 XF86Next_VMode 269024802 0x1008FE22 XF86Prev_VMode 269024803 0x1008FE23 XF86LogWindowTree 269024804 0x1008FE24 XF86LogGrabInfo 269024805 0x1008FE25 XF86ModeLock 269025025 0x1008FF01 XF86MonBrightnessUp 269025026 0x1008FF02 XF86MonBrightnessDown 269025027 0x1008FF03 XF86KbdLightOnOff 269025028 0x1008FF04 XF86KbdBrightnessUp 269025029 0x1008FF05 XF86KbdBrightnessDown 269025030 0x1008FF06 XF86MonBrightnessCycle 269025031 0x1008FF07 XF86Standby 269025040 0x1008FF10 XF86AudioLowerVolume 269025041 0x1008FF11 XF86AudioMute 269025042 0x1008FF12 XF86AudioRaiseVolume 269025043 0x1008FF13 XF86AudioPlay 269025044 0x1008FF14 XF86AudioStop 269025045 0x1008FF15 XF86AudioPrev 269025046 0x1008FF16 XF86AudioNext 269025047 0x1008FF17 XF86HomePage 269025048 0x1008FF18 XF86Mail 269025049 0x1008FF19 XF86Start 269025050 0x1008FF1A XF86Search 269025051 0x1008FF1B XF86AudioRecord 269025052 0x1008FF1C XF86Calculator 269025053 0x1008FF1D XF86Memo 269025054 0x1008FF1E XF86ToDoList 269025055 0x1008FF1F XF86Calendar 269025056 0x1008FF20 XF86PowerDown 269025057 0x1008FF21 XF86ContrastAdjust 269025058 0x1008FF22 XF86RockerUp 269025059 0x1008FF23 XF86RockerDown 269025060 0x1008FF24 XF86RockerEnter 269025061 0x1008FF25 XF86Back 269025062 0x1008FF26 XF86Forward 269025063 0x1008FF27 XF86Stop 269025064 0x1008FF28 XF86Refresh 269025065 0x1008FF29 XF86PowerOff 269025066 0x1008FF2A XF86WakeUp 269025067 0x1008FF2B XF86Eject 269025068 0x1008FF2C XF86ScreenSaver 269025069 0x1008FF2D XF86WWW 269025070 0x1008FF2E XF86Sleep 269025071 0x1008FF2F XF86Favorites 269025072 0x1008FF30 XF86AudioPause 269025073 0x1008FF31 XF86AudioMedia 269025074 0x1008FF32 XF86MyComputer 269025075 0x1008FF33 XF86VendorHome 269025076 0x1008FF34 XF86LightBulb 269025077 0x1008FF35 XF86Shop 269025078 0x1008FF36 XF86History 269025079 0x1008FF37 XF86OpenURL 269025080 0x1008FF38 XF86AddFavorite 269025081 0x1008FF39 XF86HotLinks 269025082 0x1008FF3A XF86BrightnessAdjust 269025083 0x1008FF3B XF86Finance 269025084 0x1008FF3C XF86Community 269025085 0x1008FF3D XF86AudioRewind 269025086 0x1008FF3E XF86BackForward 269025087 0x1008FF3F XF86Launch0 269025088 0x1008FF40 XF86Launch1 269025089 0x1008FF41 XF86Launch2 269025090 0x1008FF42 XF86Launch3 269025091 0x1008FF43 XF86Launch4 269025092 0x1008FF44 XF86Launch5 269025093 0x1008FF45 XF86Launch6 269025094 0x1008FF46 XF86Launch7 269025095 0x1008FF47 XF86Launch8 269025096 0x1008FF48 XF86Launch9 269025097 0x1008FF49 XF86LaunchA 269025098 0x1008FF4A XF86LaunchB 269025099 0x1008FF4B XF86LaunchC 269025100 0x1008FF4C XF86LaunchD 269025101 0x1008FF4D XF86LaunchE 269025102 0x1008FF4E XF86LaunchF 269025103 0x1008FF4F XF86ApplicationLeft 269025104 0x1008FF50 XF86ApplicationRight 269025105 0x1008FF51 XF86Book 269025106 0x1008FF52 XF86CD 269025107 0x1008FF53 XF86Calculater 269025108 0x1008FF54 XF86Clear 269025109 0x1008FF55 XF86Close 269025110 0x1008FF56 XF86Copy 269025111 0x1008FF57 XF86Cut 269025112 0x1008FF58 XF86Display 269025113 0x1008FF59 XF86DOS 269025114 0x1008FF5A XF86Documents 269025115 0x1008FF5B XF86Excel 269025116 0x1008FF5C XF86Explorer 269025117 0x1008FF5D XF86Game 269025118 0x1008FF5E XF86Go 269025119 0x1008FF5F XF86iTouch 269025120 0x1008FF60 XF86LogOff 269025121 0x1008FF61 XF86Market 269025122 0x1008FF62 XF86Meeting 269025123 0x1008FF63 XF86MenuKB 269025125 0x1008FF65 XF86MenuPB 269025126 0x1008FF66 XF86MySites 269025127 0x1008FF67 XF86New 269025128 0x1008FF68 XF86News 269025129 0x1008FF69 XF86OfficeHome 269025130 0x1008FF6A XF86Open 269025131 0x1008FF6B XF86Option 269025132 0x1008FF6C XF86Paste 269025133 0x1008FF6D XF86Phone 269025134 0x1008FF6E XF86Q 269025136 0x1008FF70 XF86Reply 269025138 0x1008FF72 XF86Reload 269025139 0x1008FF73 XF86RotateWindows 269025140 0x1008FF74 XF86RotationPB 269025141 0x1008FF75 XF86RotationKB 269025142 0x1008FF76 XF86Save 269025143 0x1008FF77 XF86ScrollUp 269025144 0x1008FF78 XF86ScrollDown 269025145 0x1008FF79 XF86ScrollClick 269025146 0x1008FF7A XF86Send 269025147 0x1008FF7B XF86Spell 269025148 0x1008FF7C XF86SplitScreen 269025149 0x1008FF7D XF86Support 269025150 0x1008FF7E XF86TaskPane 269025151 0x1008FF7F XF86Terminal 269025152 0x1008FF80 XF86Tools 269025153 0x1008FF81 XF86Travel 269025154 0x1008FF82 XF86UserPB 269025156 0x1008FF84 XF86User1KB 269025157 0x1008FF85 XF86User2KB 269025158 0x1008FF86 XF86Video 269025159 0x1008FF87 XF86WheelButton 269025160 0x1008FF88 XF86Word 269025161 0x1008FF89 XF86Xfer 269025162 0x1008FF8A XF86ZoomIn 269025163 0x1008FF8B XF86ZoomOut 269025164 0x1008FF8C XF86Away 269025165 0x1008FF8D XF86Messenger 269025166 0x1008FF8E XF86WebCam 269025167 0x1008FF8F XF86MailForward 269025168 0x1008FF90 XF86Pictures 269025169 0x1008FF91 XF86Music 269025170 0x1008FF92 XF86Battery 269025171 0x1008FF93 XF86Bluetooth 269025172 0x1008FF94 XF86WLAN 269025173 0x1008FF95 XF86UWB 269025174 0x1008FF96 XF86AudioForward 269025175 0x1008FF97 XF86AudioRepeat 269025176 0x1008FF98 XF86AudioRandomPlay 269025177 0x1008FF99 XF86Subtitle 269025178 0x1008FF9A XF86AudioCycleTrack 269025179 0x1008FF9B XF86CycleAngle 269025180 0x1008FF9C XF86FrameBack 269025181 0x1008FF9D XF86FrameForward 269025182 0x1008FF9E XF86Time 269025183 0x1008FF9F XF86Select 269025184 0x1008FFA0 XF86View 269025185 0x1008FFA1 XF86TopMenu 269025186 0x1008FFA2 XF86Red 269025187 0x1008FFA3 XF86Green 269025188 0x1008FFA4 XF86Yellow 269025189 0x1008FFA5 XF86Blue 269025190 0x1008FFA6 XF86Suspend 269025191 0x1008FFA7 XF86Hibernate 269025192 0x1008FFA8 XF86TouchpadToggle 269025193 0x1008FFA9 XF86TouchpadOn 269025200 0x1008FFB0 XF86TouchpadOff 269025201 0x1008FFB1 XF86AudioMicMute 269025202 0x1008FFB2 XF86Keyboard 269025203 0x1008FFB3 XF86WWAN 269025204 0x1008FFB4 XF86RFKill 269025205 0x1008FFB5 XF86AudioPreset 269025206 0x1008FFB6 XF86RotationLockToggle 269025207 0x1008FFB7 XF86FullScreen 269025208 0x1008FFB8 .CE .SH "SEE ALSO" bind(n), event(n) .SH KEYWORDS bind, binding, event, keysym '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/label.n0000644001000000100000000001223415105057705017054 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH label n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME label \- Create and manipulate 'label' non-interactive text or image widgets .SH SYNOPSIS \fBlabel\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-disabledforeground \-padx \-activeforeground \-font \-pady \-anchor \-foreground \-relief \-background \-highlightbackground \-takefocus \-bitmap \-highlightcolor \-text \-borderwidth \-highlightthickness \-textvariable \-compound \-image \-underline \-cursor \-justify \-wraplength .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-height height Height Specifies a desired height for the label. If an image or bitmap is being displayed in the label then the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); for text it is in lines of text. If this option is not specified, the label's desired height is computed from the size of the image or bitmap or text being displayed in it. .OP \-state state State Specifies one of three states for the label: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the button is displayed using the \fB\-foreground\fR and \fB\-background\fR options. In active state the label is displayed using the \fB\-activeforeground\fR and \fB\-activebackground\fR options. In the disabled state the \fB\-disabledforeground\fR and \fB\-background\fR options determine how the button is displayed. .OP \-width width Width Specifies a desired width for the label. If an image or bitmap is being displayed in the label then the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); for text it is in characters. If this option is not specified, the label's desired width is computed from the size of the image or bitmap or text being displayed in it. .BE .SH DESCRIPTION .PP The \fBlabel\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a label widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the label such as its colors, font, text, and initial relief. The \fBlabel\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A label is a widget that displays a textual string, bitmap or image. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the \fB\-wraplength\fR option) and one of the characters may optionally be underlined using the \fB\-underline\fR option. The label can be manipulated in a few simple ways, such as changing its relief or text, using the commands described below. .SH "WIDGET COMMAND" .PP The \fBlabel\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for label widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBlabel\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBlabel\fR command. .SH BINDINGS .PP When a new label is created, it has no default event bindings: labels are not intended to be interactive. .SH EXAMPLE .PP .CS # Make the widgets \fBlabel\fR .t -text "This widget is at the top" -bg red \fBlabel\fR .b -text "This widget is at the bottom" -bg green \fBlabel\fR .l -text "Left\enHand\enSide" \fBlabel\fR .r -text "Right\enHand\enSide" text .mid \&.mid insert end "This layout is like Java's BorderLayout" # Lay them out pack .t -side top -fill x pack .b -side bottom -fill x pack .l -side left -fill y pack .r -side right -fill y pack .mid -expand 1 -fill both .CE .SH "SEE ALSO" labelframe(n), button(n), ttk::label(n) .SH KEYWORDS label, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/labelframe.n0000644001000000100000000001521615105057705020072 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH labelframe n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME labelframe \- Create and manipulate 'labelframe' labelled container widgets .SH SYNOPSIS \fBlabelframe\fI pathName\fR ?\fIoptions\fR? .SO \-borderwidth \-highlightbackground \-pady \-cursor \-highlightcolor \-relief \-font \-highlightthickness \-takefocus \-foreground \-padx \-text .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-background background Background This option is the same as the standard \fB\-background\fR option except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border. .OP \-class class Class Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. The \fB\-class\fR option may not be changed with the \fBconfigure\fR widget command. .OP \-colormap colormap Colormap Specifies a colormap to use for the window. The value may be either \fBnew\fR, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as \fIpathName\fR), in which case the new window will use the colormap from the specified window. If the \fB\-colormap\fR option is not specified, the new window uses the same colormap as its parent. This option may not be changed with the \fBconfigure\fR widget command. .OP \-height height Height Specifies the desired height for the window in any of the forms acceptable to \fBTk_GetPixels\fR. If this option is negative or zero then the window will not request any size at all. .OP \-labelanchor labelAnchor LabelAnchor Specifies where to place the label. A label is only displayed if the \fB\-text\fR option is not the empty string. Valid values for this option are (listing them clockwise) \fBnw\fR, \fBn\fR, \fBne\fR, \fBen\fR, \fBe\fR, \fBes\fR, \fBse\fR, \fBs\fR,\fBsw\fR, \fBws\fR, \fBw\fR and \fBwn\fR. The default value is \fBnw\fR. .OP \-labelwidget labelWidget LabelWidget Specifies a widget to use as label. This overrides any \fB\-text\fR option. The widget must exist before being used as \fB\-labelwidget\fR and if it is not a descendant of this window, it will be raised above it in the stacking order. .OP \-visual visual Visual Specifies visual information for the new window in any of the forms accepted by \fBTk_GetVisual\fR. If this option is not specified, the new window will use the same visual as its parent. The \fB\-visual\fR option may not be modified with the \fBconfigure\fR widget command. .OP \-width width Width Specifies the desired width for the window in any of the forms acceptable to \fBTk_GetPixels\fR. If this option is negative or zero then the window will not request any size at all. .BE .SH DESCRIPTION .PP The \fBlabelframe\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a labelframe widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the labelframe such as its background color and relief. The \fBlabelframe\fR command returns the path name of the new window. .PP A labelframe is a simple widget. Its primary purpose is to act as a spacer or container for complex window layouts. It has the features of a \fBframe\fR plus the ability to display a label. .SH "WIDGET COMMAND" .PP The \fBlabelframe\fR command creates a new Tcl command whose name is the same as the path name of the labelframe's window. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIPathName\fR is the name of the command, which is the same as the labelframe widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for frame widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBlabelframe\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBlabelframe\fR command. .SH BINDINGS .PP When a new labelframe is created, it has no default event bindings: labelframes are not intended to be interactive. .SH EXAMPLE .PP This shows how to build part of a GUI for a hamburger vendor. The \fBlabelframe\fR widgets are used to organize the available choices by the kinds of things that the choices are being made over. .PP .CS grid [\fBlabelframe\fR .burger -text "Burger"] \e [\fBlabelframe\fR .bun -text "Bun"] -sticky news grid [\fBlabelframe\fR .cheese -text "Cheese Option"] \e [\fBlabelframe\fR .pickle -text "Pickle Option"] -sticky news foreach {type name val} { burger Beef beef burger Lamb lamb burger Vegetarian beans bun Plain white bun Sesame seeds bun Wholemeal brown cheese None none cheese Cheddar cheddar cheese Edam edam cheese Brie brie cheese Gruy\eu00e8re gruyere cheese "Monterey Jack" jack pickle None none pickle Gherkins gherkins pickle Onions onion pickle Chili chili } { set w [radiobutton .$type.$val -text $name -anchor w \e -variable $type -value $val] pack $w -side top -fill x } set burger beef set bun white set cheese none set pickle none .CE .SH "SEE ALSO" frame(n), label(n), ttk::labelframe(n) .SH KEYWORDS labelframe, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/license.terms0000644001000000100000000000433315076161071020314 0ustar ICTAD+Jan.NijtmansICTAD+Jan.NijtmansThis software is copyrighted by the Regents of the University of California, Sun Microsystems, Inc., Scriptics Corporation, ActiveState Corporation, Apple Inc. and other parties. The following terms apply to all files associated with the software unless explicitly disclaimed in individual files. The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No written agreement, license, or royalty fee is required for any of the authorized uses. Modifications to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first page of each file where they apply. IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. GOVERNMENT USE: If you are acquiring this software on behalf of the U.S. government, the Government shall have only "Restricted Rights" in the software and related documentation as defined in the Federal Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you are acquiring the software on behalf of the Department of Defense, the software shall be classified as "Commercial Computer Software" and the Government shall have only "Restricted Rights" as defined in Clause 252.227-7013 (b) (3) of DFARs. Notwithstanding the foregoing, the authors grant the U.S. Government and others acting in its behalf permission to use and distribute the software in accordance with the terms specified in this license. tk9.0.3/doc/listbox.n0000644001000000100000000005747115105057705017475 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH listbox n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME listbox \- Create and manipulate 'listbox' item list widgets .SH SYNOPSIS \fBlistbox\fI pathName \fR?\fIoptions\fR? .SO \-background \-borderwidth \-cursor \-disabledforeground \-exportselection \-font \-foreground \-highlightbackground \-highlightcolor \-highlightthickness \-justify \-relief \-selectbackground \-selectborderwidth \-selectforeground \-setgrid \-takefocus \-xscrollcommand \-yscrollcommand .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-activestyle activeStyle ActiveStyle Specifies the style in which to draw the active element. This must be one of \fBdotbox\fR (show a focus ring around the active element), \fBnone\fR (no special indication of active element) or \fBunderline\fR (underline the active element). The default is \fBunderline\fR on Windows, and \fBdotbox\fR elsewhere. .OP \-height height Height Specifies the desired height for the window, in lines. If zero or less, then the desired height for the window is made just large enough to hold all the elements in the listbox. .OP \-listvariable listVariable Variable Specifies the name of a global variable. The value of the variable is a list to be displayed inside the widget; if the variable value changes then the widget will automatically update itself to reflect the new value. Attempts to assign a variable with an invalid list value to \fB\-listvariable\fR will cause an error. Attempts to unset a variable in use as a \fB\-listvariable\fR will fail but will not generate an error. .OP \-selectmode selectMode SelectMode Specifies one of several styles for manipulating the selection. The value of the option may be arbitrary, but the default bindings expect it to be either \fBsingle\fR, \fBbrowse\fR, \fBmultiple\fR, or \fBextended\fR; the default value is \fBbrowse\fR. .OP \-state state State Specifies one of two states for the listbox: \fBnormal\fR or \fBdisabled\fR. If the listbox is disabled then items may not be inserted or deleted, items are drawn in the \fB\-disabledforeground\fR color, and selection cannot be modified and is not shown (though selection information is retained). .OP \-width width Width Specifies the desired width for the window in characters. If the font does not have a uniform width then the width of the character .QW 0 is used in translating from character units to screen units. If zero or less, then the desired width for the window is made just large enough to hold all the elements in the listbox. .BE .SH DESCRIPTION .PP The \fBlistbox\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a listbox widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the listbox such as its colors, font, text, and relief. The \fBlistbox\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A listbox is a widget that displays a list of strings, one per line. When first created, a new listbox has no elements. Elements may be added or deleted using widget commands described below. In addition, one or more elements may be selected as described below. If a listbox is exporting its selection (see \fB\-exportselection\fR option), then it will observe the standard X11 protocols for handling the selection. Listbox selections are available as type \fBSTRING\fR; the value of the selection will be the text of the selected elements, with newlines separating the elements. .PP It is not necessary for all the elements to be displayed in the listbox window at once; commands described below may be used to change the view in the window. Listboxes allow scrolling in both directions using the standard \fB\-xscrollcommand\fR and \fB\-yscrollcommand\fR options. They also support scanning, as described below. .SH "INDICES" .PP Many of the widget commands for listboxes take one or more indices as arguments. An index specifies a particular element of the listbox, in any of the following ways: .IP \fInumber\fR 12 Specifies the element as a numerical index, where 0 corresponds to the first element in the listbox. .IP \fBactive\fR 12 Indicates the element that has the location cursor. This element will be displayed as specified by \fB\-activestyle\fR when the listbox has the keyboard focus, and it is specified with the \fBactivate\fR widget command. .IP \fBanchor\fR 12 Indicates the anchor point for the selection, which is set with the \fBselection anchor\fR widget command. .IP \fBend\fR 12 Indicates the end of the listbox. For most commands this refers to the last element in the listbox, but for a few commands such as \fBindex\fR and \fBinsert\fR it refers to the element just after the last one. .IP \fB@\fIx\fB,\fIy\fR 12 Indicates the element that covers the point in the listbox window specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no element covers that point, then the closest element to that point is used. .PP Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. In the widget command descriptions below, arguments named \fIindex\fR, \fIfirst\fR, and \fIlast\fR always contain text indices in one of the above forms. .SH "WIDGET COMMAND" .PP The \fBlistbox\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for listbox widgets: .\" METHOD: activate .TP \fIpathName \fBactivate\fI index\fR . Sets the active element to the one indicated by \fIindex\fR. If \fIindex\fR is outside the range of elements in the listbox then the closest element is activated. The active element is drawn as specified by \fB\-activestyle\fR when the widget has the input focus, and its index may be retrieved with the index \fBactive\fR. .\" METHOD: bbox .TP \fIpathName \fBbbox\fI index\fR . Returns a list of four numbers describing the bounding box of the text in the element given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the text (specified in pixels relative to the widget) and the last two elements give the width and height of the area, in pixels. If no part of the element given by \fIindex\fR is visible on the screen, or if \fIindex\fR refers to a non-existent element, then the result is an empty string; if the element is partially visible, the result gives the full area of the element, including any parts that are not visible. .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBlistbox\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBlistbox\fR command. .\" METHOD: curselection .TP \fIpathName \fBcurselection\fR . Returns a list containing the numerical indices of all of the elements in the listbox that are currently selected. If there are no elements selected in the listbox then an empty string is returned. .\" METHOD: delete .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? . Deletes one or more elements of the listbox. \fIFirst\fR and \fIlast\fR are indices specifying the first and last elements in the range to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR, i.e. a single element is deleted. .\" METHOD: get .TP \fIpathName \fBget \fIfirst\fR ?\fIlast\fR? . If \fIlast\fR is omitted, returns the contents of the listbox element indicated by \fIfirst\fR, or an empty string if \fIfirst\fR refers to a non-existent element. If \fIlast\fR is specified, the command returns a list whose elements are all of the listbox elements between \fIfirst\fR and \fIlast\fR, inclusive. Both \fIfirst\fR and \fIlast\fR may have any of the standard forms for indices. .\" METHOD: index .TP \fIpathName \fBindex \fIindex\fR . Returns the integer index value that corresponds to \fIindex\fR. If \fIindex\fR is \fBend\fR the return value is a count of the number of elements in the listbox (not the index of the last element). .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex \fR?\fIelement element ...\fR? . Inserts zero or more new elements in the list just before the element given by \fIindex\fR. If \fIindex\fR is specified as \fBend\fR then the new elements are added to the end of the list. Returns an empty string. .\" METHOD: itemcget .TP \fIpathName \fBitemcget \fIindex option\fR . Returns the current value of the item configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBitemconfigure\fR command. .\" METHOD: itemconfigure .TP \fIpathName \fBitemconfigure \fIindex\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? . Query or modify the configuration options of an item in the listbox. If no \fIoption\fR is specified, returns a list describing all of the available options for the item (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. The following options are currently supported for items: .RS .\" OPTION: -background .TP \fB\-background \fIcolor\fR . \fIColor\fR specifies the background color to use when displaying the item. It may have any of the forms accepted by \fBTk_GetColor\fR. .\" OPTION: -foreground .TP \fB\-foreground \fIcolor\fR . \fIColor\fR specifies the foreground color to use when displaying the item. It may have any of the forms accepted by \fBTk_GetColor\fR. .\" OPTION: -selectbackground .TP \fB\-selectbackground \fIcolor\fR . \fIcolor\fR specifies the background color to use when displaying the item while it is selected. It may have any of the forms accepted by \fBTk_GetColor\fR. .\" OPTION: -selectforeground .TP \fB\-selectforeground \fIcolor\fR . \fIcolor\fR specifies the foreground color to use when displaying the item while it is selected. It may have any of the forms accepted by \fBTk_GetColor\fR. .RE .\" METHOD: nearest .TP \fIpathName \fBnearest \fIy\fR . Given a y-coordinate within the listbox window, this command returns the index of the (visible) listbox element nearest to that y-coordinate. .\" METHOD: scan .TP \fIpathName \fBscan\fI option args\fR . This command is used to implement scanning on listboxes. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx y\fR . Records \fIx\fR and \fIy\fR and the current view in the listbox window; used in conjunction with later \fBscan dragto\fR commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. .TP \fIpathName \fBscan dragto \fIx y\fR. . This command computes the difference between its \fIx\fR and \fIy\fR arguments and the \fIx\fR and \fIy\fR arguments to the last \fBscan mark\fR command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the list at high speed through the window. The return value is an empty string. .RE .\" METHOD: see .TP \fIpathName \fBsee \fIindex\fR . Adjust the view in the listbox so that the element given by \fIindex\fR is visible. If the element is already visible then the command has no effect; if the element is near one edge of the window then the listbox scrolls to bring the element into view at the edge; otherwise the listbox scrolls to center the element. .\" METHOD: selection .TP \fIpathName \fBselection \fIoption arg\fR . This command is used to adjust the selection within a listbox. It has several forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBselection anchor \fIindex\fR . Sets the selection anchor to the element given by \fIindex\fR. If \fIindex\fR refers to a non-existent element, then the closest element is used. The selection anchor is the end of the selection that is fixed while dragging out a selection with the mouse. The index \fBanchor\fR may be used to refer to the anchor element. .TP \fIpathName \fBselection clear \fIfirst \fR?\fIlast\fR? . If any of the elements between \fIfirst\fR and \fIlast\fR (inclusive) are selected, they are deselected. The selection state is not changed for elements outside this range. .TP \fIpathName \fBselection includes \fIindex\fR . Returns 1 if the element indicated by \fIindex\fR is currently selected, 0 if it is not. .TP \fIpathName \fBselection set \fIfirst \fR?\fIlast\fR? . Selects all of the elements in the range between \fIfirst\fR and \fIlast\fR, inclusive, without affecting the selection state of elements outside that range. .RE .\" METHOD: size .TP \fIpathName \fBsize\fR . Returns a decimal string indicating the total number of elements in the listbox. .\" METHOD: xview .TP \fIpathName \fBxview \fR?\fIargs\fR . This command is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR . Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the listbox's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP \fIpathName \fBxview \fIindex\fR . Adjusts the view in the window so that the character position given by \fIindex\fR is displayed at the left edge of the window. Character positions are defined by the width of the character \fB0\fR. .TP \fIpathName \fBxview moveto\fI fraction\fR . Adjusts the view in the window so that \fIfraction\fR of the total width of the listbox text is off-screen to the left. \fIfraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR . This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then it is converted to an integer, rounded away from 0. \fIWhat\fR must be either \fBpages\fR or \fBunits\fR or an abbreviation of one of these. If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by \fInumber\fR character units (the width of the \fB0\fR character) on the display. .RE .\" METHOD: yview .TP \fIpathName \fByview \fR?\fIargs\fR? . This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fByview\fR . Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the listbox element at the top of the window, relative to the listbox as a whole (0.5 means it is halfway through the listbox, for example). The second element gives the position of the listbox element just after the last one in the window, relative to the listbox as a whole. These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR option. .TP \fIpathName \fByview \fIindex\fR . Adjusts the view in the window so that the element given by \fIindex\fR is displayed at the top of the window. .TP \fIpathName \fByview moveto\fI fraction\fR . Adjusts the view in the window so that the element given by \fIfraction\fR appears at the top of the window. \fIFraction\fR is a fraction between 0 and 1; 0 indicates the first element in the listbox, 0.33 indicates the element one-third the way through the listbox, and so on. .TP \fIpathName \fByview scroll \fInumber what\fR . This command adjusts the view in the window up or down according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then it is converted to an integer, rounded away from 0. \fIWhat\fR must be either \fBpages\fR or \fBunits\fR. If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. If \fInumber\fR is negative then earlier elements become visible; if it is positive then later elements become visible. If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by \fInumber\fR lines. .RE .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for listboxes that give them Motif-like behavior. Much of the behavior of a listbox is determined by its \fB\-selectmode\fR option, which selects one of four ways of dealing with the selection. .PP If the selection mode is \fBsingle\fR or \fBbrowse\fR, at most one element can be selected in the listbox at once. In both modes, clicking button 1 on an element selects it and deselects any other selected item. In \fBbrowse\fR mode it is also possible to drag the selection with button 1. On button 1, the listbox will also take focus if it has a \fBnormal\fR state. .PP If the selection mode is \fBmultiple\fR or \fBextended\fR, any number of elements may be selected at once, including discontiguous ranges. In \fBmultiple\fR mode, clicking button 1 on an element toggles its selection state without affecting any other elements. In \fBextended\fR mode, pressing button 1 on an element selects it, deselects everything else, and sets the anchor to the element under the mouse; dragging the mouse with button 1 down extends the selection to include all the elements between the anchor and the element under the mouse, inclusive. .PP Most people will probably want to use \fBbrowse\fR mode for single selections and \fBextended\fR mode for multiple selections; the other modes appear to be useful only in special situations. .PP Any time the set of selected item(s) in the listbox is updated by the user through the keyboard or mouse, the virtual event \fB<>\fR will be generated. This virtual event will not be generated when adjusting the selection with the \fIpathName \fBselection\fR command. It is easiest to bind to this event to be made aware of any user changes to listbox selection. .PP In addition to the above behavior, the following additional behavior is defined by the default bindings: .IP [1] In \fBextended\fR mode, the selected range can be adjusted by pressing button 1 with the Shift key down: this modifies the selection to consist of the elements between the anchor and the element under the mouse, inclusive. The un-anchored end of this new selection can also be dragged with the button down. .IP [2] In \fBextended\fR mode, pressing button 1 with the Control key down starts a toggle operation: the anchor is set to the element under the mouse, and its selection state is reversed. The selection state of other elements is not changed. If the mouse is dragged with button 1 down, then the selection state of all elements between the anchor and the element under the mouse is set to match that of the anchor element; the selection state of all other elements remains what it was before the toggle operation began. .IP [3] If the mouse leaves the listbox window with button 1 down, the window scrolls away from the mouse, making information visible that used to be off-screen on the side of the mouse. The scrolling continues until the mouse re-enters the window, the button is released, or the end of the listbox is reached. .IP [4] Mouse button 2 may be used for scanning. If it is pressed and dragged over the listbox, the contents of the listbox drag at high speed in the direction the mouse moves. .IP [5] If the Up or Down key is pressed, the location cursor (active element) moves up or down one element. If the selection mode is \fBbrowse\fR or \fBextended\fR then the new active element is also selected and all other elements are deselected. In \fBextended\fR mode the new active element becomes the selection anchor. .IP [6] In \fBextended\fR mode, Shift-Up and Shift-Down move the location cursor (active element) up or down one element and also extend the selection to that element in a fashion similar to dragging with mouse button 1. .IP [7] The Left and Right keys scroll the listbox view left and right by the width of the character \fB0\fR. Control-Left and Control-Right scroll the listbox view left and right by the width of the window. Control-Prior and Control-Next also scroll left and right by the width of the window. .IP [8] The Prior and Next keys scroll the listbox view up and down by one page (the height of the window). .IP [9] The Home and End keys scroll the listbox horizontally to the left and right edges, respectively. .IP [10] Control-Home sets the location cursor to the first element in the listbox, selects that element, and deselects everything else in the listbox. .IP [11] Control-End sets the location cursor to the last element in the listbox, selects that element, and deselects everything else in the listbox. .IP [12] In \fBextended\fR mode, Control-Shift-Home extends the selection to the first element in the listbox and Control-Shift-End extends the selection to the last element. .IP [13] In \fBmultiple\fR mode, Control-Shift-Home moves the location cursor to the first element in the listbox and Control-Shift-End moves the location cursor to the last element. .IP [14] The space and Select keys make a selection at the location cursor (active element) just as if mouse button 1 had been pressed over this element. .IP [15] In \fBextended\fR mode, Control-Shift-space and Shift-Select extend the selection to the active element just as if button 1 had been pressed with the Shift key down. .IP [16] In \fBextended\fR mode, the Escape key cancels the most recent selection and restores all the elements in the selected range to their previous selection state. .IP [17] Control-/ selects everything in the widget, except in \fBsingle\fR and \fBbrowse\fR modes, in which case it selects the active element and deselects everything else. .IP [18] Control-backslash deselects everything in the widget, except in \fBbrowse\fR mode where it has no effect. .IP [19] The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection. .PP The behavior of listboxes can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "SEE ALSO" ttk::treeview(n) .SH KEYWORDS listbox, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/loadTk.n0000644001000000100000000000606315105057705017216 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH "Safe Tk" n 8.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME safe::loadTk \- Load Tk into a safe interpreter. .SH SYNOPSIS \fBsafe::loadTk \fIchild\fR ?\fB\-use\fI windowId\fR? ?\fB\-display\fI displayName\fR? .BE .SH DESCRIPTION .PP Safe Tk is based on Safe Tcl, which provides a mechanism that allows restricted and mediated access to auto-loading and packages for safe interpreters. Safe Tk adds the ability to configure the interpreter for safe Tk operations and load Tk into safe interpreters. .PP The \fBsafe::loadTk\fR command initializes the required data structures in the named safe interpreter and then loads Tk into it. The interpreter must have been created with \fBsafe::interpCreate\fR or have been initialized with \fBsafe::interpInit\fR. The command returns the name of the safe interpreter. If \fB\-use\fR is specified, the window identified by the specified system dependent identifier \fIwindowId\fR is used to contain the .QW . window of the safe interpreter; it can be any valid id, eventually referencing a window belonging to another application. As a convenience, if the window you plan to use is a Tk Window of the application you can use the window name (e.g., .QW \fB.x.y\fR ) instead of its window Id (e.g., from \fBwinfo id\fI .x.y\fR). When \fB\-use\fR is not specified, a new toplevel window is created for the .QW . window of the safe interpreter. On X11 if you want the embedded window to use another display than the default one, specify it with \fB\-display\fR. See the \fBSECURITY ISSUES\fR section below for implementation details. .SH "SECURITY ISSUES" .PP Please read the \fBsafe\fR manual page for Tcl to learn about the basic security considerations for Safe Tcl. .PP \fBsafe::loadTk\fR adds the value of \fBtk_library\fR taken from the parent interpreter to the virtual access path of the safe interpreter so that auto-loading will work in the safe interpreter. .PP Tk initialization is now safe with respect to not trusting the child's state for startup. \fBsafe::loadTk\fR registers the child's name so when the Tk initialization (\fBTk_SafeInit\fR) is called and in turn calls the parent's \fBsafe::InitTk\fR it will return the desired \fBargv\fR equivalent (\fB\-use\fI windowId\fR, correct \fB\-display\fR, etc.) .PP When \fB\-use\fR is not used, the new toplevel created is specially decorated so the user is always aware that the user interface presented comes from a potentially unsafe code and can easily delete the corresponding interpreter. .PP On X11, conflicting \fB\-use\fR and \fB\-display\fR are likely to generate a fatal X error. .SH "SEE ALSO" safe(n), interp(n), library(n), load(n), package(n), source(n), unknown(n) .SH KEYWORDS alias, auto-loading, auto_mkindex, load, parent interpreter, safe interpreter, child interpreter, source '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/lower.n0000644001000000100000000000270115076161057017126 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH lower n 3.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME lower \- Change a window's position in the stacking order .SH SYNOPSIS \fBlower \fIwindow \fR?\fIbelowThis\fR? .BE .SH DESCRIPTION .PP If the \fIbelowThis\fR argument is omitted then the command lowers \fIwindow\fR so that it is below all of its siblings in the stacking order (it will be obscured by any siblings that overlap it and will not obscure any siblings). If \fIbelowThis\fR is specified then it must be the path name of a window that is either a sibling of \fIwindow\fR or the descendant of a sibling of \fIwindow\fR. In this case the \fBlower\fR command will insert \fIwindow\fR into the stacking order just below \fIbelowThis\fR (or the ancestor of \fIbelowThis\fR that is a sibling of \fIwindow\fR); this could end up either raising or lowering \fIwindow\fR. .PP All \fBtoplevel\fR windows may be restacked with respect to each other, whatever their relative path names, but the window manager is not obligated to strictly honor requests to restack. .SH "SEE ALSO" raise .SH KEYWORDS lower, obscure, stacking order '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/MainLoop.30000644001000000100000000000163015105057705017416 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_MainLoop 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_MainLoop \- loop for events until all windows are deleted .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_MainLoop\fR() .fi .BE .SH DESCRIPTION .PP \fBTk_MainLoop\fR is a procedure that loops repeatedly calling \fBTcl_DoOneEvent\fR. It returns only when there are no applications left in this process (i.e. no main windows exist anymore). Most windowing applications will call \fBTk_MainLoop\fR after initialization; the main execution of the application will consist entirely of callbacks invoked via \fBTcl_DoOneEvent\fR. .SH KEYWORDS application, event, main loop tk9.0.3/doc/MaintGeom.30000644001000000100000000001016215105057705017560 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_MaintainGeometry 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_MaintainGeometry, Tk_UnmaintainGeometry \- maintain geometry of one window relative to another .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_MaintainGeometry\fR(\fIwindow, container, x, y, width, height\fR) .sp \fBTk_UnmaintainGeometry\fR(\fIwindow, container\fR) .fi .SH ARGUMENTS .AS Tk_Window container .AP Tk_Window window in Window whose geometry is to be controlled. .AP Tk_Window container in Window relative to which \fIwindow\fR's geometry will be controlled. .AP int x in Desired x-coordinate of \fIwindow\fR in \fIcontainer\fR, measured in pixels from the inside of \fIcontainer\fR's left border to the outside of \fIwindow\fR's left border. .AP int y in Desired y-coordinate of \fIwindow\fR in \fIcontainer\fR, measured in pixels from the inside of \fIcontainer\fR's top border to the outside of \fIwindow\fR's top border. .AP int width in Desired width for \fIwindow\fR, in pixels. .AP int height in Desired height for \fIwindow\fR, in pixels. .BE .SH DESCRIPTION .PP \fBTk_MaintainGeometry\fR and \fBTk_UnmaintainGeometry\fR make it easier for geometry managers to deal with windows whose containers are not their parents. Three problems arise if the container for a window is not its parent: .IP [1] The x- and y-position of the window must be translated from the coordinate system of the container to that of the parent before positioning the window. .IP [2] If the container window, or any of its ancestors up to the window's parent, is moved, then the window must be repositioned within its parent in order to maintain the correct position relative to the container. .IP [3] If the container or one of its ancestors is mapped or unmapped, then the window must be mapped or unmapped to correspond. .LP None of these problems is an issue if the parent and container are the same. For example, if the container or one of its ancestors is unmapped, the window is automatically removed by the screen by X. .PP \fBTk_MaintainGeometry\fR deals with these problems for windows whose containers are not their parents, as well as handling the simpler case of windows whose container are their parents. \fBTk_MaintainGeometry\fR is typically called by a window manager once it has decided where a window should be positioned relative to its container. \fBTk_MaintainGeometry\fR translates the coordinates to the coordinate system of \fIwindow\fR's parent and then moves and resizes the window appropriately. Furthermore, it remembers the desired position and creates event handlers to monitor the container and all of its ancestors up to (but not including) the window's parent. If any of these windows is moved, mapped, or unmapped, the window will be adjusted so that it is mapped only when the container is mapped and its geometry relative to the container remains as specified by \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR. .PP When a window manager relinquishes control over a window, or if it decides that it does not want the window to appear on the screen under any conditions, it calls \fBTk_UnmaintainGeometry\fR. \fBTk_UnmaintainGeometry\fR unmaps the window and cancels any previous calls to \fBTk_MaintainGeometry\fR for the \fIcontainer\fR\-\fIwindow\fR pair, so that the window's geometry and mapped state are no longer maintained automatically. \fBTk_UnmaintainGeometry\fR need not be called by a geometry manager if the window, the container, or any of the container's ancestors is destroyed: Tk will call it automatically. .PP If \fBTk_MaintainGeometry\fR is called repeatedly for the same \fIcontainer\fR\-\fIwindow\fR pair, the information from the most recent call supersedes any older information. If \fBTk_UnmaintainGeometry\fR is called for a \fIcontainer\fR\-\fIwindow\fR pair that is is not currently managed, the call has no effect. .SH KEYWORDS geometry manager, map, container, parent, position, window, unmap tk9.0.3/doc/MainWin.30000644001000000100000000000376115105057705017251 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_MainWindow 3 7.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_MainWindow, Tk_GetNumMainWindows \- functions for querying main window information .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Window \fBTk_MainWindow\fR(\fIinterp\fR) .sp \fBTk_SetMainMenubar\fR(\fIinterp, tkwin, menuName\fR) .sp \fBTk_SetWindowMenubar\fR(\fIinterp, tkwin, oldMenuName, menuName\fR) .sp int \fBTk_GetNumMainWindows\fR() .fi .SH ARGUMENTS .AS Tcl_Interp *pathName .AP Tcl_Interp *interp in/out Interpreter associated with the application. .AP Tk_Window tkwin in Token for main window. .AP const char *menuName in The name of the new menubar that the toplevel needs to be set to. NULL means that their is no menu now. .AP const char *oldMenuName in The name of the menubar previously set in this toplevel. NULL means no menu was set previously. .BE .SH DESCRIPTION .PP A main window is a special kind of toplevel window used as the outermost window in an application. .PP If \fIinterp\fR is associated with a Tk application then \fBTk_MainWindow\fR returns the application's main window. If there is no Tk application associated with \fIinterp\fR then \fBTk_MainWindow\fR returns NULL and leaves an error message in interpreter \fIinterp\fR's result. .PP \fBTk_GetNumMainWindows\fR returns a count of the number of main windows currently open in the current thread. \fBTk_SetMainMenubar\fR Called when a toplevel widget is brought to front. On the Macintosh, sets up the menubar that goes across the top of the main monitor. On other platforms, nothing is necessary. \fBTk_SetWindowMenubar\fR associates a menu with a window. The old menu clones for the menubar are thrown away, and a handler is set up to allocate the new ones. .SH KEYWORDS application, main window tk9.0.3/doc/man.macros0000644001000000100000000001326215105057705017601 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans.\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. .\" type is type of argument (int, etc.), in/out is either "in", "out", .\" or "in/out" to describe whether procedure reads or modifies arg, .\" and indent is equivalent to second arg of .IP (shouldn't ever be .\" needed; use .AS below instead) .\" .\" .AS ?type? ?name? .\" Give maximum sizes of arguments for setting tab stops. Type and .\" name are examples of largest possible arguments that will be passed .\" to .AP later. If args are omitted, default tab stops are used. .\" .\" .BS .\" Start box enclosure. From here until next .BE, everything will be .\" enclosed in one large box. .\" .\" .BE .\" End of box enclosure. .\" .\" .CS .\" Begin code excerpt. .\" .\" .CE .\" End code excerpt. .\" .\" .VS ?version? ?br? .\" Begin vertical sidebar, for use in marking newly-changed parts .\" of man pages. The first argument is ignored and used for recording .\" the version when the .VS was added, so that the sidebars can be .\" found and removed when they reach a certain age. If another argument .\" is present, then a line break is forced before starting the sidebar. .\" .\" .VE .\" End of vertical sidebar. .\" .\" .DS .\" Begin an indented unfilled display. .\" .\" .DE .\" End of indented unfilled display. .\" .\" .SO ?manpage? .\" Start of list of standard options for a Tk widget. The manpage .\" argument defines where to look up the standard options; if .\" omitted, defaults to "options". The options follow on successive .\" lines, in three columns separated by tabs. .\" .\" .SE .\" End of list of standard options for a Tk widget. .\" .\" .OP cmdName dbName dbClass .\" Start of description of a specific option. cmdName gives the .\" option's name as specified in the class command, dbName gives .\" the option's name in the option database, and dbClass gives .\" the option's class in the option database. .\" .\" .UL arg1 arg2 .\" Print arg1 underlined, then print arg2 normally. .\" .\" .QW arg1 ?arg2? .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). .\" .\" .PQ arg1 ?arg2? .\" Print an open parenthesis, arg1 in quotes, then arg2 normally .\" (for trailing punctuation) and then a closing parenthesis. .\" .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. .if t .wh -1.3i ^B .nr ^l \n(.l .ad b .\" # Start an argument description .de AP .ie !"\\$4"" .TP \\$4 .el \{\ . ie !"\\$2"" .TP \\n()Cu . el .TP 15 .\} .ta \\n()Au \\n()Bu .ie !"\\$3"" \{\ \&\\$1 \\fI\\$2\\fP (\\$3) .\".b .\} .el \{\ .br .ie !"\\$2"" \{\ \&\\$1 \\fI\\$2\\fP .\} .el \{\ \&\\fI\\$1\\fP .\} .\} .. .\" # define tabbing values for .AP .de AS .nr )A 10n .if !"\\$1"" .nr )A \\w'\\$1'u+3n .nr )B \\n()Au+15n .\" .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n .nr )C \\n()Bu+\\w'(in/out)'u+2n .. .AS Tcl_Interp Tcl_CreateInterp in/out .\" # BS - start boxed text .\" # ^y = starting y location .\" # ^b = 1 .de BS .br .mk ^y .nr ^b 1u .if n .nf .if n .ti 0 .if n \l'\\n(.lu\(ul' .if n .fi .. .\" # BE - end boxed text (draw box now) .de BE .nf .ti 0 .mk ^t .ie n \l'\\n(^lu\(ul' .el \{\ .\" Draw four-sided box normally, but don't draw top of .\" box if the box started on an earlier page. .ie !\\n(^b-1 \{\ \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .el \}\ \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .\} .fi .br .nr ^b 0 .. .\" # VS - start vertical sidebar .\" # ^Y = starting y location .\" # ^v = 1 (for troff; for nroff this doesn't matter) .de VS .if !"\\$2"" .br .mk ^Y .ie n 'mc \s12\(br\s0 .el .nr ^v 1u .. .\" # VE - end of vertical sidebar .de VE .ie n 'mc .el \{\ .ev 2 .nf .ti 0 .mk ^t \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' .sp -1 .fi .ev .\} .nr ^v 0 .. .\" # Special macro to handle page bottom: finish off current .\" # box/sidebar if in box/sidebar mode, then invoked standard .\" # page bottom macro. .de ^B .ev 2 'ti 0 'nf .mk ^t .if \\n(^b \{\ .\" Draw three-sided box if this is the box's first page, .\" draw two sides but no top otherwise. .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 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .\} .if \\n(^v \{\ .nr ^x \\n(^tu+1v-\\n(^Yu \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c .\} .bp 'fi .ev .if \\n(^b \{\ .mk ^y .nr ^b 2 .\} .if \\n(^v \{\ .mk ^Y .\} .. .\" # DS - begin display .de DS .RS .nf .sp .. .\" # DE - end display .de DE .fi .RE .sp .. .\" # SO - start of list of standard options .de SO 'ie '\\$1'' .ds So \\fBoptions\\fR 'el .ds So \\fB\\$1\\fR .SH "STANDARD OPTIONS" .LP .nf .ta 5.5c 11c .ft B .. .\" # SE - end of list of standard options .de SE .fi .ft R .LP See the \\*(So manual entry for details on the standard options. .. .\" # OP - start of full description for a single option .de OP .LP .nf .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi .IP .. .\" # CS - begin code excerpt .de CS .RS .nf .ta .25i .5i .75i 1i .. .\" # CE - end code excerpt .de CE .fi .RE .. .\" # UL - underline word .de UL \\$1\l'|0\(ul'\\$2 .. .\" # QW - apply quotation marks to word .de QW .ie '\\*(lq'"' ``\\$1''\\$2 .\"" fix emacs highlighting .el \\*(lq\\$1\\*(rq\\$2 .. .\" # PQ - apply parens and quotation marks to word .de PQ .ie '\\*(lq'"' (``\\$1''\\$2)\\$3 .\"" fix emacs highlighting .el (\\*(lq\\$1\\*(rq\\$2)\\$3 .. .\" # QR - quoted range .de QR .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 .\"" fix emacs highlighting .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 .. .\" # MT - "empty" string .de MT .QW "" .. tk9.0.3/doc/ManageGeom.30000644001000000100000000000663615105057705017713 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_ManageGeometry 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_ManageGeometry \- arrange to handle geometry requests for a window .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR) .fi .SH ARGUMENTS .AS Tk_GeometryProc clientData .AP Tk_Window tkwin in Token for window to be managed. .AP "const Tk_GeomMgr" *mgrPtr in Pointer to data structure containing information about the geometry manager, or NULL to indicate that \fItkwin\fR's geometry should not be managed anymore. The data structure pointed to by \fImgrPtr\fR must be static: Tk keeps a reference to it as long as the window is managed. .AP void *clientData in Arbitrary one-word value to pass to geometry manager callbacks. .BE .SH DESCRIPTION .PP \fBTk_ManageGeometry\fR arranges for a particular geometry manager, described by the \fImgrPtr\fR argument, to control the geometry of a particular content window, given by \fItkwin\fR. If \fItkwin\fR was previously managed by some other geometry manager, the previous manager loses control in favor of the new one. If \fImgrPtr\fR is NULL, geometry management is cancelled for \fItkwin\fR. .PP The structure pointed to by \fImgrPtr\fR contains information about the geometry manager: .CS typedef struct { const char *\fIname\fR; Tk_GeomRequestProc *\fIrequestProc\fR; Tk_GeomLostContentProc *\fIlostContentProc\fR; } \fBTk_GeomMgr\fR; .CE The \fIname\fR field is the textual name for the geometry manager, such as \fBpack\fR or \fBplace\fR; this value will be returned by the command \fBwinfo manager\fR. .PP \fIrequestProc\fR is a procedure in the geometry manager that will be invoked whenever \fBTk_GeometryRequest\fR is called by the content window to change its desired geometry. \fIrequestProc\fR should have arguments and results that match the type \fBTk_GeomRequestProc\fR: .CS typedef void \fBTk_GeomRequestProc\fR( void *\fIclientData\fR, Tk_Window \fItkwin\fR); .CE The parameters to \fIrequestProc\fR will be identical to the corresponding parameters passed to \fBTk_ManageGeometry\fR. \fIclientData\fR usually points to a data structure containing application-specific information about how to manage \fItkwin\fR's geometry. .PP The \fIlostContentProc\fR field of \fImgrPtr\fR points to another procedure in the geometry manager. Tk will invoke \fIlostContentProc\fR if some other manager calls \fBTk_ManageGeometry\fR to claim \fItkwin\fR away from the current geometry manager. \fIlostContentProc\fR is not invoked if \fBTk_ManageGeometry\fR is called with a NULL value for \fImgrPtr\fR (presumably the current geometry manager has made this call, so it already knows that the window is no longer managed), nor is it called if \fImgrPtr\fR is the same as the window's current geometry manager. \fIlostContentProc\fR should have arguments and results that match the following prototype: .CS typedef void \fBTk_GeomLostContentProc\fR( void *\fIclientData\fR, Tk_Window \fItkwin\fR); .CE The parameters to \fIlostContentProc\fR will be identical to the corresponding parameters passed to \fBTk_ManageGeometry\fR. .SH KEYWORDS callback, geometry, managed, request, unmanaged tk9.0.3/doc/MapWindow.30000644001000000100000000000311615105057705017606 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_MapWindow 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_MapWindow, Tk_UnmapWindow \- map or unmap a window .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Window \fBTk_MapWindow\fR(\fItkwin\fR) .sp \fBTk_UnmapWindow\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window. .BE .SH DESCRIPTION .PP These procedures may be used to map and unmap windows managed by Tk. \fBTk_MapWindow\fR maps the window given by \fItkwin\fR, and also creates an X window corresponding to \fItkwin\fR if it does not already exist. See the \fBTk_CreateWindow\fR manual entry for information on deferred window creation. \fBTk_UnmapWindow\fR unmaps \fItkwin\fR's window from the screen. .PP If \fItkwin\fR is a child window (i.e. \fBTk_CreateWindow\fR was used to create a child window), then event handlers interested in map and unmap events are invoked immediately. If \fItkwin\fR is not an internal window, then the event handlers will be invoked later, after X has seen the request and returned an event for it. .PP These procedures should be used in place of the X procedures \fBXMapWindow\fR and \fBXUnmapWindow\fR, since they update Tk's local data structure for \fItkwin\fR. Applications using Tk should not invoke \fBXMapWindow\fR and \fBXUnmapWindow\fR directly. .SH KEYWORDS map, unmap, window tk9.0.3/doc/MeasureChar.30000644001000000100000000001563715105057705020113 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_MeasureChars 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_MeasureChars, Tk_MeasureCharsInContext, Tk_TextWidth, Tk_DrawChars, Tk_DrawCharsInContext, Tk_UnderlineChars, Tk_UnderlineCharsInContext \- routines to measure and display simple single-line strings. .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_MeasureChars\fR(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fR) .sp int \fBTk_MeasureCharsInContext\fR(\fItkfont, string, numBytes, rangeStart, rangeLength, maxPixels, flags, lengthPtr\fR) .sp int \fBTk_TextWidth\fR(\fItkfont, string, numBytes\fR) .sp \fBTk_DrawChars\fR(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fR) .sp \fBTk_DrawCharsInContext\fR(\fIdisplay, drawable, gc, tkfont, string, numBytes, rangeStart, rangeLength, x, y\fR) .sp \fBTk_UnderlineChars\fR(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fR) .sp \fBTk_UnderlineCharsInContext\fR(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y, firstByte, lastByte\fR) .fi .SH ARGUMENTS .AS "const char" firstChar .AP Tk_Font tkfont in Token for font in which text is to be drawn or measured. Must have been returned by a previous call to \fBTk_GetFont\fR. .AP "const char" *string in Text to be measured or displayed. Need not be null terminated. Any non-printing meta-characters in the string (such as tabs, newlines, and other control characters) will be measured or displayed in a platform-dependent manner. .AP Tcl_Size numBytes in The maximum number of bytes to consider when measuring or drawing \fIstring\fR. Must be greater than or equal to 0. .AP int maxPixels in If \fImaxPixels\fR is >= 0, it specifies the longest permissible line length in pixels. Characters from \fIstring\fR are processed only until this many pixels have been covered. If \fImaxPixels\fR is < 0, then the line length is unbounded and the \fIflags\fR argument is ignored. .AP int flags in Various flag bits OR-ed together: \fBTK_PARTIAL_OK\fR means include a character as long as any part of it fits in the length given by \fImaxPixels\fR; otherwise, a character must fit completely to be considered. \fBTK_WHOLE_WORDS\fR means stop on a word boundary, if possible. If \fBTK_AT_LEAST_ONE\fR is set, it means return at least one character even if no characters could fit in the length given by \fImaxPixels\fR. If \fBTK_AT_LEAST_ONE\fR is set and \fBTK_WHOLE_WORDS\fR is also set, it means that if not even one word fits on the line, return the first few letters of the word that did fit; if not even one letter of the word fit, then the first letter will still be returned. \fBTK_ISOLATE_END\fR means that the last character should not be considered in context with the rest of the string (used for breaking lines, with the Tk_*InContext variants of the functions only). .AP int *lengthPtr out Filled with the number of pixels occupied by the number of characters returned as the result of \fBTk_MeasureChars\fR. .AP Display *display in Display on which to draw. .AP Drawable drawable in Window or pixmap in which to draw. .AP GC gc in Graphics context for drawing characters. The font selected into this GC must be the same as the \fItkfont\fR. .AP int "x, y" in Coordinates at which to place the left edge of the baseline when displaying \fIstring\fR. .AP int firstByte in The index of the first byte of the first character to underline in the \fIstring\fR. Underlining begins at the left edge of this character. .AP int lastByte in The index of the first byte of the last character up to which the underline will be drawn. The character specified by \fIlastByte\fR will not itself be underlined. .AP Tcl_Size rangeStart in Index of first byte to draw or to measure. .AP Tcl_Size rangeLength in Length of range to draw or to measure, in bytes. .BE .SH DESCRIPTION .PP These routines are for measuring and displaying simple single-font, single-line strings. To measure and display single-font, multi-line, justified text, refer to the documentation for \fBTk_ComputeTextLayout\fR. There is no programming interface in the core of Tk that supports multi-font, multi-line text; support for that behavior must be built on top of simpler layers. Note that the interfaces described here are byte-oriented not character-oriented, so index values coming from Tcl scripts need to be converted to byte offsets using the \fBTcl_UtfAtIndex\fR and related routines. .PP A glyph is the displayable picture of a letter, number, or some other symbol. Not all character codes in a given font have a glyph. Characters such as tabs, newlines/returns, and control characters that have no glyph are measured and displayed by these procedures in a platform-dependent manner; under X, they are replaced with backslashed escape sequences, while under Windows and Macintosh hollow or solid boxes may be substituted. Refer to the documentation for \fBTk_ComputeTextLayout\fR for a programming interface that supports the platform-independent expansion of tab characters into columns and newlines/returns into multi-line text. .PP \fBTk_MeasureChars\fR is used both to compute the length of a given string and to compute how many characters from a string fit in a given amount of space. The return value is the number of bytes from \fIstring\fR that fit in the space specified by \fImaxPixels\fR subject to the conditions described by \fIflags\fR. If all characters fit, the return value will be \fInumBytes\fR. \fI*lengthPtr\fR is filled with the computed width, in pixels, of the portion of the string that was measured. For example, if the return value is 5, then \fI*lengthPtr\fR is filled with the distance between the left edge of \fIstring\fR[0] and the right edge of \fIstring\fR[4]. .PP \fBTk_TextWidth\fR is a wrapper function that provides a simpler interface to the \fBTk_MeasureChars\fR function. The return value is how much space in pixels the given \fIstring\fR needs. .PP \fBTk_DrawChars\fR draws the \fIstring\fR at the given location in the given \fIdrawable\fR. .PP \fBTk_UnderlineChars\fR underlines the given range of characters in the given \fIstring\fR. It does not draw the characters (which are assumed to have been displayed previously by \fBTk_DrawChars\fR); it just draws the underline. This procedure is used to underline a few characters without having to construct an underlined font. To produce natively underlined text, the appropriate underlined font should be constructed and used. .PP \fBTk_MeasureCharsInContext\fR, \fBTk_DrawCharsInContext\fR, \fBTk_UnderlineCharsInContext\fR are variants of respectively \fBTk_MeasureChars\fR, \fBTk_DrawChars\fR and \fBTk_UnderlineChars\fR, but with access to all the characters on the line for context. Except on macOS, this context isn't actually consulted (meaning the out of context variants are called). .SH "SEE ALSO" font(n), FontId(3) .SH KEYWORDS font, measurement tk9.0.3/doc/menu.n0000644001000000100000000011233515105057705016744 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH menu n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME menu, tk_menuSetFocus \- Create and manipulate 'menu' widgets and menubars .SH SYNOPSIS .nf \fBmenu\fI pathName \fR?\fIoptions\fR? \fBtk_menuSetFocus\fI pathName\fR .fi .SO \-activebackground \-borderwidth \-foreground \-activeborderwidth \-cursor \-relief \-activeforeground \-disabledforeground \-takefocus \-background \-font \-activerelief .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-postcommand postCommand Command If this option is specified then it provides a Tcl command to execute each time the menu is posted. The command is invoked by the \fBpost\fR widget command before posting the menu. Note that in Tk 8.0 on Macintosh and Windows, all post-commands in a system of menus are executed before any of those menus are posted. This is due to the limitations in the individual platforms' menu managers. .OP \-selectcolor selectColor Background For menu entries that are check buttons or radio buttons, this option specifies the color to display in the indicator when the check button or radio button is selected. .OP \-tearoff tearOff TearOff This option must have a proper boolean value (default is false), which specifies whether or not the menu should include a tear-off entry at the top. If so, it will exist as entry 0 of the menu and the other entries will number starting at 1. The default menu bindings arrange for the menu to be torn off when the tear-off entry is invoked. This option is ignored under Aqua/macOS, where menus cannot be torn off. .OP \-tearoffcommand tearOffCommand TearOffCommand If this option has a non-empty value, then it specifies a Tcl command to invoke whenever the menu is torn off. The actual command will consist of the value of this option, followed by a space, followed by the name of the menu window, followed by a space, followed by the name of the name of the torn off menu window. For example, if the option's value is .QW "\fBa b\fR" and menu \fB.x.y\fR is torn off to create a new menu \fB.x.tearoff1\fR, then the command .QW "\fBa b .x.y .x.tearoff1\fR" will be invoked. This option is ignored under Aqua/macOS, where menus cannot be torn off. .OP \-title title Title The string will be used to title the window created when this menu is torn off. If the title is NULL, then the window will have the title of the menubutton or the text of the cascade item from which this menu was invoked. .OP \-type type Type This option can be one of \fBmenubar\fR, \fBtearoff\fR, or \fBnormal\fR, and is set when the menu is created. While the string returned by the configuration database will change if this option is changed, this does not affect the menu widget's behavior. This is used by the cloning mechanism and is not normally set outside of the Tk library. .BE .SH INTRODUCTION .PP The \fBmenu\fR command creates a new top-level window (given by the \fIpathName\fR argument) and makes it into a menu widget. That menu widget can either be used as a pop-up window or applied to a \fBtoplevel\fR (with its \fB\-menu\fR option) to make it into the menubar for that toplevel. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the menu such as its colors and font. The \fBmenu\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A menu is a widget that displays a collection of one-line entries arranged in one or more columns. There exist several different types of entries, each with different properties. Entries of different types may be combined in a single menu. Menu entries are not the same as entry widgets. In fact, menu entries are not even distinct widgets; the entire menu is one widget. .PP Menu entries are displayed with up to three separate fields. The main field is a label in the form of a text string, a bitmap, or an image, controlled by the \fB\-label\fR, \fB\-bitmap\fR, and \fB\-image\fR options for the entry. If the \fB\-accelerator\fR option is specified for an entry then a second textual field is displayed to the right of the label. The accelerator typically describes a keystroke sequence that may be used in the application to cause the same result as invoking the menu entry. This is a display option, it does not actually set the corresponding binding (which can be achieved using the \fBbind\fR command). The third field is an \fIindicator\fR. The indicator is present only for checkbutton or radiobutton entries. It indicates whether the entry is selected or not, and is displayed to the left of the entry's string. .PP In normal use, an entry becomes active (displays itself differently) whenever the mouse pointer is over the entry. If a mouse button is released over the entry then the entry is \fIinvoked\fR. The effect of invocation is different for each type of entry; these effects are described below in the sections on individual entries. .PP Entries may be \fIdisabled\fR, which causes their labels and accelerators to be displayed with dimmer colors. The default menu bindings will not allow a disabled entry to be activated or invoked. Disabled entries may be re-enabled, at which point it becomes possible to activate and invoke them again. .PP Whenever a menu's active entry is changed, a <> virtual event is send to the menu. The active item can then be queried from the menu, and an action can be taken, such as setting context-sensitive help text for the entry. .SH "TYPES OF ENTRIES" .SS "COMMAND ENTRIES" .PP The most common kind of menu entry is a command entry, which behaves much like a button widget. When a command entry is invoked, a Tcl command is executed. The Tcl command is specified with the \fB\-command\fR option. .SS "SEPARATOR ENTRIES" .PP A separator is an entry that is displayed as a horizontal dividing line. A separator may not be activated or invoked, and it has no behavior other than its display appearance. .SS "CHECKBUTTON ENTRIES" .PP A checkbutton menu entry behaves much like a checkbutton widget. When it is invoked it toggles back and forth between the selected and deselected states. When the entry is selected, a particular value is stored in a particular global variable (as determined by the \fB\-onvalue\fR and \fB\-variable\fR options for the entry); when the entry is deselected another value (determined by the \fB\-offvalue\fR option) is stored in the global variable. An indicator box is displayed to the left of the label in a checkbutton entry. If the entry is selected then the indicator's center is displayed in the color given by the \fB\-selectcolor\fR option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If a \fB\-command\fR option is specified for a checkbutton entry, then its value is evaluated as a Tcl command each time the entry is invoked; this happens after toggling the entry's selected state. .SS "RADIOBUTTON ENTRIES" .PP A radiobutton menu entry behaves much like a radiobutton widget. Radiobutton entries are organized in groups of which only one entry may be selected at a time. Whenever a particular entry becomes selected it stores a particular value into a particular global variable (as determined by the \fB\-value\fR and \fB\-variable\fR options for the entry). This action causes any previously-selected entry in the same group to deselect itself. Once an entry has become selected, any change to the entry's associated variable will cause the entry to deselect itself. Grouping of radiobutton entries is determined by their associated variables: if two entries have the same associated variable then they are in the same group. An indicator diamond is displayed to the left of the label in each radiobutton entry. If the entry is selected then the indicator's center is displayed in the color given by the \fB\-selectcolor\fR option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If a \fB\-command\fR option is specified for a radiobutton entry, then its value is evaluated as a Tcl command each time the entry is invoked; this happens after selecting the entry. .SS "CASCADE ENTRIES" .PP A cascade entry is one with an associated menu (determined by the \fB\-menu\fR option). Cascade entries allow the construction of cascading menus. The \fBpostcascade\fR widget command can be used to post and unpost the associated menu just next to of the cascade entry. The associated menu must be a child of the menu containing the cascade entry (this is needed in order for menu traversal to work correctly). .PP A cascade entry posts its associated menu by invoking a Tcl command of the form .CS \fImenu\fB post \fIx y\fR .CE where \fImenu\fR is the path name of the associated menu, and \fIx\fR and \fIy\fR are the root-window coordinates of the upper-right corner of the cascade entry. On Unix, the lower-level menu is unposted by executing a Tcl command with the form .CS \fImenu\fB unpost\fR .CE where \fImenu\fR is the name of the associated menu. On other platforms, the platform's native code takes care of unposting the menu. .PP If a \fB\-command\fR option is specified for a cascade entry then it is evaluated as a Tcl command whenever the entry is invoked. This is not supported on Windows. .SS "TEAR-OFF ENTRIES" .PP A tear-off entry appears at the top of the menu if enabled with the \fB\-tearoff\fR option. It is not like other menu entries in that it cannot be created with the \fBadd\fR widget command and cannot be deleted with the \fBdelete\fR widget command. When a tear-off entry is created it appears as a dashed line at the top of the menu. Under the default bindings, invoking the tear-off entry causes a torn-off copy to be made of the menu and all of its submenus. .SH "MENUBARS" .PP Any menu can be set as a menubar for a toplevel window (see \fBtoplevel\fR command for syntax). On the Macintosh, whenever the toplevel is in front, this menu's cascade items will appear in the menubar across the top of the main screen. On Windows and Unix, this menu's items will be displayed in a menubar across the top of the window. These menus will behave according to the interface guidelines of their platforms. In particular, since macOS requires that a menubar always be displayed for the active app, if no menu is assigned by a \fBconfigure -menu\fR for a certain toplevel then a standard default menu will be displayed whenever that toplevel has focus. For every menu set as a menubar, a clone menu is made. See the \fBCLONES\fR section for more information. .PP As noted, menubars may behave differently on different platforms. One example of this concerns the handling of checkbuttons and radiobuttons within the menu. While it is permitted to put these menu elements on menubars, they may not be drawn with indicators on some platforms, due to system restrictions. .SS "SPECIAL MENUS IN MENUBARS" .PP Certain menus in a menubar will be treated specially. On the Macintosh, access to the special Application, Window and Help menus is provided. On Windows, access to the Windows System menu in each window is provided. On X Windows, a special right-justified help menu may be provided if Motif menu compatibility is enabled. In all cases, these menus must be created with the command name of the menubar menu concatenated with the special name. So for a menubar named .menubar, on the Macintosh, the special menus would be .menubar.apple, .menubar.window and .menubar.help; on Windows, the special menu would be .menubar.system; on X Windows, the help menu would be .menubar.help. .PP When Tk sees a .menubar.apple menu as the first menu in a menubar on the Macintosh, that menu's contents make up the first items of the Application menu whenever the window containing the menubar is in front. After all of the Tk-defined items, the menu will have a separator, followed by all standard Application menu items. Such a .apple menu must be present in a menu when that menu is first configured as a toplevel's menubar, otherwise a default application menu (hidden from Tk) will be inserted into the menubar at that time and subsequent addition of a .apple menu will no longer result in it becoming the Application menu. .PP When Tk sees a .menubar.window menu on the Macintosh, the menu's contents are inserted into the standard Window menu of the user's menubar whenever the window's menubar is in front. The first items in the menu are provided by macOS, and the names of the current toplevels are automatically appended after all the Tk-defined items and a separator. The Window menu on the Mac also allows toggling the window into a fullscreen state, and managing a tabbed window interface (multiple windows grouped into a single window) if supported by that version of the operating system. .PP When Tk sees a .menubar.help menu on the Macintosh, the menu's contents are appended to the standard Help menu of the user's menubar whenever the window's menubar is in front. The first items in the menu are provided by macOS. .PP When Tk sees a System menu on Windows, its items are appended to the system menu that the menubar is attached to. This menu is tied to the application icon and can be invoked with the mouse or by typing Alt+Spacebar. Due to limitations in the Windows API, any font changes, colors, images, bitmaps, or tearoff images will not appear in the system menu. .PP When Tk sees a Help menu on X Windows and Motif menu compatibility is enabled the menu is moved to be last in the menubar and is right justified. Motif menu compatibility is enabled by setting the Tk option \fB*Menu.useMotifHelp\fR to true. .SH "CLONES" .PP When a menu is set as a menubar for a toplevel window, or when a menu is torn off, a clone of the menu is made. This clone is a menu widget in its own right, but it is a child of the original. Changes in the configuration of the original are reflected in the clone. Additionally, any cascades that are pointed to are also cloned so that menu traversal will work right. Clones are destroyed when either the tearoff or menubar goes away, or when the original menu is destroyed. .SH "WIDGET COMMAND" .PP The \fBmenu\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. .PP Many of the widget commands for a menu take as one argument an indicator of which entry of the menu to operate on. These indicators are called \fIindex\fRes and may be specified in any of the following forms: .IP \fBactive\fR 12 Indicates the entry that is currently active. If no entry is active then this form is equivalent to \fB{}\fR. This form may not be abbreviated. .IP \fBend\fR 12 Indicates the bottommost entry in the menu. If there are no entries in the menu then this form is equivalent to \fB{}\fR. This form may not be abbreviated. .IP \fBlast\fR 12 Same as \fBend\fR. .IP \fB{}\fR 12 Indicates .QW "no entry at all" ; this is used most commonly with the \fBactivate\fR option to deactivate all the entries in the menu. In most cases the specification of \fB{}\fR causes nothing to happen in the widget command. .IP \fB@\fIx\fB,\fIy\fR 12 Indicates the entry that covers the point in the menu's window specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no entry covers that point, then this form is equivalent to \fB{}\fR. If only a single number is specified, it is treated as the y-coordinate. .IP \fInumber\fR 12 Specifies the entry numerically, where 0 corresponds to the top-most entry of the menu, 1 to the entry below it, and so on. .IP \fIid\fR 12 If the index does not satisfy one of the above forms then the menu is searched for an entry with the specified id. .IP \fIpattern\fR 12 If all of the above methods for finding an entry fail, this form is used. \fIPattern\fR is pattern-matched against the label of each entry in the menu, in order from the top down, until a matching entry is found. The rules of \fBstring match\fR are used. .PP If the index could match more than one of the above forms, then the form earlier in the above list takes precedence. Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. .PP The following widget commands are possible for menu widgets: .\" METHOD: activate .TP \fIpathName \fBactivate \fIindex\fR . Change the state of the entry indicated by \fIindex\fR to \fBactive\fR and redisplay it using its active colors. Any previously-active entry is deactivated. If \fIindex\fR is specified as \fB{}\fR, or if the specified entry is disabled, then the menu ends up with no active entry. Returns an empty string. .\" METHOD: add .TP \fIpathName \fBadd \fItype \fR?\fIid\fR? ?\fIoption value option value ...\fR? . Add a new entry to the bottom of the menu. The new entry's type is given by \fItype\fR and must be one of \fBcascade\fR, \fBcheckbutton\fR, \fBcommand\fR, \fBradiobutton\fR, or \fBseparator\fR, or a unique abbreviation of one of the above. If the \fIid\fR argument is specified, it is used as the entry identifier; \fIid\fR must not already exist in the menu. Otherwise, a new unique identifier is generated. If additional arguments are present, they specify the options listed in the \fBMENU ENTRY OPTIONS\fR section below. The \fBadd\fR widget command returns the id of the new entry. .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmenu\fR command. .\" METHOD: clone .TP \fIpathName \fBclone \fInewPathname\fR ?\fIcloneType\fR? . Makes a clone of the current menu named \fInewPathName\fR. This clone is a menu in its own right, but any changes to the clone are propagated to the original menu and vice versa. \fIcloneType\fR can be \fBnormal\fR, \fBmenubar\fR, or \fBtearoff\fR. Should not normally be called outside of the Tk library. See the \fBCLONES\fR section for more information. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBmenu\fR command. .\" METHOD: delete .TP \fIpathName \fBdelete \fIindex1\fR ?\fIindex2\fR? . Delete all of the menu entries between \fIindex1\fR and \fIindex2\fR inclusive. If \fIindex2\fR is omitted then it defaults to \fIindex1\fR. Attempts to delete a tear-off menu entry are ignored (instead, you should change the \fB\-tearoff\fR option to remove the tear-off entry). .\" METHOD: entrycget .TP \fIpathName \fBentrycget \fIindex option\fR . Returns the current value of a configuration option for the entry given by \fIindex\fR. \fIOption\fR may have any of the names described in the \fBMENU ENTRY OPTIONS\fR section below. .\" METHOD: entryconfigure .TP \fIpathName \fBentryconfigure \fIindex \fR?\fIoptions...\fR? . This command is similar to the \fBconfigure\fR command, except that it applies to the options for an individual entry, whereas \fBconfigure\fR applies to the options for the menu as a whole. \fIOptions\fR may have any of the values described in the \fBMENU ENTRY OPTIONS\fR section below. If \fIoptions\fR are specified, options are modified as indicated in the command and the command returns an empty string. If no \fIoptions\fR are specified, returns a list describing the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). .\" METHOD: id .TP \fIpathName \fBid \fIindex\fR . Returns the id of the menu entry given by \fIindex\fR. This is the identifier that was assigned to the entry when it was created using the \fBadd\fR or \fBinsert\fR widget command. Returns an empty string for the tear-off entry, or if \fIindex\fR is equivalent to \fB{}\fR. .\" METHOD: index .TP \fIpathName \fBindex \fIindex\fR . Returns the numerical index corresponding to \fIindex\fR, or \fB{}\fR if \fIindex\fR was specified as \fB{}\fR. .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex type \fR?\fIid\fR? ?\fIoption value option value ...\fR? . Same as the \fBadd\fR widget command except that it inserts the new entry just before the entry given by \fIindex\fR, instead of appending to the end of the menu. The \fItype\fR, \fIid\fR, \fIoption\fR, and \fIvalue\fR arguments have the same interpretation as for the \fBadd\fR widget command. It is not possible to insert new menu entries before the tear-off entry, if the menu has one. The \fBinsert\fR widget command returns the id of the new entry. .\" METHOD: invoke .TP \fIpathName \fBinvoke \fIindex\fR . Invoke the action of the menu entry. See the sections on the individual entries above for details on what happens. If the menu entry is disabled then nothing happens. If the entry has a command associated with it then the result of that command is returned as the result of the \fBinvoke\fR widget command. Otherwise the result is an empty string. Note: invoking a menu entry does not automatically unpost the menu; the default bindings normally take care of this before invoking the \fBinvoke\fR widget command. .\" METHOD: post .TP \fIpathName \fBpost \fIx y\fR ?\fIindex\fR? . Arrange for the menu to be displayed on the screen at the root-window coordinates given by \fIx\fR and \fIy\fR. If an index is specified the menu will be located so that the entry with that index is displayed at the point. These coordinates are adjusted if necessary to guarantee that the entire menu is visible on the screen. This command normally returns an empty string. If the \fB\-postcommand\fR option has been specified, then its value is executed as a Tcl script before posting the menu and the result of that script is returned as the result of the \fBpost\fR widget command. If an error returns while executing the command, then the error is returned without posting the menu. .\" METHOD: postcascade .TP \fIpathName \fBpostcascade \fIindex\fR . Posts the submenu associated with the cascade entry given by \fIindex\fR, and unposts any previously posted submenu. If \fIindex\fR does not correspond to a cascade entry, or if \fIpathName\fR is not posted, the command has no effect except to unpost any currently posted submenu. .\" METHOD: type .TP \fIpathName \fBtype \fIindex\fR . Returns the type of the menu entry given by \fIindex\fR. This is the \fItype\fR argument passed to the \fBadd\fR or \fBinsert\fR widget command when the entry was created, such as \fBcommand\fR or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry. .\" METHOD: unpost .TP \fIpathName \fBunpost\fR . Unmap the window so that it is no longer displayed. If a lower-level cascaded menu is posted, unpost that menu. Returns an empty string. This subcommand does not work on Windows and the Macintosh, as those platforms have their own way of unposting menus. .\" METHOD: xposition .TP \fIpathName \fBxposition \fIindex\fR . Returns a decimal string giving the x-coordinate within the menu window of the leftmost pixel in the entry specified by \fIindex\fR. .\" METHOD: yposition .TP \fIpathName \fByposition \fIindex\fR . Returns a decimal string giving the y-coordinate within the menu window of the topmost pixel in the entry specified by \fIindex\fR. .SH "MENU ENTRY OPTIONS" The following options are allowed on menu entries. Most options are not supported by all entry types. .\" OPTION: -activebackground .TP \fB\-activebackground \fIvalue\fR . Specifies a background color to use for displaying this entry when it is active. This option is ignored on Aqua/macOS. If it is specified as an empty string (the default), then the \fB\-activebackground\fR option for the overall menu is used. If the \fBtk_strictMotif\fR variable has been set to request strict Motif compliance, then this option is ignored and the \fB\-background\fR option is used in its place. This option is not available for separator or tear-off entries. .\" OPTION: -activeforeground .TP \fB\-activeforeground \fIvalue\fR . Specifies a foreground color to use for displaying this entry when it is active. This option is ignored on Aqua/macOS. If this option is specified as an empty string (the default), then the \fB\-activeforeground\fR option for the overall menu is used. .\" OPTION: -accelerator .TP \fB\-accelerator \fIvalue\fR . Specifies a string to display at the right side of the menu entry. Normally describes an accelerator keystroke sequence that may be used to invoke the same function as the menu entry. This is a display option, it does not actually set the corresponding binding (which can be achieved using the \fBbind\fR command). This option is not available for separator or tear-off entries. .\" OPTION: -background .TP \fB\-background \fIvalue\fR . Specifies a background color to use for displaying this entry when it is in the normal state (neither active nor disabled). This option is ignored on Aqua/macOS. If it is specified as an empty string (the default), then the \fB\-background\fR option for the overall menu is used. This option is not available for separator or tear-off entries. .\" OPTION: -bitmap .TP \fB\-bitmap \fIvalue\fR . Specifies a bitmap to display in the menu instead of a textual label, in any of the forms accepted by \fBTk_GetBitmap\fR. This option overrides the \fB\-label\fR option (as controlled by the \fB\-compound\fR option) but may be reset to an empty string to enable a textual label to be displayed. If a \fB\-image\fR option has been specified, it overrides \fB\-bitmap\fR. This option is not available for separator or tear-off entries. .\" OPTION: -columnbreak .TP \fB\-columnbreak \fIvalue\fR . When this option is zero, the entry appears below the previous entry. When this option is one, the entry appears at the top of a new column in the menu. This option is ignored on Aqua/macOS, where menus are always a single column. .\" OPTION: -command .TP \fB\-command \fIvalue\fR . Specifies a Tcl command to execute when the menu entry is invoked. Not available for separator or tear-off entries. .\" OPTION: -compound .TP \fB\-compound \fIvalue\fR . Specifies whether the menu entry should display both an image and text, and if so, where the image should be placed relative to the text. Valid values for this option are \fBbottom\fR, \fBcenter\fR, \fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value is \fBnone\fR, meaning that the button will display either an image or text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR options. .\" OPTION: -font .TP \fB\-font \fIvalue\fR . Specifies the font to use when drawing the label or accelerator string in this entry. If this option is specified as an empty string (the default) then the \fB\-font\fR option for the overall menu is used. This option is not available for separator or tear-off entries. .\" OPTION: -foreground .TP \fB\-foreground \fIvalue\fR . Specifies a foreground color to use for displaying this entry when it is in the normal state (neither active nor disabled). This option is ignored on Aqua/macOS. If it is specified as an empty string (the default), then the \fB\-foreground\fR option for the overall menu is used. This option is not available for separator or tear-off entries. .\" OPTION: -hidemargin .TP \fB\-hidemargin \fIvalue\fR . Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. 1 indicates that the margin for the entry is hidden; 0 means that the margin is used. .\" OPTION: -image .TP \fB\-image \fIvalue\fR . Specifies an image to display in the menu instead of a text string or bitmap. The image must have been created by some previous invocation of \fBimage create\fR. This option overrides the \fB\-label\fR and \fB\-bitmap\fR options (as controlled by the \fB\-compound\fR option) but may be reset to an empty string to enable a textual or bitmap label to be displayed. This option is not available for separator or tear-off entries. .\" OPTION: -indicatoron .TP \fB\-indicatoron \fIvalue\fR . Available only for checkbutton and radiobutton entries. \fIValue\fR is a boolean that determines whether or not the indicator should be displayed. .\" OPTION: -label .TP \fB\-label \fIvalue\fR . Specifies a string to display as an identifying label in the menu entry. Not available for separator or tear-off entries. .\" OPTION: -menu .TP \fB\-menu \fIvalue\fR . Available only for cascade entries. Specifies the path name of the submenu associated with this entry. The submenu must be a child of the menu. .\" OPTION: -offvalue .TP \fB\-offvalue \fIvalue\fR . Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is deselected. .\" OPTION: -onvalue .TP \fB\-onvalue \fIvalue\fR . Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. .\" OPTION: -selectcolor .TP \fB\-selectcolor \fIvalue\fR . Available only for checkbutton and radiobutton entries. Specifies the color to display in the indicator when the entry is selected. If the value is an empty string (the default) then the \fB\-selectcolor\fR option for the menu determines the indicator color. .\" OPTION: -selectimage .TP \fB\-selectimage \fIvalue\fR . Available only for checkbutton and radiobutton entries. Specifies an image to display in the entry (in place of the \fB\-image\fR option) when it is selected. \fIValue\fR is the name of an image, which must have been created by some previous invocation of \fBimage create\fR. This option is ignored unless the \fB\-image\fR option has been specified. .\" OPTION: -state .TP \fB\-state \fIvalue\fR . Specifies one of three states for the entry: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the entry is displayed using the \fB\-foreground\fR option for the menu and the \fB\-background\fR option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the \fB\-activeforeground\fR option for the menu along with the \fB\-activebackground\fR option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the \fB\-disabledforeground\fR option for the menu and the \fB\-background\fR option from the entry. This option is not available for separator entries. .\" OPTION: -underline .TP \fB\-underline \fIvalue\fR . Specifies the integer index of a character to underline in the entry. This option is also queried by the default bindings and used to implement keyboard traversal. 0 corresponds to the first character of the text displayed in the entry, 1 to the next character, and so on. If a bitmap or image is displayed in the entry then this option is ignored. This option is not available for separator or tear-off entries. .\" OPTION: -value .TP \fB\-value \fIvalue\fR . Available only for radiobutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. If an empty string is specified, then the \fB\-label\fR option for the entry as the value to store in the variable. .\" OPTION: -variable .TP \fB\-variable \fIvalue\fR . Available only for checkbutton and radiobutton entries. Specifies the name of a global variable to set when the entry is selected. For checkbutton entries the variable is also set when the entry is deselected. For radiobutton entries, changing the variable causes the currently-selected entry to deselect itself. .RS .PP For checkbutton entries, the default value of this option is taken from the \fB\-label\fR option, and for radiobutton entries a single fixed value is used. It is recommended that you always set the \fB\-variable\fR option when creating either a checkbutton or a radiobutton. .RE .SH "MENU CONFIGURATIONS" .PP The default bindings support four different ways of using menus: .TP \fBPulldown Menus in Menubar\fR . This is the most common case. You create a menu widget that will become the menu bar. You then add cascade entries to this menu, specifying the pull down menus you wish to use in your menu bar. You then create all of the pulldowns. Once you have done this, specify the menu using the \fB\-menu\fR option of the toplevel's widget command. See the \fBtoplevel\fR manual entry for details. .TP \fBPulldown Menus in Menu Buttons\fR . This is the compatible way to do menu bars. You create one menubutton widget for each top-level menu, and typically you arrange a series of menubuttons in a row in a menubar window. You also create the top-level menus and any cascaded submenus, and tie them together with \fB\-menu\fR options in menubuttons and cascade menu entries. The top-level menu must be a child of the menubutton, and each submenu must be a child of the menu that refers to it. Once you have done this, the default bindings will allow users to traverse and invoke the tree of menus via its menubutton; see the \fBmenubutton\fR manual entry for details. .TP \fBPopup Menus\fR . Popup menus typically post in response to a mouse button press or keystroke. You create the popup menus and any cascaded submenus, then you call the \fBtk_popup\fR procedure at the appropriate time to post the top-level menu. .TP \fBOption Menus\fR . An option menu consists of a menubutton with an associated menu that allows you to select one of several values. The current value is displayed in the menubutton and is also stored in a global variable. Use the \fBtk_optionMenu\fR procedure to create option menubuttons and their menus. .TP \fBTorn-off Menus\fR . You create a torn-off menu by invoking the tear-off entry at the top of an existing menu. The default bindings will create a new menu that is a copy of the original menu and leave it permanently posted as a top-level window. The torn-off menu behaves just the same as the original menu. .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for menus that give them the following default behavior: .IP [1] When the mouse enters a menu, the entry underneath the mouse cursor activates; as the mouse moves around the menu, the active entry changes to track the mouse. .IP [2] When the mouse leaves a menu all of the entries in the menu deactivate, except in the special case where the mouse moves from a menu to a cascaded submenu. .IP [3] When a button is released over a menu, the active entry (if any) is invoked. The menu also unposts unless it is a torn-off menu. .IP [4] The Space and Return keys invoke the active entry and unpost the menu. .IP [5] If any of the entries in a menu have letters underlined with the \fB\-underline\fR option, then pressing one of the underlined letters (or its upper-case or lower-case equivalent) invokes that entry and unposts the menu. .IP [6] The Escape key aborts a menu selection in progress without invoking any entry. It also unposts the menu unless it is a torn-off menu. .IP [7] The Up and Down keys activate the next higher or lower entry in the menu. When one end of the menu is reached, the active entry wraps around to the other end. .IP [8] The Left key moves to the next menu to the left. If the current menu is a cascaded submenu, then the submenu is unposted and the current menu entry becomes the cascade entry in the parent. If the current menu is a top-level menu posted from a menubutton, then the current menubutton is unposted and the next menubutton to the left is posted. Otherwise the key has no effect. The left-right order of menubuttons is determined by their stacking order: Tk assumes that the lowest menubutton (which by default is the first one created) is on the left. .IP [9] The Right key moves to the next menu to the right. If the current entry is a cascade entry, then the submenu is posted and the current menu entry becomes the first entry in the submenu. Otherwise, if the current menu was posted from a menubutton, then the current menubutton is unposted and the next menubutton to the right is posted. .PP Disabled menu entries are non-responsive: they do not activate and they ignore mouse button presses and releases. .PP Several of the bindings make use of the command \fBtk_menuSetFocus\fR. It saves the current focus and sets the focus to its \fIpathName\fR argument, which is a menu widget. .PP The behavior of menus can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH BUGS .PP At present it is not possible to use the option database to specify values for the options to individual entries. .SH "SEE ALSO" bind(n), menubutton(n), ttk::menubutton(n), toplevel(n) .SH KEYWORDS menu, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/menubutton.n0000644001000000100000000002177615076161057020213 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH menubutton n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME menubutton \- Create and manipulate 'menubutton' pop-up menu indicator widgets .SH SYNOPSIS \fBmenubutton\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-disabledforeground \-padx \-activeforeground \-font \-pady \-anchor \-foreground \-relief \-background \-highlightbackground \-takefocus \-bitmap \-highlightcolor \-text \-borderwidth \-highlightthickness \-textvariable \-cursor \-image \-underline \-compound \-justify \-wraplength .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-direction direction Direction Specifies where the menu is going to be popup up. \fBabove\fR tries to pop the menu above the menubutton. \fBbelow\fR tries to pop the menu below the menubutton. \fBleft\fR tries to pop the menu to the left of the menubutton. \fBright\fR tries to pop the menu to the right of the menu button. \fBflush\fR pops the menu directly over the menubutton. In the case of \fBabove\fR or \fBbelow\fR, the direction will be reversed if the menu would show offscreen. .OP \-height height Height Specifies a desired height for the menubutton. If an image or bitmap is being displayed in the menubutton then the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); for text it is in lines of text. If this option is not specified, the menubutton's desired height is computed from the size of the image or bitmap or text being displayed in it. .OP \-indicatoron indicatorOn IndicatorOn The value must be a proper boolean value. If it is true then a small indicator rectangle will be displayed on the right side of the menubutton and the default menu bindings will treat this as an option menubutton. If false then no indicator will be displayed. .OP \-menu menu MenuName Specifies the path name of the menu associated with this menubutton. The menu must be a child of the menubutton. .OP \-state state State Specifies one of three states for the menubutton: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the menubutton is displayed using the \fBforeground\fR and \fBbackground\fR options. The active state is typically used when the pointer is over the menubutton. In active state the menubutton is displayed using the \fB\-activeforeground\fR and \fB\-activebackground\fR options. Disabled state means that the menubutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the \fB\-disabledforeground\fR and \fB\-background\fR options determine how the button is displayed. .OP \-width width Width Specifies a desired width for the menubutton. If an image or bitmap is being displayed in the menubutton then the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); for text it is in characters. If this option is not specified, the menubutton's desired width is computed from the size of the image or bitmap or text being displayed in it. .BE .SH INTRODUCTION .PP The \fBmenubutton\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a menubutton widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the menubutton such as its colors, font, text, and initial relief. The \fBmenubutton\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A menubutton is a widget that displays a textual string, bitmap, or image and is associated with a menu widget. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the \fB\-wraplength\fR option) and one of the characters may optionally be underlined using the \fB\-underline\fR option. In normal usage, pressing mouse button 1 over the menubutton causes the associated menu to be posted just underneath the menubutton. If the mouse is moved over the menu before releasing the mouse button, the button release causes the underlying menu entry to be invoked. When the button is released, the menu is unposted. .PP Menubuttons are used to construct a \fBtk_optionMenu\fR, which is the preferred mechanism for allowing a user to select one item from a list on macOS. .PP Menubuttons were also typically organized into groups called menu bars that allow scanning: if the mouse button is pressed over one menubutton (causing it to post its menu) and the mouse is moved over another menubutton in the same menu bar without releasing the mouse button, then the menu of the first menubutton is unposted and the menu of the new menubutton is posted instead. \fIThis use is deprecated\fR in favor of setting a \fBmenu\fR directly as a menubar; see the \fBtoplevel\fR's \fB\-menu\fR option for how to do that. .PP There are several interactions between menubuttons and menus; see the \fBmenu\fR manual entry for information on various menu configurations, such as pulldown menus and option menus. .SH "WIDGET COMMAND" .PP The \fBmenubutton\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for menubutton widgets: .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR command. .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for menubuttons that give them the following default behavior: .IP [1] A menubutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves it. .IP [2] Pressing mouse button 1 over a menubutton posts the menubutton: its relief changes to raised and its associated menu is posted under the menubutton. If the mouse is dragged down into the menu with the button still down, and if the mouse button is then released over an entry in the menu, the menubutton is unposted and the menu entry is invoked. .IP [3] If button 1 is pressed over a menubutton and then released over that menubutton, the menubutton stays posted: you can still move the mouse over the menu and click button 1 on an entry to invoke it. Once a menu entry has been invoked, the menubutton unposts itself. .IP [4] If button 1 is pressed over a menubutton and then dragged over some other menubutton, the original menubutton unposts itself and the new menubutton posts. .IP [5] If button 1 is pressed over a menubutton and released outside any menubutton or menu, the menubutton unposts without invoking any menu entry. .IP [6] When a menubutton is posted, its associated menu claims the input focus to allow keyboard traversal of the menu and its submenus. See the \fBmenu\fR manual entry for details on these bindings. .IP [7] If the \fB\-underline\fR option has been specified for a menubutton then keyboard traversal may be used to post the menubutton: Alt+\fIx\fR, where \fIx\fR is the underlined character (or its lower-case or upper-case equivalent), may be typed in any window under the menubutton's toplevel to post the menubutton. .IP [8] The F10 key may be typed in any window to post the first menubutton under its toplevel window that is not disabled. .IP [9] If a menubutton has the input focus, the space and return keys post the menubutton. .PP If the menubutton's state is \fBdisabled\fR then none of the above actions occur: the menubutton is completely non-responsive. .PP The behavior of menubuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "SEE ALSO" ttk::menubutton(n), menu(n) .SH KEYWORDS menubutton, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/message.n0000644001000000100000000001447615105057705017433 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH message n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME message \- Create and manipulate 'message' non-interactive text widgets .SH SYNOPSIS \fBmessage\fI pathName \fR?\fIoptions\fR? .SO \-anchor \-background \-borderwidth \-cursor \-font \-foreground \-highlightbackground \-highlightcolor \-highlightthickness \-padx \-pady \-relief \-takefocus \-text \-textvariable .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-aspect aspect Aspect Specifies a non-negative integer value indicating desired aspect ratio for the text. The aspect ratio is specified as 100*width/height. 100 means the text should be as wide as it is tall, 200 means the text should be twice as wide as it is tall, 50 means the text should be twice as tall as it is wide, and so on. Used to choose line length for text if \fB\-width\fR option is not specified. Defaults to 150. .OP \-justify justify Justify Specifies how to justify lines of text. Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. Defaults to \fBleft\fR. This option works together with the \fB\-anchor\fR, \fB\-aspect\fR, \fB\-padx\fR, \fB\-pady\fR, and \fB\-width\fR options to provide a variety of arrangements of the text within the window. The \fB\-aspect\fR and \fB\-width\fR options determine the amount of screen space needed to display the text. The \fB\-anchor\fR, \fB\-padx\fR, and \fB\-pady\fR options determine where this rectangular area is displayed within the widget's window, and the \fB\-justify\fR option determines how each line is displayed within that rectangular region. For example, suppose \fB\-anchor\fR is \fBe\fR and \fB\-justify\fR is \fBleft\fR, and that the message window is much larger than needed for the text. The text will be displayed so that the left edges of all the lines line up and the right edge of the longest line is \fB\-padx\fR from the right side of the window; the entire text block will be centered in the vertical span of the window. .OP \-width width Width Specifies the length of lines in the window. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. If this option has a value greater than zero then the \fB\-aspect\fR option is ignored and the \fB\-width\fR option determines the line length. If this option value is negative or zero, then the \fB\-aspect\fR option determines the line length. .BE .SH DESCRIPTION .PP The \fBmessage\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a message widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the message such as its colors, font, text, and initial relief. The \fBmessage\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A message is a widget that displays a textual string. A message widget has three special features that differentiate it from a \fBlabel\fR widget. First, it breaks up its string into lines in order to produce a given aspect ratio for the window. The line breaks are chosen at word boundaries wherever possible (if not even a single word would fit on a line, then the word will be split across lines). Newline characters in the string will force line breaks; they can be used, for example, to leave blank lines in the display. .PP The second feature of a message widget is justification. The text may be displayed left-justified (each line starts at the left side of the window), centered on a line-by-line basis, or right-justified (each line ends at the right side of the window). .PP The third feature of a message widget is that it handles control characters and non-printing characters specially. Tab characters are replaced with enough blank space to line up on the next 8-character boundary. Newlines cause line breaks. Other control characters (ASCII code less than 0x20) and characters not defined in the font are displayed as a four-character sequence \fB\ex\fIhh\fR where \fIhh\fR is the two-digit hexadecimal number corresponding to the character. In the unusual case where the font does not contain all of the characters in .QW 0123456789abcdef\ex then control characters and undefined characters are not displayed at all. .SH "WIDGET COMMAND" .PP The \fBmessage\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for message widgets: .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBmessage\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBmessage\fR command. .SH "DEFAULT BINDINGS" .PP When a new message is created, it has no default event bindings: messages are intended for output purposes only. .SH BUGS .PP Tabs do not work very well with text that is centered or right-justified. The most common result is that the line is justified wrong. .SH "SEE ALSO" label(n) .SH KEYWORDS message, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/messageBox.n0000644001000000100000000000723115105057705020073 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk_messageBox n 4.2 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_messageBox \- pops up a message window and waits for user response. .SH SYNOPSIS \fBtk_messageBox \fR?\fIoption value ...\fR? .BE .SH DESCRIPTION .PP This procedure creates and displays a message window with an application-specified message, an icon and a set of buttons. Each of the buttons in the message window is identified by a unique symbolic name (see the \fB\-type\fR options). After the message window is popped up, \fBtk_messageBox\fR waits for the user to select one of the buttons. Then it returns the symbolic name of the selected button. .PP The following option-value pairs are supported: .\" OPTION: -command .TP \fB\-command\fI string\fR . Specifies the prefix of a Tcl command to invoke when the user closes the dialog. The actual command consists of \fIstring\fR followed by a space and the name of the button clicked by the user to close the dialog. This is only available on macOS. .\" OPTION: -default .TP \fB\-default\fI name\fR . \fIName\fR gives the symbolic name of the default button for this message window ( .QW ok , .QW cancel , and so on). See \fB\-type\fR for a list of the symbolic names. If this option is not specified, the first button in the dialog will be made the default. .\" OPTION: -detail .TP \fB\-detail\fI string\fR . Specifies an auxiliary message to the main message given by the \fB\-message\fR option. The message detail will be presented beneath the main message and, where supported by the OS, in a less emphasized font than the main message. .\" OPTION: -icon .TP \fB\-icon\fI iconImage\fR . Specifies an icon to display. \fIIconImage\fR must be one of the following: \fBerror\fR, \fBinfo\fR, \fBquestion\fR or \fBwarning\fR. If this option is not specified, then the info icon will be displayed. .\" OPTION: -message .TP \fB\-message\fI string\fR . Specifies the message to display in this message box. The default value is an empty string. .\" OPTION: -parent .TP \fB\-parent\fI window\fR . Makes \fIwindow\fR the logical parent of the message box. The message box is displayed on top of its parent window. .\" OPTION: -title .TP \fB\-title\fI titleString\fR . Specifies a string to display as the title of the message box. The default value is an empty string. .\" OPTION: -type .TP \fB\-type\fI predefinedType\fR . Arranges for a predefined set of buttons to be displayed. The following values are possible for \fIpredefinedType\fR: .RS .IP \fBabortretryignore\fR 18 Displays three buttons whose symbolic names are \fBabort\fR, \fBretry\fR and \fBignore\fR. .IP \fBok\fR 18 Displays one button whose symbolic name is \fBok\fR. This is the default. .IP \fBokcancel\fR 18 Displays two buttons whose symbolic names are \fBok\fR and \fBcancel\fR. .IP \fBretrycancel\fR 18 Displays two buttons whose symbolic names are \fBretry\fR and \fBcancel\fR. .IP \fByesno\fR 18 Displays two buttons whose symbolic names are \fByes\fR and \fBno\fR. .IP \fByesnocancel\fR 18 Displays three buttons whose symbolic names are \fByes\fR, \fBno\fR and \fBcancel\fR. .RE .PP .SH EXAMPLE .PP .CS set answer [\fBtk_messageBox\fR -message "Really quit?" \e -icon question -type yesno \e -detail "Select \e"Yes\e" to make the application exit"] switch -- $answer { yes exit no {\fBtk_messageBox\fR -message "I know you like this application!" \e -type ok} } .CE .SH KEYWORDS message box '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/MoveToplev.30000644001000000100000000000412115105057705017776 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1993 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_MoveToplevelWindow 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_MoveToplevelWindow \- Adjust the position of a top-level window .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_MoveToplevelWindow\fR(\fItkwin, x, y\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in Token for top-level window to move. .AP int x in New x-coordinate for the top-left pixel of \fItkwin\fR's border, or the top-left pixel of the decorative border supplied for \fItkwin\fR by the window manager, if there is one. .AP int y in New y-coordinate for the top-left pixel of \fItkwin\fR's border, or the top-left pixel of the decorative border supplied for \fItkwin\fR by the window manager, if there is one. .BE .SH DESCRIPTION .PP In general, a window should never set its own position; this should be done only by the geometry manger that is responsible for the window. For top-level windows the window manager is effectively the geometry manager; Tk provides interface code between the application and the window manager to convey the application's desires to the geometry manager. The desired size for a top-level window is conveyed using the usual \fBTk_GeometryRequest\fR mechanism. The procedure \fBTk_MoveToplevelWindow\fR may be used by an application to request a particular position for a top-level window; this procedure is similar in function to the \fBwm geometry\fR Tcl command except that negative offsets cannot be specified. It is invoked by widgets such as menus that want to appear at a particular place on the screen. .PP When \fBTk_MoveToplevelWindow\fR is called it does not immediately pass on the new desired location to the window manager; it defers this action until all other outstanding work has been completed, using the \fBTcl_DoWhenIdle\fR mechanism. .SH KEYWORDS position, top-level window, window manager tk9.0.3/doc/Name.30000644001000000100000000000615115105057705016563 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_Name 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_Name, Tk_PathName, Tk_NameToWindow \- convert between names and window tokens .SH SYNOPSIS .nf \fB#include \fR .sp Tk_Uid \fBTk_Name\fR(\fItkwin\fR) .sp char * \fBTk_PathName\fR(\fItkwin\fR) .sp Tk_Window \fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR) .fi .SH ARGUMENTS .AS Tcl_Interp *pathName .AP Tk_Window tkwin in Token for window. .AP Tcl_Interp *interp out Interpreter to use for error reporting (can be NULL). .AP "const char" *pathName in Character string containing path name of window. .BE .SH DESCRIPTION .PP Each window managed by Tk has two names, a short name that identifies a window among children of the same parent, and a path name that identifies the window uniquely among all the windows belonging to the same main window. The path name is used more often in Tk than the short name; many commands, like \fBbind\fR, expect path names as arguments. .PP The \fBTk_Name\fR macro returns a window's short name, which is the same as the \fIname\fR argument passed to \fBTk_CreateWindow\fR when the window was created. The value is returned as a Tk_Uid, which may be used just like a string pointer but also has the properties of a unique identifier (see the manual entry for \fBTk_GetUid\fR for details). .PP The \fBTk_PathName\fR macro returns a hierarchical name for \fItkwin\fR. Path names have a structure similar to file names in Unix but with dots between elements instead of slashes: the main window for an application has the path name .QW . ; its children have names like .QW .a and .QW .b ; their children have names like .QW .a.aa and .QW .b.bb ; and so on. A window is considered to be a child of another window for naming purposes if the second window was named as the first window's \fIparent\fR when the first window was created. This is not always the same as the X window hierarchy. For example, a pop-up is created as a child of the root window, but its logical parent will usually be a window within the application. .PP The procedure \fBTk_NameToWindow\fR returns the token for a window given its path name (the \fIpathName\fR argument) and another window belonging to the same main window (\fItkwin\fR). It normally returns a token for the named window, but if no such window exists \fBTk_NameToWindow\fR leaves an error message in interpreter \fIinterp\fR's result and returns NULL. The \fItkwin\fR argument to \fBTk_NameToWindow\fR is needed because path names are only unique within a single application hierarchy. If, for example, a single process has opened two main windows, each will have a separate naming hierarchy and the same path name might appear in each of the hierarchies. Normally \fItkwin\fR is the main window of the desired hierarchy, but this need not be the case: any window in the desired hierarchy may be used. .SH KEYWORDS name, path name, token, window tk9.0.3/doc/NameOfImg.30000644001000000100000000000144515105057705017506 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_NameOfImage 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_NameOfImage \- Return name of image. .SH SYNOPSIS .nf \fB#include \fR .sp const char * \fBTk_NameOfImage\fR(\fIimageModel\fR) .fi .SH ARGUMENTS .AS Tk_ImageModel imageModel .AP Tk_ImageModel imageModel in Token for image, which was passed to image manager's \fIcreateProc\fR when the image was created. .BE .SH DESCRIPTION .PP This procedure is invoked by image managers to find out the name of an image. Given the token for the image, it returns the string name for the image. .SH KEYWORDS image manager, image name tk9.0.3/doc/nsimage.n0000644001000000100000000001136715105057705017426 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2022 Marc Culler '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH nsimage n 9.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME nsimage \- A Tk image type for macOS based on the NSImage class. .BE .SH DESCRIPTION The nsimage is implemented as a Tk image type. The \fBimage\fR command is used to create, delete, and query all images, including images of type \fBnsimage\fR. The options that are available are specific to the nsimage type and are described below. .PP The command to create an \fBnsimage\fR: .TP \fBimage create nsimage \fR?\fIname\fR? ?\fIoption value ...\fR? .PP creates a new nsimage and a command with the same name and returns its name. .SH OPTIONS .PP Valid \fIoptions\fR are: .\" OPTION: -source .TP \fB\-source\fI string\fR .PP The value of the \fB\-source\fR option is a string describing an NSimage. There are several ways to interpret this string, and the interpretation is determined by the value of the \fB\-as\fR option. This option is required. .PP .\" OPTION: -as .TP \fB\-as\fI type\fR .PP There are four possible values for the \fB\-as\fR option which specify how the source string should be interpreted. The allowed values and their meanings are: .RS .IP \fBname\fR The source should be interpreted as the name of a named NSImage provided by the system. This is the default if the \fB\-as\fR option is not specified. .IP \fBfile\fR The source should be interpreted as a path to an image file in one of the formats understood by the NSImage class. .IP \fBpath\fR The source should be interpreted as a path to an arbitrary file. The type of the file will be examined and the resulting image will be the system icon for files of that type. .IP \fBfiletype\fR The source is interpreted as a string identifying a particular file type. It may be a filename extension, an Apple Uniform Type Identifier or a 4-character OSType value as used in the HFS filesystem. .RE .\" OPTION: -width .TP \fB\-width\fI pixels\fR .PP The value of the \fIwidth\fR option is an integer specifying the width in pixels of the nsimage. If the width is not specified it will be computed from the height so as to preserve the aspect ration. If neither width nor height are specified then the width and height of the underlying NSImage will be used. .\" OPTION: -height .TP \fB\-height\fI pixels\fR .PP The value of the \fIheight\fR option is an integer specifying the height in pixels of the nsimage. If the height is not specified it will be computed from the height so as to preserve the aspect ration. If neither width nor height are specified then the width and height of the underlying NSImage will be used. .\" OPTION: -radius .TP \fB\-radius\fI pixels\fR .PP The value of the \fIradius\fR option is an integer. If non-zero the image will be clipped to a rounded rectangle with the same width and height as the image, but with circular arcs of the specified radius cutting off the corners of the rectangle. .\" OPTION: -ring .TP \fB\-ring\fI pixels\fR .PP The value of the \fIring\fR option is an integer. If non-zero then it specifies the thickness of a focus ring which will be drawn around the image using the control accent color specified in the System Preferences. The image is resized to reduce its width and height by twice the thickness of the ring. Note that this may create a small amount of distortion. The aspect ration of a non-square image will change slightly. .\" OPTION: -alpha .TP \fB\-alpha\fI float\fR .PP The value of the \fIalpha\fR option should be a floating point number between 0.0 and 1.0. This alpha value will be applied to each pixel of the nsimage, producing a partially transparent image. The default value is 1.0, which makes the image opaque. .\" OPTION: -pressed .TP \fB\-pressed\fI boolean\fR .PP The \fIpressed\fR option takes a boolean value. If the value is true or 1 then the image will be algorithmically modified to become darker in light mode or lighter in dark mode. The default is false. For an image button, the primary image should use the value false while the pressed image should be the same image but with the \fIpressed\fR option set to true. .\" OPTION: -template .TP \fB\-template\fI boolean\fR .PP The \fItemplate\fR option takes a boolean value. If the value is true or 1 then the image will be marked as being a template image. This means that the system will algorithmically convert the image to a light colored image when in dark mode. For the algorithm to work correctly the image must consist only of black pixels with alpha values. .SH "SEE ALSO" image(n), options(n), photo(n) .SH KEYWORDS height, image, types of images, width '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/option.n0000644001000000100000000001337515105057705017314 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH option n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME option \- Add/retrieve window options to/from the option database .SH SYNOPSIS .nf \fBoption add \fIpattern value \fR?\fIpriority\fR? \fBoption clear\fR \fBoption get \fIwindow name class\fR \fBoption readfile \fIfileName \fR?\fIpriority\fR? .fi .BE .SH DESCRIPTION .PP The \fBoption\fR command allows you to add entries to the Tk option database or to retrieve options from the database. .\" METHOD: add The \fBadd\fR form of the command adds a new option to the database. \fIPattern\fR contains the option being specified, and consists of names and/or classes separated by asterisks or dots, in the usual X format (see \fBPATTERN FORMAT\fR). \fIValue\fR contains a text string to associate with \fIpattern\fR; this is the value that will be returned in calls to \fBTk_GetOption\fR or by invocations of the \fBoption get\fR command. If \fIpriority\fR is specified, it indicates the priority level for this option (see below for legal values); it defaults to \fBinteractive\fR. This command always returns an empty string. .PP .\" METHOD: clear The \fBoption clear\fR command clears the option database. Default options (from the \fBRESOURCE_MANAGER\fR property or the \fB.Xdefaults\fR file) will be reloaded automatically the next time an option is added to the database or removed from it. This command always returns an empty string. .PP .\" METHOD: get The \fBoption get\fR command returns the value of the option specified for \fIwindow\fR under \fIname\fR and \fIclass\fR. If several entries in the option database match \fIwindow\fR, \fIname\fR, and \fIclass\fR, then the command returns whichever was created with highest \fIpriority\fR level. If there are several matching entries at the same priority level, then it returns whichever entry was most recently entered into the option database. If there are no matching entries, then the empty string is returned. .PP .\" METHOD: readfile The \fBreadfile\fR form of the command reads \fIfileName\fR, which should have the standard format for an X resource database such as \fB.Xdefaults\fR, and adds all the options specified in that file to the option database. If \fIpriority\fR is specified, it indicates the priority level at which to enter the options; \fIpriority\fR defaults to \fBinteractive\fR. .PP The file is read through a channel which is in "utf-8" encoding, invalid byte sequences are automatically converted to valid ones. This means that encodings like ISO 8859-1 or cp1252 with high probability will work as well, but this cannot be guaranteed. This cannot be changed, setting the [encoding system] has no effect. .PP The \fIpriority\fR arguments to the \fBoption\fR command are normally specified symbolically using one of the following values: .IP \fBwidgetDefault\fR3 Level 20. Used for default values hard-coded into widgets. .IP \fBstartupFile\fR Level 40. Used for options specified in application-specific startup files. .IP \fBuserDefault\fR Level 60. Used for options specified in user-specific defaults files, such as \fB.Xdefaults\fR, resource databases loaded into the X server, or user-specific startup files. .IP \fBinteractive\fR Level 80. Used for options specified interactively after the application starts running. If \fIpriority\fR is not specified, it defaults to this level. .PP Any of the above keywords may be abbreviated. In addition, priorities may be specified numerically using integers between 0 and 100, inclusive. The numeric form is probably a bad idea except for new priority levels other than the ones given above. .SH "PATTERN FORMAT" .PP Patterns consist of a sequence of words separated by either periods, .QW . , or asterisks .QW * . The overall pattern may also be optionally preceded by an asterisk. .PP Each word in the pattern conventionally starts with either an upper-case letter (in which case it denotes the class of either a widget or an option) or any other character, when it denotes the name of a widget or option. The last word in the pattern always indicates the option; the preceding ones constrain which widgets that option will be looked for in. .PP When two words are separated by a period, the latter widget must be a direct child of the former (or the option must apply to only the indicated widgets). When two words are separated by an asterisk, any depth of widgets may lie between the former and latter widgets (and the option applies to all widgets that are children of the former widget). .PP If the overall pattern is preceded by an asterisk, then the overall pattern applies anywhere it can throughout the whole widget hierarchy. Otherwise the first word of the pattern is matched against the name and class of the .QW \fB.\fR \fBtoplevel\fR, which are usually set by options to \fBwish\fR. .SH EXAMPLES .PP Instruct every button in the application to have red text on it unless explicitly overridden, by setting the \fBforeground\fR for the \fBButton\fR class (note that on some platforms the option is ignored): .CS \fBoption add\fR *Button.foreground red startupFile .CE .PP Allow users to control what happens in an entry widget when the Return key is pressed by specifying a script in the option database and add a default option for that which rings the bell: .CS entry .e bind .e [\fBoption get\fR .e returnCommand Command] \fBoption add\fR *.e.returnCommand bell widgetDefault .CE .SH "SEE ALSO" options(n), wish(1) .SH KEYWORDS database, option, priority, retrieve '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/optionMenu.n0000644001000000100000000000303115076161060020122 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk_optionMenu n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_optionMenu \- Create an option menubutton and its menu .SH SYNOPSIS \fBtk_optionMenu \fIpathName varName value \fR?\fIvalue value ...\fR? .BE .SH DESCRIPTION .PP This procedure creates an option menubutton whose name is \fIpathName\fR, plus an associated menu. Together they allow the user to select one of the values given by the \fIvalue\fR arguments. The current value will be stored in the global variable whose name is given by \fIvarName\fR and it will also be displayed as the label in the option menubutton. The user can click on the menubutton to display a menu containing all of the \fIvalue\fRs and thereby select a new value. Once a new value is selected, it will be stored in the variable and appear in the option menubutton. The current value can also be changed by setting the variable. .PP The return value from \fBtk_optionMenu\fR is the name of the menu associated with \fIpathName\fR, so that the caller can change its configuration options or manipulate it in other ways. .SH EXAMPLE .PP .CS tk_optionMenu .foo myVar Foo Bar Boo Spong Wibble pack .foo .CE .SH KEYWORDS option menu '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/options.n0000644001000000100000000004516015105057705017474 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH options n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME options \- Standard options supported by widgets .BE .SH DESCRIPTION .PP This manual entry describes the common configuration options supported by widgets in the Tk toolkit. Every widget does not necessarily support every option (see the manual entries for individual widgets for a list of the standard options supported by that widget), but if a widget does support an option with one of the names listed below, then the option has exactly the effect described below. .PP In the descriptions below, .QW "Command-Line Name" refers to the switch used in class commands and \fBconfigure\fR widget commands to set this value. For example, if an option's command-line switch is \fB\-foreground\fR and there exists a widget \fB.a.b.c\fR, then the command .CS \&\fB.a.b.c\0\0configure\0\0\-foreground black\fR .CE may be used to specify the value \fBblack\fR for the option in the widget \fB.a.b.c\fR. Command-line switches may be abbreviated, as long as the abbreviation is unambiguous. .QW "Database Name" refers to the option's name in the option database (e.g. in .Xdefaults files). .QW "Database Class" refers to the option's class value in the option database. .OP \-activebackground activeBackground Foreground Specifies background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. If strict Motif compliance has been requested by setting the \fBtk_strictMotif\fR variable, this option will normally be ignored; the normal background color will be used instead. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. .OP \-activeborderwidth activeBorderWidth BorderWidth Specifies a non-negative value indicating the width of the 3-D border drawn around active elements. See above for definition of active elements. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. This option is typically only available in widgets displaying more than one element at a time (e.g. menus but not buttons). .OP \-activeforeground activeForeground Background Specifies foreground color to use when drawing active elements. See above for definition of active elements. .OP \-activerelief activeRelief Relief Specifies the 3-D effect desired for the active item of the widget. See the \fB\-relief\fR option for details. .OP \-anchor anchor Anchor Specifies how the information in a widget (e.g. text or a bitmap) is to be displayed in the widget. Must be one of the values \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. For example, \fBnw\fR means display the information such that its top-left corner is at the top-left corner of the widget. .OP "\-background or \-bg" background Background Specifies the normal background color to use when displaying the widget. .OP \-bitmap bitmap Bitmap Specifies a bitmap to display in the widget, in any of the forms acceptable to \fBTk_GetBitmap\fR. The exact way in which the bitmap is displayed may be affected by other options such as \fB\-anchor\fR or \fB\-justify\fR. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget but this is controlled by the \fB\-compound\fR option; the \fB\-bitmap\fR option may be reset to an empty string to re-enable a text display. In widgets that support both \fB\-bitmap\fR and \fB\-image\fR options, \fB\-image\fR will usually override \fB\-bitmap\fR. .OP "\-borderwidth or \-bd" borderWidth BorderWidth Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the \fB\-relief\fR option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. .OP \-cursor cursor Cursor Specifies the mouse cursor to be used for the widget. The value may have any of the forms acceptable to \fBTk_GetCursor\fR. In addition, if an empty string is specified, it indicates that the widget should defer to its parent for cursor specification. .OP \-compound compound Compound Specifies if the widget should display text and bitmaps/images at the same time, and if so, where the bitmap/image should be placed relative to the text. Must be one of the values \fBnone\fR, \fBbottom\fR, \fBtop\fR, \fBleft\fR, \fBright\fR, or \fBcenter\fR. For example, the (default) value \fBnone\fR specifies that the bitmap or image should (if defined) be displayed instead of the text, the value \fBleft\fR specifies that the bitmap or image should be displayed to the left of the text, and the value \fBcenter\fR specifies that the bitmap or image should be displayed on top of the text. .OP \-disabledforeground disabledForeground DisabledForeground Specifies foreground color to use when drawing a disabled element. If the option is specified as an empty string (which is typically the case on monochrome displays), disabled elements are drawn with the normal foreground color but they are dimmed by drawing them with a stippled fill pattern. .OP \-exportselection exportSelection ExportSelection Specifies whether or not a selection in the widget should also be the X selection. The value may have any of the forms accepted by \fBTcl_GetBoolean\fR, such as \fBtrue\fR, \fBfalse\fR, \fB0\fR, \fB1\fR, \fByes\fR, or \fBno\fR. If the selection is exported, then selecting in the widget deselects the current X selection, selecting outside the widget deselects any widget selection, and the widget will respond to selection retrieval requests when it has a selection. The default is usually for widgets to export selections. .OP \-font font Font Specifies the font to use when drawing text inside the widget. The value may have any of the forms described in the \fBfont\fR manual page under \fBFONT DESCRIPTION\fR. .OP "\-foreground or \-fg" foreground Foreground Specifies the normal foreground color to use when displaying the widget. .OP \-highlightbackground highlightBackground HighlightBackground Specifies the color to display in the traversal highlight region when the widget does not have the input focus. .OP \-highlightcolor highlightColor HighlightColor Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. .OP \-highlightthickness highlightThickness HighlightThickness Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. If the value is zero, no focus highlight is drawn around the widget. .OP \-image image Image Specifies an image to display in the widget, which must have been created with the \fBimage create\fR command. Typically, if the \fB\-image\fR option is specified then it overrides other options that specify a bitmap or textual value to display in the widget, though this is controlled by the \fB\-compound\fR option; the \fB\-image\fR option may be reset to an empty string to re-enable a bitmap or text display. .OP \-insertbackground insertBackground Foreground Specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection). .OP \-insertborderwidth insertBorderWidth BorderWidth Specifies a non-negative value indicating the width of the 3-D border to draw around the insertion cursor. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. .OP \-insertofftime insertOffTime OffTime Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain .QW off in each blink cycle. If this option is zero then the cursor does not blink: it is on all the time. .OP \-insertontime insertOnTime OnTime Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain .QW on in each blink cycle. .OP \-insertwidth insertWidth InsertWidth Specifies a non-negative value indicating the total width of the insertion cursor. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. If a border has been specified for the insertion cursor (using the \fB\-insertborderwidth\fR option), the border will be drawn inside the width specified by the \fB\-insertwidth\fR option. .OP \-jump jump Jump For widgets with a slider that can be dragged to adjust a value, such as scrollbars, this option determines when notifications are made about changes in the value. The option's value must be a boolean of the form accepted by \fBTcl_GetBoolean\fR. If the value is false, updates are made continuously as the slider is dragged. If the value is true, updates are delayed until the mouse button is released to end the drag; at that point a single notification is made (the value .QW jumps rather than changing smoothly). .OP \-justify justify Justify When there are multiple lines of text displayed in a widget, this option determines how the lines line up with each other. Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. \fBLeft\fR means that the lines' left edges all line up, \fBcenter\fR means that the lines' centers are aligned, and \fBright\fR means that the lines' right edges line up. .OP \-orient orient Orient For widgets that can lay themselves out with either a horizontal or vertical orientation, such as scrollbars, this option specifies which orientation should be used. Must be either \fBhorizontal\fR or \fBvertical\fR or an abbreviation of one of these. .OP \-padx padX Pad Specifies a non-negative value indicating how much extra space to request for the widget in the X-direction. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. When computing how large a window it needs, the widget will add this amount to the width it would normally need (as determined by the width of the things displayed in the widget); if the geometry manager can satisfy this request, the widget will end up with extra internal space to the left and/or right of what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options. .OP \-pady padY Pad Specifies a non-negative value indicating how much extra space to request for the widget in the Y-direction. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. When computing how large a window it needs, the widget will add this amount to the height it would normally need (as determined by the height of the things displayed in the widget); if the geometry manager can satisfy this request, the widget will end up with extra internal space above and/or below what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options. .OP \-placeholder placeHolder PlaceHolder Specifies a help text string to display if no text is otherwise displayed, that is when the widget is empty. The placeholder text is displayed using the values of the \fB\-font\fR and \fB\-justify\fR options. .OP \-placeholderforeground placeholderForeground PlaceholderForeground Specifies the foreground color to use when the placeholder text is displayed. The default color is platform-specific. .OP \-relief relief Relief Specifies the 3-D effect desired for the widget. Acceptable values are \fBraised\fR, \fBsunken\fR, \fBflat\fR, \fBridge\fR, \fBsolid\fR, and \fBgroove\fR. The value indicates how the interior of the widget should appear relative to its exterior; for example, \fBraised\fR means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget. .OP \-repeatdelay repeatDelay RepeatDelay Specifies the number of milliseconds a button or key must be held down before it begins to auto-repeat. Used, for example, on the up- and down-arrows in scrollbars. .OP \-repeatinterval repeatInterval RepeatInterval Used in conjunction with \fB\-repeatdelay\fR: once auto-repeat begins, this option determines the number of milliseconds between auto-repeats. .OP \-selectbackground selectBackground Foreground Specifies the background color to use when displaying selected items. .OP \-selectborderwidth selectBorderWidth BorderWidth Specifies a non-negative value indicating the width of the 3-D border to draw around selected items. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. .OP \-selectforeground selectForeground Background Specifies the foreground color to use when displaying selected items. .OP \-setgrid setGrid SetGrid Specifies a boolean value that determines whether this widget controls the resizing grid for its top-level window. This option is typically used in text widgets, where the information in the widget has a natural size (the size of a character) and it makes sense for the window's dimensions to be integral numbers of these units. These natural window sizes form a grid. If the \fB\-setgrid\fR option is set to true then the widget will communicate with the window manager so that when the user interactively resizes the top-level window that contains the widget, the dimensions of the window will be displayed to the user in grid units and the window size will be constrained to integral numbers of grid units. See the section \fBGRIDDED GEOMETRY MANAGEMENT\fR in the \fBwm\fR manual entry for more details. .OP \-takefocus takeFocus TakeFocus Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal scripts consult the value of the \fB\-takefocus\fR option. A value of \fB0\fR means that the window should be skipped entirely during keyboard traversal. \fB1\fR means that the window should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). An empty value for the option means that the traversal scripts make the decision about whether or not to focus on the window: the current algorithm is to skip the window if it is disabled, if it has no key bindings, or if it is not viewable. If the value has any other form, then the traversal scripts take the value, append the name of the window to it (with a separator space), and evaluate the resulting string as a Tcl script. The script must return \fB0\fR, \fB1\fR, or an empty string: a \fB0\fR or \fB1\fR value specifies whether the window will receive the input focus, and an empty string results in the default decision described above. Note that this interpretation of the option is defined entirely by the Tcl scripts that implement traversal: the widget implementations ignore the option entirely, so you can change its meaning if you redefine the keyboard traversal scripts. .OP \-text text Text Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as \fB\-anchor\fR or \fB\-justify\fR. .OP \-textvariable textVariable Variable Specifies the name of a global variable. The value of the variable is a text string to be displayed inside the widget; if the variable value changes then the widget will automatically update itself to reflect the new value. The way in which the string is displayed in the widget depends on the particular widget and may be determined by other options, such as \fB\-anchor\fR or \fB\-justify\fR. .OP \-troughcolor troughColor Background Specifies the color to use for the rectangular trough areas in widgets such as scrollbars and scales. This option is ignored for scrollbars on Windows (native widget does not recognize this option). .OP \-underline underline Underline Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on. \fBend\fR corresponds to the last character, \fBend\fR-1 to the before last character, and so on. .OP \-wraplength wrapLength WrapLength For widgets that can perform word-wrapping, this option specifies the maximum line length. Lines that would exceed this length are wrapped onto the next line, so that no line is longer than the specified length. The value may be specified in any of the standard forms for screen distances. If this value is negative or zero then no wrapping is done: lines will break only at newline characters in the text. .OP \-xscrollcommand xScrollCommand ScrollCommand Specifies the prefix for a command used to communicate with horizontal scrollbars. When the view in the widget's window changes (or whenever anything else occurs that could change the display in a scrollbar, such as a change in the total size of the widget's contents), the widget will generate a Tcl command by concatenating the scroll command and two numbers. Each of the numbers is a fraction between 0 and 1, which indicates a position in the document. 0 indicates the beginning of the document, 1 indicates the end, .333 indicates a position one third the way through the document, and so on. The first fraction indicates the first information in the document that is visible in the window, and the second fraction indicates the information just after the last portion that is visible. The command is then passed to the Tcl interpreter for execution. Typically the \fB\-xscrollcommand\fR option consists of the path name of a scrollbar widget followed by .QW set , e.g. .QW ".x.scrollbar set" : this will cause the scrollbar to be updated whenever the view in the window changes. If this option is not specified, then no command will be executed. .OP \-yscrollcommand yScrollCommand ScrollCommand Specifies the prefix for a command used to communicate with vertical scrollbars. This option is treated in the same way as the \fB\-xscrollcommand\fR option, except that it is used for vertical scrollbars and is provided by widgets that support vertical scrolling. See the description of \fB\-xscrollcommand\fR for details on how this option is used. .SH "SEE ALSO" colors, cursors, font .SH KEYWORDS class, name, standard option, switch '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/OwnSelect.30000644001000000100000000000337115105057705017607 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_OwnSelection 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_OwnSelection \- make a window the owner of the primary selection .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_OwnSelection\fR(\fItkwin, selection, proc, clientData\fR) .fi .SH ARGUMENTS .AS Tk_LostSelProc clientData .AP Tk_Window tkwin in Window that is to become new selection owner. .AP Atom selection in The name of the selection to be owned, such as XA_PRIMARY. .AP Tk_LostSelProc *proc in Procedure to invoke when \fItkwin\fR loses selection ownership later. .AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION .PP \fBTk_OwnSelection\fR arranges for \fItkwin\fR to become the new owner of the selection specified by the atom \fIselection\fR. After this call completes, future requests for the selection will be directed to handlers created for \fItkwin\fR using \fBTk_CreateSelHandler\fR. When \fItkwin\fR eventually loses the selection ownership, \fIproc\fR will be invoked so that the window can clean itself up (e.g. by unhighlighting the selection). \fIProc\fR should have arguments and result that match the type \fBTk_LostSelProc\fR: .CS typedef void \fBTk_LostSelProc\fR( void *\fIclientData\fR); .CE The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTk_OwnSelection\fR, and is usually a pointer to a data structure containing application-specific information about \fItkwin\fR. .SH KEYWORDS own, selection owner tk9.0.3/doc/pack.n0000644001000000100000000003012115105057705016706 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH pack n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME pack \- Geometry manager that packs around edges of cavity .SH SYNOPSIS \fBpack \fIoption arg \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBpack\fR command is used to communicate with the packer, a geometry manager that arranges the children of a parent by packing them in order around the edges of the parent. The \fBpack\fR command can have any of several forms, depending on the \fIoption\fR argument: .TP \fBpack \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? . If the first argument to \fBpack\fR is a window name (any value starting with .QW . ), then the command is processed in the same way as \fBpack configure\fR. .\" METHOD: configure .TP \fBpack configure \fIwindow \fR?\fIwindow ...\fR? ?\fIoptions\fR? . The arguments consist of the names of one or more content windows followed by pairs of arguments that specify how to manage the content. See \fBTHE PACKER ALGORITHM\fR below for details on how the options are used by the packer. The following options are supported: .RS .\" OPTION: -after .TP \fB\-after \fIother\fR . \fIOther\fR must the name of another window. Use its container as the container for the content, and insert the content just after \fIother\fR in the packing order. .\" OPTION: -anchor .TP \fB\-anchor \fIanchor\fR . \fIAnchor\fR must be a valid anchor position such as \fBn\fR or \fBsw\fR; it specifies where to position each content in its parcel. Defaults to \fBcenter\fR. .\" OPTION: -before .TP \fB\-before \fIother\fR . \fIOther\fR must the name of another window. Use its container as the container for the content, and insert the content just before \fIother\fR in the packing order. .\" OPTION: -expand .TP \fB\-expand \fIboolean\fR . Specifies whether the content should be expanded to consume extra space in their container. \fIBoolean\fR may have any proper boolean value, such as \fB1\fR or \fBno\fR. Defaults to 0. .\" OPTION: -fill .TP \fB\-fill \fIstyle\fR . If a content's parcel is larger than its requested dimensions, this option may be used to stretch the content. \fIStyle\fR must have one of the following values: .RS .IP \fBnone\fR Give the content its requested dimensions plus any internal padding requested with \fB\-ipadx\fR or \fB\-ipady\fR. This is the default. .IP \fBx\fR Stretch the content horizontally to fill the entire width of its parcel (except leave external padding as specified by \fB\-padx\fR). .IP \fBy\fR Stretch the content vertically to fill the entire height of its parcel (except leave external padding as specified by \fB\-pady\fR). .IP \fBboth\fR Stretch the content both horizontally and vertically. .RE .\" OPTION: -in .TP \fB\-in \fIcontainer\fR . Insert the window at the end of the packing order for the container window given by \fIcontainer\fR. .\" OPTION: -ipadx .TP \fB\-ipadx \fIamount\fR . \fIAmount\fR specifies how much horizontal internal padding to leave on each side of the content. \fIAmount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. It defaults to 0. .\" OPTION: -ipady .TP \fB\-ipady \fIamount\fR . \fIAmount\fR specifies how much vertical internal padding to leave on each side of the content. \fIAmount\fR defaults to 0. .\" OPTION: -padx .TP \fB\-padx \fIamount\fR . \fIAmount\fR specifies how much horizontal external padding to leave on each side of the content. \fIAmount\fR may be a list of two values to specify padding for left and right separately. \fIAmount\fR defaults to 0. .\" OPTION: -pady .TP \fB\-pady \fIamount\fR . \fIAmount\fR specifies how much vertical external padding to leave on each side of the content. \fIAmount\fR may be a list of two values to specify padding for top and bottom separately. \fIAmount\fR defaults to 0. .\" OPTION: -side .TP \fB\-side \fIside\fR . Specifies which side of the container the content will be packed against. Must be \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. Defaults to \fBtop\fR. .LP If no \fB\-in\fR, \fB\-after\fR or \fB\-before\fR option is specified then each of the content will be inserted at the end of the packing list for its parent unless it is already managed by the packer (in which case it will be left where it is). If one of these options is specified then all the content will be inserted at the specified point. If any of the content are already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values. .RE .\" METHOD: content .TP \fBpack content \fIwindow\fR . Returns a list of all of the content windows in the packing order for \fIwindow\fR. The order of the content windows in the list is the same as their order in the packing order. If \fIwindow\fR has no content then an empty string is returned. .\" METHOD: forget .TP \fBpack forget \fIwindow \fR?\fIwindow ...\fR? . Removes each of the \fIwindow\fRs from the packing order for its container and unmaps their windows. The content will no longer be managed by the packer. .RS .PP .VS "TIP 518" If the last content window of the container becomes unmanaged, this will also send the virtual event \fB<>\fR to the container; the container may choose to resize itself (or otherwise respond) to such a change. .VE "TIP 518" .RE .\" METHOD: info .TP \fBpack info \fIwindow\fR . Returns a list whose elements are the current configuration state of the window given by \fIwindow\fR in the same option-value form that might be specified to \fBpack configure\fR. The first two elements of the list are .QW "\fB\-in \fIcontainer\fR" where \fIcontainer\fR is the window's container. .\" METHOD: propagate .TP \fBpack propagate \fIcontainer\fR ?\fIboolean\fR? . If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR then propagation is enabled for \fIcontainer\fR, which must be a window name (see \fBGEOMETRY PROPAGATION\fR below). If \fIboolean\fR has a false boolean value then propagation is disabled for \fIcontainer\fR. In either of these cases an empty string is returned. If \fIboolean\fR is omitted then the command returns \fB0\fR or \fB1\fR to indicate whether propagation is currently enabled for \fIcontainer\fR. Propagation is enabled by default. .\" METHOD: slaves .TP \fBpack slaves \fIwindow\fR . Synonym for \fBpack content \fIwindow\fR. .SH "THE PACKER ALGORITHM" .PP For each container the packer maintains an ordered list of content windows called the \fIpacking list\fR. The \fB\-in\fR, \fB\-after\fR, and \fB\-before\fR configuration options are used to specify the container for each content and the content's position in the packing list. If none of these options is given for a content then the content is added to the end of the packing list for its parent. .PP The packer arranges the content windows for a container by scanning the packing list in order. At the time it processes each content, a rectangular area within the container is still unallocated. This area is called the \fIcavity\fR; for the first content it is the entire area of the container. .PP For each content the packer carries out the following steps: .IP [1] The packer allocates a rectangular \fIparcel\fR for the content along the side of the cavity given by the content's \fB\-side\fR option. If the side is top or bottom then the width of the parcel is the width of the cavity and its height is the requested height of the content plus the \fB\-ipady\fR and \fB\-pady\fR options. For the left or right side the height of the parcel is the height of the cavity and the width is the requested width of the content plus the \fB\-ipadx\fR and \fB\-padx\fR options. The parcel may be enlarged further because of the \fB\-expand\fR option (see \fBEXPANSION\fR below) .IP [2] The packer chooses the dimensions of the content. The width will normally be the content's requested width plus twice its \fB\-ipadx\fR option and the height will normally be the content's requested height plus twice its \fB\-ipady\fR option. However, if the \fB\-fill\fR option is \fBx\fR or \fBboth\fR then the width of the content is expanded to fill the width of the parcel, minus twice the \fB\-padx\fR option. If the \fB\-fill\fR option is \fBy\fR or \fBboth\fR then the height of the content is expanded to fill the width of the parcel, minus twice the \fB\-pady\fR option. .IP [3] The packer positions the content over its parcel. If the content is smaller than the parcel then the \fB\-anchor\fR option determines where in the parcel the content will be placed. If \fB\-padx\fR or \fB\-pady\fR is non-zero, then the given amount of external padding will always be left between the content and the edges of the parcel. .PP Once a given content has been packed, the area of its parcel is subtracted from the cavity, leaving a smaller rectangular cavity for the next content. If a content does not use all of its parcel, the unused space in the parcel will not be used by subsequent content. If the cavity should become too small to meet the needs of a content then the content will be given whatever space is left in the cavity. If the cavity shrinks to zero size, then all remaining content on the packing list will be unmapped from the screen until the container window becomes large enough to hold them again. .SS "EXPANSION" .PP If a container window is so large that there will be extra space left over after all of its content have been packed, then the extra space is distributed uniformly among all of the content for which the \fB\-expand\fR option is set. Extra horizontal space is distributed among the expandable content whose \fB\-side\fR is \fBleft\fR or \fBright\fR, and extra vertical space is distributed among the expandable content whose \fB\-side\fR is \fBtop\fR or \fBbottom\fR. .SS "GEOMETRY PROPAGATION" .PP The packer normally computes how large a container must be to just exactly meet the needs of its content, and it sets the requested width and height of the container to these dimensions. This causes geometry information to propagate up through a window hierarchy to a top-level window so that the entire sub-tree sizes itself to fit the needs of the leaf windows. However, the \fBpack propagate\fR command may be used to turn off propagation for one or more containers. If propagation is disabled then the packer will not set the requested width and height of the packer. This may be useful if, for example, you wish for a container window to have a fixed size that you specify. .SH "RESTRICTIONS ON CONTAINER WINDOWS" .PP The container for each content must either be the content's parent (the default) or a descendant of the content's parent. This restriction is necessary to guarantee that the content can be placed over any part of its container that is visible without danger of the content being clipped by its parent. .SH "PACKING ORDER" .PP If the container for a content is not its parent then you must make sure that the content is higher in the stacking order than the container. Otherwise the container will obscure the content and it will appear as if the content has not been packed correctly. The easiest way to make sure the content is higher than the container is to create the container window first: the most recently created window will be highest in the stacking order. Or, you can use the \fBraise\fR and \fBlower\fR commands to change the stacking order of either the container or the content. .SH EXAMPLE .PP .CS # Make the widgets label .t -text "This widget is at the top" -bg red label .b -text "This widget is at the bottom" -bg green label .l -text "Left\enHand\enSide" label .r -text "Right\enHand\enSide" text .mid \&.mid insert end "This layout is like Java's BorderLayout" # Lay them out \fBpack\fR .t -side top -fill x \fBpack\fR .b -side bottom -fill x \fBpack\fR .l -side left -fill y \fBpack\fR .r -side right -fill y \fBpack\fR .mid -expand 1 -fill both .CE .SH "SEE ALSO" grid(n), place(n) .SH KEYWORDS geometry manager, location, packer, parcel, propagation, size '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/palette.n0000644001000000100000000000615515105057705017440 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk_setPalette n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_setPalette, tk_bisque \- Modify the Tk color palette .SH SYNOPSIS .nf \fBtk_setPalette \fIbackground\fR \fBtk_setPalette \fIname value \fR?\fIname value ...\fR? \fBtk_bisque\fR .fi .BE .SH DESCRIPTION .PP The \fBtk_setPalette\fR procedure changes the color scheme for Tk. It does this by modifying the colors of existing widgets and by changing the option database so that future widgets will use the new color scheme. If \fBtk_setPalette\fR is invoked with a single argument, the argument is the name of a color to use as the normal background color; \fBtk_setPalette\fR will compute a complete color palette from this background color. Alternatively, the arguments to \fBtk_setPalette\fR may consist of any number of \fIname\fR\-\fIvalue\fR pairs, where the first argument of the pair is the name of an option in the Tk option database and the second argument is the new value to use for that option. The following database names are currently supported: .DS .ta 4c 8c \fBactiveBackground\fR \fBforeground\fR \fBselectColor\fR \fBactiveForeground\fR \fBhighlightBackground\fR \fBselectBackground\fR \fBbackground\fR \fBhighlightColor\fR \fBselectForeground\fR \fBdisabledForeground\fR \fBinsertBackground\fR \fBtroughColor\fR .DE \fBtk_setPalette\fR tries to compute reasonable defaults for any options that you do not specify. You can specify options other than the above ones and Tk will change those options on widgets as well. This feature may be useful if you are using custom widgets with additional color options. .PP Once it has computed the new value to use for each of the color options, \fBtk_setPalette\fR scans the widget hierarchy to modify the options of all existing widgets. For each widget, it checks to see if any of the above options is defined for the widget. If so, and if the option's current value is the default, then the value is changed; if the option has a value other than the default, \fBtk_setPalette\fR will not change it. The default for an option is the one provided by the widget (\fB[lindex [$w configure $option] 3]\fR) unless \fBtk_setPalette\fR has been run previously, in which case it is the value specified in the previous invocation of \fBtk_setPalette\fR. .PP After modifying all the widgets in the application, \fBtk_setPalette\fR adds options to the option database to change the defaults for widgets created in the future. The new options are added at priority \fBwidgetDefault\fR, so they will be overridden by options from the .Xdefaults file or options specified on the command-line that creates a widget. .PP The procedure \fBtk_bisque\fR is provided for backward compatibility: it restores the application's colors to the light brown .PQ bisque color scheme used in Tk 3.6 and earlier versions. .SH KEYWORDS bisque, color, palette '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/panedwindow.n0000644001000000100000000003416115105057705020317 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH panedwindow n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME panedwindow \- Create and manipulate 'panedwindow' split container widgets .SH SYNOPSIS \fBpanedwindow\fI pathName \fR?\fIoptions\fR? .SO \-background \-borderwidth \-cursor \-orient \-relief .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-handlepad handlePad HandlePad When sash handles are drawn, specifies the distance from the top or left end of the sash (depending on the orientation of the widget) at which to draw the handle. May be any value accepted by \fBTk_GetPixels\fR. .OP \-handlesize handleSize HandleSize Specifies the side length of a sash handle. Handles are always drawn as squares. May be any value accepted by \fBTk_GetPixels\fR. .OP \-height height Height Specifies a desired height for the overall panedwindow widget. May be any value accepted by \fBTk_GetPixels\fR. If an empty string, the widget will be made high enough to allow all contained widgets to have their natural height. .OP \-opaqueresize opaqueResize OpaqueResize Specifies whether panes should be resized as a sash is moved (true), or if resizing should be deferred until the sash is placed (false). In the latter case, a .QW ghost version of the sash is displayed during the resizing to show where the panes will be resized to when releasing the mouse button. This .QW ghost version of the sash is the proxy. It's rendering can be configured using the \fB\-proxybackground\fR, \fB\-proxyborderwidth\fR and \fB\-proxyrelief\fR options. .OP \-proxybackground proxyBackground ProxyBackground Background color to use when drawing the proxy. If an empty string, the value of the \fB\-background\fR option will be used. .OP \-proxyborderwidth proxyBorderWidth ProxyBorderWidth Specifies the borderwidth of the proxy. May be any value accepted by \fBTk_GetPixels\fR. .OP \-proxyrelief proxyRelief ProxyRelief Relief to use when drawing the proxy. May be any of the standard Tk relief values. If an empty string, the value of the \fB\-sashrelief\fR option will be used. .OP \-sashcursor sashCursor SashCursor Mouse cursor to use when over a sash. If null, \fBsb_h_double_arrow\fR will be used for horizontal panedwindows, and \fBsb_v_double_arrow\fR will be used for vertical panedwindows. .OP \-sashpad sashPad SashPad Specifies the amount of padding to leave of each side of a sash. May be any value accepted by \fBTk_GetPixels\fR. .OP \-sashrelief sashRelief SashRelief Relief to use when drawing a sash. May be any of the standard Tk relief values. .OP \-sashwidth sashWidth SashWidth Specifies the width of each sash. May be any value accepted by \fBTk_GetPixels\fR. .OP \-showhandle showHandle ShowHandle Specifies whether sash handles should be shown. May be any valid Tcl boolean value. .OP \-width width Width Specifies a desired width for the overall panedwindow widget. May be any value accepted by \fBTk_GetPixels\fR. If an empty string, the widget will be made wide enough to allow all contained widgets to have their natural width. .BE .SH DESCRIPTION .PP The \fBpanedwindow\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a panedwindow widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the panedwindow such as its default background color and relief. The \fBpanedwindow\fR command returns the path name of the new window. .PP A panedwindow widget contains any number of panes, arranged horizontally or vertically, according to the value of the \fB\-orient\fR option. Each pane contains one widget, and each pair of panes is separated by a moveable (via mouse movements) sash. Moving a sash causes the widgets on either side of the sash to be resized. .SH "WIDGET COMMAND" .PP The \fBpanedwindow\fR command creates a new Tcl command whose name is the same as the path name of the panedwindow's window. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIPathName\fR is the name of the command, which is the same as the panedwindow widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for panedwindow widgets: .\" METHOD: add .TP \fIpathName \fBadd \fIwindow \fR?\fIwindow ...\fR? ?\fIoption value ...\fR? . Add one or more windows to the panedwindow, each in a separate pane. The arguments consist of the names of one or more windows followed by pairs of arguments that specify how to manage the windows. \fIOption\fR may have any of the values accepted by the \fBconfigure\fR subcommand. .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBpanedwindow\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure \fR?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBpanedwindow\fR command. .\" METHOD: forget .TP \fIpathName \fBforget \fIwindow \fR?\fIwindow ...\fR? . Remove the pane containing \fIwindow\fR from the panedwindow. All geometry management options for \fIwindow\fR will be forgotten. .\" METHOD: identify .TP \fIpathName \fBidentify \fIx y\fR . Identify the panedwindow component underneath the point given by \fIx\fR and \fIy\fR, in window coordinates. If the point is over a sash or a sash handle, the result is a two element list containing the index of the sash or handle, and a word indicating whether it is over a sash or a handle, such as {0 sash} or {2 handle}. If the point is over any other part of the panedwindow, the result is an empty list. .\" METHOD: panecget .TP \fIpathName \fBpanecget \fIwindow option\fR . Query a management option for \fIwindow\fR. \fIOption\fR may be any value allowed by the \fBpaneconfigure\fR subcommand. .\" METHOD: paneconfigure .TP \fIpathName \fBpaneconfigure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the management options for \fIwindow\fR. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. The following options are supported: .RS .\" OPTION: -after .TP \fB\-after \fIwindow\fR . Insert the window after the window specified. \fIwindow\fR should be the name of a window already managed by \fIpathName\fR. .\" OPTION: -before .TP \fB\-before \fIwindow\fR . Insert the window before the window specified. \fIwindow\fR should be the name of a window already managed by \fIpathName\fR. .\" OPTION: -height .TP \fB\-height \fIsize\fR . Specify a height for the window. The height will be the outer dimension of the window including its border, if any. If \fIsize\fR is an empty string, or if \fB\-height\fR is not specified, then the height requested internally by the window will be used initially; the height may later be adjusted by the movement of sashes in the panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. .\" OPTION: -hide .TP \fB\-hide \fIboolean\fR . Controls the visibility of a pane. When the \fIboolean\fR is true (according to \fBTcl_GetBoolean\fR) the pane will not be visible, but it will still be maintained in the list of panes. .\" OPTION: -minsize .TP \fB\-minsize \fIn\fR . Specifies that the size of the window cannot be made less than \fIn\fR. This constraint only affects the size of the widget in the paned dimension \(em the x dimension for horizontal panedwindows, the y dimension for vertical panedwindows. May be any value accepted by \fBTk_GetPixels\fR. .\" OPTION: -padx .TP \fB\-padx \fIn\fR . Specifies a non-negative value indicating how much extra space to leave on each side of the window in the X-direction. The value may have any of the forms accepted by \fBTk_GetPixels\fR. .\" OPTION: -pady .TP \fB\-pady \fIn\fR . Specifies a non-negative value indicating how much extra space to leave on each side of the window in the Y-direction. The value may have any of the forms accepted by \fBTk_GetPixels\fR. .\" OPTION: -sticky .TP \fB\-sticky \fIstyle\fR . If a window's pane is larger than the requested dimensions of the window, this option may be used to position (or stretch) the window within its pane. \fIStyle\fR is a string that contains zero or more of the characters \fBn\fR, \fBs\fR, \fBe\fR or \fBw\fR. The string can optionally contains spaces or commas, but they are ignored. Each letter refers to a side (north, south, east, or west) that the window will .QW stick to. If both \fBn\fR and \fBs\fR (or \fBe\fR and \fBw\fR) are specified, the window will be stretched to fill the entire height (or width) of its cavity. .\" OPTION: -stretch .TP \fB\-stretch \fIwhen\fR . Controls how extra space is allocated to each of the panes. \fIWhen\fR is one of \fBalways\fR, \fBfirst\fR, \fBlast\fR, \fBmiddle\fR, and \fBnever\fR. The panedwindow will calculate the required size of all its panes. Any remaining (or deficit) space will be distributed to those panes marked for stretching. The space will be distributed based on each panes current ratio of the whole. The \fIwhen\fR values have the following definition: .RS .IP \fBalways\fR This pane will always stretch. .IP \fBfirst\fR Only if this pane is the first pane (left-most or top-most) will it stretch. .IP \fBlast\fR Only if this pane is the last pane (right-most or bottom-most) will it stretch. This is the default value. .IP \fBmiddle\fR Only if this pane is not the first or last pane will it stretch. .IP \fBnever\fR This pane will never stretch. .RE .\" OPTION: -width .TP \fB\-width \fIsize\fR . Specify a width for the window. The width will be the outer dimension of the window including its border, if any. If \fIsize\fR is an empty string, or if \fB\-width\fR is not specified, then the width requested internally by the window will be used initially; the width may later be adjusted by the movement of sashes in the panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. .RE .\" METHOD: panes .TP \fIpathName \fBpanes\fR . Returns an ordered list of the widgets managed by \fIpathName\fR. .\" METHOD: proxy .TP \fIpathName \fBproxy \fR?\fIargs\fR? . This command is used to query and change the position of the sash proxy, used for rubberband-style pane resizing. It can take any of the following forms: .RS .TP \fIpathName \fBproxy coord\fR . Return a list containing the x and y coordinates of the most recent proxy location. .TP \fIpathName \fBproxy forget\fR . Remove the proxy from the display. .TP \fIpathName \fBproxy place \fIx y\fR . Place the proxy at the given \fIx\fR and \fIy\fR coordinates. .RE .\" METHOD: sash .TP \fIpathName \fBsash \fR?\fIargs\fR? . This command is used to query and change the position of sashes in the panedwindow. It can take any of the following forms: .RS .TP \fIpathName \fBsash coord \fIindex\fR . Return the current x and y coordinate pair for the sash given by \fIindex\fR. \fIIndex\fR must be an integer between 0 and 1 less than the number of panes in the panedwindow. The coordinates given are those of the top left corner of the region containing the sash. .TP \fIpathName \fBsash dragto \fIindex x y\fR . This command computes the difference between the given coordinates and the coordinates given to the last \fBsash mark\fR command for the given sash. It then moves that sash the computed difference. The return value is the empty string. .TP \fIpathName \fBsash mark \fIindex x y\fR . Records \fIx\fR and \fIy\fR for the sash given by \fIindex\fR; used in conjunction with later \fBsash dragto\fR commands to move the sash. .TP \fIpathName \fBsash place \fIindex x y\fR . Place the sash given by \fIindex\fR at the given coordinates. .RE .SH "RESIZING PANES" .PP A pane is resized by grabbing the sash (or sash handle if present) and dragging with the mouse. This is accomplished via mouse motion bindings on the widget. When a sash is moved, the sizes of the panes on each side of the sash, and thus the widgets in those panes, are adjusted. .PP When a pane is resized from outside (e.g. it is packed to expand and fill, and the containing toplevel is resized), space is added to the final (rightmost or bottommost) pane in the window. .PP Unlike child windows managed by e.g. pack or grid, the panes managed by a panedwindow do not change width or height to accommodate changes in the requested widths or heights of the panes, once these have become mapped. Therefore it may be advisable, particularly when creating layouts interactively, to not add a pane to the panedwindow widget until after the geometry requests of that pane has been finalized (i.e., all components of the pane inserted, all options affecting geometry set to their proper values, etc.). .SH "SEE ALSO" ttk::panedwindow(n) .SH KEYWORDS panedwindow, widget, geometry management '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ParseArgv.30000644001000000100000000003430215105057705017574 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_ParseArgv \- process command-line options .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR) .fi .SH ARGUMENTS .AS Tk_ArgvInfo *argTable .AP Tcl_Interp *interp in Interpreter to use for returning error messages. .AP Tk_Window tkwin in Window to use when arguments specify Tk options. If NULL, then no Tk options will be processed. .AP int argcPtr in/out Pointer to number of arguments in argv; gets modified to hold number of unprocessed arguments that remain after the call. .AP "const char" **argv in/out Command line arguments passed to main program. Modified to hold unprocessed arguments that remain after the call. .AP Tk_ArgvInfo *argTable in Array of argument descriptors, terminated by element with type \fBTK_ARGV_END\fR. .AP int flags in If non-zero, then it specifies one or more flags that control the parsing of arguments. Different flags may be OR'ed together. The flags currently defined are \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR, \fBTK_ARGV_NO_ABBREV\fR, \fBTK_ARGV_NO_LEFTOVERS\fR, and \fBTK_ARGV_NO_DEFAULTS\fR. .BE .SH DESCRIPTION .PP \fBTk_ParseArgv\fR processes an array of command-line arguments according to a table describing the kinds of arguments that are expected. Each of the arguments in \fIargv\fR is processed in turn: if it matches one of the entries in \fIargTable\fR, the argument is processed according to that entry and discarded. The arguments that do not match anything in \fIargTable\fR are copied down to the beginning of \fIargv\fR (retaining their original order) and returned to the caller. At the end of the call \fBTk_ParseArgv\fR sets \fI*argcPtr\fR to hold the number of arguments that are left in \fIargv\fR, and \fIargv[*argcPtr]\fR will hold the value NULL. Normally, \fBTk_ParseArgv\fR assumes that \fIargv[0]\fR is a command name, so it is treated like an argument that does not match \fIargTable\fR and returned to the caller; however, if the \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR bit is set in \fIflags\fR then \fIargv[0]\fR will be processed just like the other elements of \fIargv\fR. .PP \fBTk_ParseArgv\fR normally returns the value \fBTCL_OK\fR. If an error occurs while parsing the arguments, then \fBTCL_ERROR\fR is returned and \fBTk_ParseArgv\fR will leave an error message in the result of interpreter \fIinterp\fR in the standard Tcl fashion. In the event of an error return, \fI*argvPtr\fR will not have been modified, but \fIargv\fR could have been partially modified. The possible causes of errors are explained below. .PP The \fIargTable\fR array specifies the kinds of arguments that are expected; each of its entries has the following structure: .CS typedef struct { const char *\fIkey\fR; int \fItype\fR; void *\fIsrc\fR; void *\fIdst\fR; const char *\fIhelp\fR; } \fBTk_ArgvInfo\fR; .CE The \fIkey\fR field is a string such as .QW \-display or .QW \-bg that is compared with the values in \fIargv\fR. \fIType\fR indicates how to process an argument that matches \fIkey\fR (more on this below). \fISrc\fR and \fIdst\fR are additional values used in processing the argument. Their exact usage depends on \fItype\fR, but typically \fIsrc\fR indicates a value and \fIdst\fR indicates where to store the value. The \fBchar *\fR declarations for \fIsrc\fR and \fIdst\fR are placeholders: the actual types may be different. Lastly, \fIhelp\fR is a string giving a brief description of this option; this string is printed when users ask for help about command-line options. .PP When processing an argument in \fIargv\fR, \fBTk_ParseArgv\fR compares the argument to each of the \fIkey\fR's in \fIargTable\fR. \fBTk_ParseArgv\fR selects the first specifier whose \fIkey\fR matches the argument exactly, if such a specifier exists. Otherwise \fBTk_ParseArgv\fR selects a specifier for which the argument is a unique abbreviation. If the argument is a unique abbreviation for more than one specifier, then an error is returned. If there is no matching entry in \fIargTable\fR, then the argument is skipped and returned to the caller. .PP Once a matching argument specifier is found, \fBTk_ParseArgv\fR processes the argument according to the \fItype\fR field of the specifier. The argument that matched \fIkey\fR is called .QW "the matching argument" in the descriptions below. As part of the processing, \fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR after the matching argument, which is called .QW "the following argument" . The legal values for \fItype\fR, and the processing that they cause, are as follows: .IP \fBTK_ARGV_END\fR Marks the end of the table. The last entry in \fIargTable\fR must have this type; all of its other fields are ignored and it will never match any arguments. .IP \fBTK_ARGV_CONSTANT\fR \fISrc\fR is treated as an integer and \fIdst\fR is treated as a pointer to an integer. \fISrc\fR is stored at \fI*dst\fR. The matching argument is discarded. .IP \fBTK_ARGV_INT\fR The following argument must contain an integer string in the format accepted by \fBstrtol\fR (e.g. .QW 0 and .QW 0x prefixes may be used to specify octal or hexadecimal numbers, respectively). \fIDst\fR is treated as a pointer to an integer; the following argument is converted to an integer value and stored at \fI*dst\fR. \fISrc\fR is ignored. The matching and following arguments are discarded from \fIargv\fR. .IP \fBTK_ARGV_FLOAT\fR The following argument must contain a floating-point number in the format accepted by \fBstrtol\fR. \fIDst\fR is treated as the address of a double-precision floating point value; the following argument is converted to a double-precision value and stored at \fI*dst\fR. The matching and following arguments are discarded from \fIargv\fR. .IP \fBTK_ARGV_STRING\fR In this form, \fIdst\fR is treated as a pointer to a (char *); \fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following argument, and discards the matching and following arguments from \fIargv\fR. \fISrc\fR is ignored. .IP \fBTK_ARGV_UID\fR This form is similar to \fBTK_ARGV_STRING\fR, except that the argument is turned into a Tk_Uid by calling \fBTk_GetUid\fR. \fIDst\fR is treated as a pointer to a Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid corresponding to the following argument, and discards the matching and following arguments from \fIargv\fR. \fISrc\fR is ignored. .IP \fBTK_ARGV_CONST_OPTION\fR This form causes a Tk option to be set (as if the \fBoption\fR command had been invoked). The \fIsrc\fR field is treated as a pointer to a string giving the value of an option, and \fIdst\fR is treated as a pointer to the name of the option. The matching argument is discarded. If \fItkwin\fR is NULL, then argument specifiers of this type are ignored (as if they did not exist). .IP \fBTK_ARGV_OPTION_VALUE\fR This form is similar to \fBTK_ARGV_CONST_OPTION\fR, except that the value of the option is taken from the following argument instead of from \fIsrc\fR. \fIDst\fR is used as the name of the option. \fISrc\fR is ignored. The matching and following arguments are discarded. If \fItkwin\fR is NULL, then argument specifiers of this type are ignored (as if they did not exist). .IP \fBTK_ARGV_OPTION_NAME_VALUE\fR In this case the following argument is taken as the name of a Tk option and the argument after that is taken as the value for that option. Both \fIsrc\fR and \fIdst\fR are ignored. All three arguments are discarded from \fIargv\fR. If \fItkwin\fR is NULL, then argument specifiers of this type are ignored (as if they did not exist). .IP \fBTK_ARGV_HELP\fR When this kind of option is encountered, \fBTk_ParseArgv\fR uses the \fIhelp\fR fields of \fIargTable\fR to format a message describing all the valid arguments. The message is placed in interpreter \fIinterp\fR's result and \fBTk_ParseArgv\fR returns \fBTCL_ERROR\fR. When this happens, the caller normally prints the help message and aborts. If the \fIkey\fR field of a \fBTK_ARGV_HELP\fR specifier is NULL, then the specifier will never match any arguments; in this case the specifier simply provides extra documentation, which will be included when some other \fBTK_ARGV_HELP\fR entry causes help information to be returned. .IP \fBTK_ARGV_REST\fR This option is used by programs or commands that allow the last several of their options to be the name and/or options for some other program. If a \fBTK_ARGV_REST\fR argument is found, then \fBTk_ParseArgv\fR does not process any of the remaining arguments; it returns them all at the beginning of \fIargv\fR (along with any other unprocessed arguments). In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an integer value, and stores at \fI*dst\fR the index of the first of the \fBTK_ARGV_REST\fR options in the returned \fIargv\fR. This allows the program to distinguish the \fBTK_ARGV_REST\fR options from other unprocessed options that preceded the \fBTK_ARGV_REST\fR. .IP \fBTK_ARGV_FUNC\fR For this kind of argument, \fIsrc\fR is treated as the address of a procedure, which is invoked to process the following argument. The procedure should have the following structure: .RS .CS int \fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR) char *\fIdst\fR; char *\fIkey\fR; char *\fInextArg\fR; { } .CE The \fIdst\fR and \fIkey\fR parameters will contain the corresponding fields from the \fIargTable\fR entry, and \fInextArg\fR will point to the following argument from \fIargv\fR (or NULL if there are not any more arguments left in \fIargv\fR). If \fIfunc\fR uses \fInextArg\fR (so that \fBTk_ParseArgv\fR should discard it), then it should return 1. Otherwise it should return 0 and \fBTkParseArgv\fR will process the following argument in the normal fashion. In either event the matching argument is discarded. .RE .IP \fBTK_ARGV_GENFUNC\fR This form provides a more general procedural escape. It treats \fIsrc\fR as the address of a procedure, and passes that procedure all of the remaining arguments. The procedure should have the following form: .RS .CS int \fIgenfunc\fR(dst, interp, key, argc, argv) char *\fIdst\fR; Tcl_Interp *\fIinterp\fR; char *\fIkey\fR; int \fIargc\fR; char **\fIargv\fR; { } .CE The \fIdst\fR and \fIkey\fR parameters will contain the corresponding fields from the \fIargTable\fR entry. \fIInterp\fR will be the same as the \fIinterp\fR argument to \fBTcl_ParseArgv\fR. \fIArgc\fR and \fIargv\fR refer to all of the options after the matching one. \fIGenfunc\fR should behave in a fashion similar to \fBTk_ParseArgv\fR: parse as many of the remaining arguments as it can, then return any that are left by compacting them to the beginning of \fIargv\fR (starting at \fIargv\fR[0]). \fIGenfunc\fR should return a count of how many arguments are left in \fIargv\fR; \fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters an error then it should leave an error message in interpreter \fIinterp\fR's result, in the usual Tcl fashion, and return \-1; when this happens \fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR. .RE .SS "FLAGS" .IP \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR \fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program or command name, and returns it to the caller just as if it had not matched \fIargTable\fR. If this flag is given, then \fIargv[0]\fR is not given special treatment. .IP \fBTK_ARGV_NO_ABBREV\fR Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for \fIkey\fR values in \fIargTable\fR. If this flag is given then only exact matches will be acceptable. .IP \fBTK_ARGV_NO_LEFTOVERS\fR Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the caller. If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR will return an error if it encounters any argument that does not match \fIargTable\fR. The only exception to this rule is \fIargv[0]\fR, which will be returned to the caller with no errors as long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR is not specified. .IP \fBTK_ARGV_NO_DEFAULTS\fR Normally, \fBTk_ParseArgv\fR searches an internal table of standard argument specifiers in addition to \fIargTable\fR. If this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will use only \fIargTable\fR and not its default table. .SH EXAMPLE .PP Here is an example definition of an \fIargTable\fR and some sample command lines that use the options. Note the effect on \fIargc\fR and \fIargv\fR; arguments processed by \fBTk_ParseArgv\fR are eliminated from \fIargv\fR, and \fIargc\fR is updated to reflect reduced number of arguments. .CS /* * Define and set default values for globals. */ int debugFlag = 0; int numReps = 100; char defaultFileName[] = "out"; char *fileName = defaultFileName; Boolean exec = FALSE; /* * Define option descriptions. */ Tk_ArgvInfo argTable[] = { {"-X", TK_ARGV_CONSTANT, (char *) 1, &debugFlag, "Turn on debugging printfs"}, {"-N", TK_ARGV_INT, NULL, &numReps, "Number of repetitions"}, {"-of", TK_ARGV_STRING, NULL, &fileName, "Name of file for output"}, {"x", TK_ARGV_REST, NULL, &exec, "File to exec, followed by any arguments (must be last argument)."}, {NULL, TK_ARGV_END, NULL, NULL, NULL} }; int main(int argc, char *argv[]) { \&... if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { fprintf(stderr, "%s\en", Tcl_GetString(Tcl_GetObjResult(interp))); exit(1); } /* * Remainder of the program. */ } .CE .PP Note that default values can be assigned to variables named in \fIargTable\fR: the variables will only be overwritten if the particular arguments are present in \fIargv\fR. Here are some example command lines and their effects. .CS prog -N 200 infile # just sets the numReps variable to 200 prog -of out200 infile # sets fileName to reference "out200" prog -XN 10 infile # sets the debug flag, also sets numReps .CE In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 2, \fIargv\fR[0] will be .QW prog , \fIargv\fR[1] will be .QW infile , and \fIargv\fR[2] will be NULL. .SH KEYWORDS arguments, command line, options tk9.0.3/doc/photo.n0000644001000000100000000010475615105057705017141 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Australian National University '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" Author: Paul Mackerras (paulus@cs.anu.edu.au), '\" Department of Computer Science, '\" Australian National University. '\" .TH photo n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME photo \- Full-color images .SH SYNOPSIS .nf \fBimage create photo \fR?\fIname\fR? ?\fIoptions\fR? \fIimageName \fBblank\fR \fIimageName \fBcget \fIoption\fR \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? \fIimageName \fBcopy \fIsourceImage\fR ?\fIoption value(s) ...\fR? \fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? \fIimageName \fBget \fIx y\fR ?\fIoption\fR? \fIimageName \fBput \fIdata\fR ?\fIoption value(s) ...\fR? \fIimageName \fBread \fIfilename\fR ?\fIoption value(s) ...\fR? \fIimageName \fBredither\fR \fIimageName \fBtransparency \fIsubcommand \fR?\fIarg ...\fR? \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? .fi .BE .SH DESCRIPTION .PP A photo is an image whose pixels can display any color with a varying degree of transparency (the alpha channel). A photo image is stored internally in full color (32 bits per pixel), and is displayed using dithering if necessary. Image data for a photo image can be obtained from a file or a string, or it can be supplied from C code through a procedural interface. At present, only .VS 8.6 PNG, .VE 8.6 GIF, PPM/PGM, .VS 9.0 and (read-only) SVG .VE 9.0 formats are supported, but an interface exists to allow additional image file formats to be added easily. A photo image is (semi)transparent if the image data it was obtained from had transparency information. In regions where no image data has been supplied, it is fully transparent. Transparency may also be modified with the \fBtransparency set\fR subcommand. .SH "CREATING PHOTOS" .PP Like all images, photos are created using the \fBimage create\fR command. Photos support the following \fIoptions\fR: .\" OPTION: -data .TP \fB\-data \fIstring\fR . Specifies the contents of the image as a string. .VS 9.0 The string should contain data in the default list-of-lists form, .VE 9.0 binary data or, for some formats, base64-encoded data (this is currently guaranteed to be supported for PNG and GIF images). The format of the string must be one of those for which there is an image file format handler that will accept string data. If both the \fB\-data\fR and \fB\-file\fR options are specified, the \fB\-file\fR option takes precedence. .\" OPTION: -format .TP \fB\-format\fR {\fIformat-name\fR ?\fIoption value ...\fR?} . Specifies the name of the file format for the data specified with the \fB\-data\fR or \fB\-file\fR option and optional arguments passed to the format handler. Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. .\" OPTION: -file .TP \fB\-file \fIname\fR . \fIname\fR gives the name of a file that is to be read to supply data for the photo image. The file format must be one of those for which there is an image file format handler that can read data. .\" OPTION: -gamma .TP \fB\-gamma \fIvalue\fR . Specifies that the colors allocated for displaying this image in a window should be corrected for a non-linear display with the specified gamma exponent value. (The intensity produced by most CRT displays is a power function of the input value, to a good approximation; gamma is the exponent and is typically around 2). The value specified must be greater than zero. The default value is one (no correction). In general, values greater than one will make the image lighter, and values less than one will make it darker. .\" OPTION: -height .TP \fB\-height \fInumber\fR . Specifies the height of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink vertically to fit the data stored in it. .VS 9.0 .\" OPTION: -metadata .TP \fB\-metadata \fImetadata\fR . Set the metadata dictionary of the image. Additional keys may be set within the metadata dictionary of the image, if image data is processed due to a \fB\-file\fR or \fB\-data\fR options and the driver outputs any metadata keys. See section \fBMETADATA DICTIONARY\fR below. .VE 9.0 .\" OPTION: -palette .TP \fB\-palette \fIpalette-spec\fR . Specifies the resolution of the color cube to be allocated for displaying this image, and thus the number of colors used from the colormaps of the windows where it is displayed. The \fIpalette-spec\fR string may be either a single decimal number, specifying the number of shades of gray to use, or three decimal numbers separated by slashes (/), specifying the number of shades of red, green and blue to use, respectively. If the first form (a single number) is used, the image will be displayed in monochrome (i.e., grayscale). .\" OPTION: -width .TP \fB\-width \fInumber\fR . Specifies the width of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink horizontally to fit the data stored in it. .SH "IMAGE COMMAND" .PP When a photo image is created, Tk also creates a new command whose name is the same as the image. This command may be used to invoke various operations on the image. It has the following general form: .CS \fIimageName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. .PP Those options that write data to the image generally expand the size of the image, if necessary, to accommodate the data written to the image, unless the user has specified non-zero values for the \fB\-width\fR and/or \fB\-height\fR configuration options, in which case the width and/or height, respectively, of the image will not be changed. .PP The following commands are possible for photo images: .\" METHOD: blank .TP \fIimageName \fBblank\fR . Blank the image; that is, set the entire image to have no data, so it will be displayed as transparent, and the background of whatever window it is displayed in will show through. The metadata dict of the image is not changed. .\" METHOD: cget .TP \fIimageName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBimage create\fR \fBphoto\fR command. .\" METHOD: configure .TP \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options for the image. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBimage create\fR \fBphoto\fR command. .VS 9.0 Note that setting the \fB\-metadata\fR option without any other option will not invoke the image format driver to recreate the bitmap. .VE 9.0 .\" METHOD: copy .TP \fIimageName \fBcopy\fI sourceImage\fR ?\fIoption value(s) ...\fR? . Copies a region from the image called \fIsourceImage\fR (which must be a photo image) to the image called \fIimageName\fR, possibly with pixel zooming and/or subsampling. If no options are specified, this command copies the whole of \fIsourceImage\fR into \fIimageName\fR, starting at coordinates (0,0) in \fIimageName\fR. The following options may be specified: .RS .\" OPTION: -from .TP \fB\-from \fIx1 y1 x2 y2\fR . Specifies a rectangular sub-region of the source image to be copied. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the default value is the bottom-right corner of the source image. The pixels copied will include the left and top edges of the specified rectangle but not the bottom or right edges. If the \fB\-from\fR option is not given, the default is the whole source image. .\" OPTION: -to .TP \fB\-to \fIx1 y1 x2 y2\fR . Specifies a rectangular sub-region of the destination image to be affected. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the default value is (\fIx1,y1\fR) plus the size of the source region (after subsampling and zooming, if specified). If \fIx2\fR and \fIy2\fR are specified, the source region will be replicated if necessary to fill the destination region in a tiled fashion. .\" OPTION: -shrink .TP \fB\-shrink\fR . Specifies that the size of the destination image should be reduced, if necessary, so that the region being copied into is at the bottom-right corner of the image. This option will not affect the width or height of the image if the user has specified a non-zero value for the \fB\-width\fR or \fB\-height\fR configuration option, respectively. .\" OPTION: -zoom .TP \fB\-zoom \fIx y\fR . Specifies that the source region should be magnified by a factor of \fIx\fR in the X direction and \fIy\fR in the Y direction. If \fIy\fR is not given, the default value is the same as \fIx\fR. With this option, each pixel in the source image will be expanded into a block of \fIx\fR x \fIy\fR pixels in the destination image, all the same color. \fIx\fR and \fIy\fR must be greater than 0. .\" OPTION: -subsample .TP \fB\-subsample \fIx y\fR . Specifies that the source image should be reduced in size by using only every \fIx\fRth pixel in the X direction and \fIy\fRth pixel in the Y direction. Negative values will cause the image to be flipped about the Y or X axes, respectively. If \fIy\fR is not given, the default value is the same as \fIx\fR. .\" OPTION: -compositingrule .TP \fB\-compositingrule \fIrule\fR . Specifies how transparent pixels in the source image are combined with the destination image. When a compositing rule of \fIoverlay\fR is set, the old contents of the destination image are visible, as if the source image were printed on a piece of transparent film and placed over the top of the destination. When a compositing rule of \fIset\fR is set, the old contents of the destination image are discarded and the source image is used as-is. The default compositing rule is \fIoverlay\fR. .RE .\" METHOD: data .TP \fIimageName \fBdata\fR ?\fIoption value(s) ...\fR? . Returns image data in the form of a string. .VS 9.0 The format of the string depends on the format handler. By default, a human readable format as a list of lists of pixel data is used, other formats can be chosen with the \fB\-format\fR option. See \fBIMAGE FORMATS\fR below for details. .VE 9.0 The following options may be specified: .RS .\" OPTION: -background .TP \fB\-background\fI color\fR . If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color. .\" OPTION: -format .TP \fB\-format\fR {\fIformat-name\fR ?\fIoption value ...\fR?} . Specifies the name of the image file format handler to use and, optionally, arguments to the format handler. Specifically, this subcommand searches for the first handler whose name matches an initial substring of \fIformat-name\fR and which has the capability to write a string containing this image data. .VS 9.0 If this option is not given, this subcommand uses the default format that consists of a list (one element per row) of lists (one element per pixel/column) of colors in .QW \fB#\fIrrggbb\fR format (see \fBIMAGE FORMATS\fR below). .VE 9.0 Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. .\" OPTION: -from .TP \fB\-from \fIx1 y1 x2 y2\fR . Specifies a rectangular region of \fIimageName\fR to be returned. If only \fIx1\fR and \fIy1\fR are specified, the region extends from \fI(x1,y1)\fR to the bottom-right corner of \fIimageName\fR. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region, including x1,y1 and excluding x2,y2. The default, if this option is not given, is the whole image. .\" OPTION: -grayscale .TP \fB\-grayscale\fR . If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. .VS 9.0 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR . Image format handler may use metadata to be included in the returned data string. The specified \fImetadata\fR is passed to the driver for inclusion in the data. If no \fB\-metadata\fR option is given, the current metadata of the image is used. .VE 9.0 .RE .\" METHOD: get .TP \fIimageName \fBget\fI x y\fR ?\fB\-withalpha\fR? . Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the image as a list of three integers between 0 and 255, representing the red, green and blue components respectively. If the \fB\-withalpha\fR option is specified, the returned list will have a fourth element representing the alpha value of the pixel as an integer between 0 and 255. .\" METHOD: put .TP \fIimageName \fBput\fI data\fR ?\fIoption value(s) ...\fR? . Sets pixels in \fI imageName\fR to the data specified in \fIdata\fR. .VS 9.0 This command searches the list of image file format handlers for a handler that can interpret the data in \fIdata\fR, and then reads the image encoded within into \fIimageName\fR (the destination image). See \fBIMAGE FORMATS\fR below for details on formats for image data. .VE 9.0 The following options may be specified: .RS .\" OPTION: -format .TP \fB\-format\fR {\fIformat-name\fR ?\fIoption value ..\fR?} . Specifies the format of the image data in \fIdata\fR and, optionally, arguments to be passed to the format handler. Specifically, only image file format handlers whose names begin with \fIformat-name\fR will be used while searching for an image data format handler to read the data. Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. .VS 9.0 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR . A specified \fImetadata\fR is passed to the image format driver when interpreting the data. Note that the current metadata of the image is not passed to the format driver and is not changed by the command. .VE 9.0 .\" OPTION: -to .TP \fB\-to \fIx1 y1\fR ?\fIx2 y2\fR? . Specifies the coordinates of the top-left corner (\fIx1\fR,\fIy1\fR) of the region of \fIimageName\fR into which the image data will be copied. The default position is (0,0). If \fIx2\fR,\fIy2\fR is given and \fIdata\fR is not large enough to cover the rectangle specified by this option, the image data extracted will be tiled so it covers the entire destination rectangle. If the region specified with this option is smaller than the supplied \fIdata\fR, the exceeding data is silently discarded. Note that if \fIdata\fR specifies a single color value, then a region extending to the bottom-right corner represented by (\fIx2\fR,\fIy2\fR) will be filled with that color. .RE .\" METHOD: read .TP \fIimageName \fBread\fI filename\fR ?\fIoption value(s) ...\fR? . Reads image data from the file named \fIfilename\fR into the image. This command first searches the list of image file format handlers for a handler that can interpret the data in \fIfilename\fR, and then reads the image in \fIfilename\fR into \fIimageName\fR (the destination image). The following options may be specified: .RS .\" OPTION: -format .TP \fB\-format {\fIformat-name\fR ?\fIoption value ..\fR?} . Specifies the format of the image data in \fIfilename\fR and, optionally, additional options to the format handler. Specifically, only image file format handlers whose names begin with \fIformat-name\fR will be used while searching for an image data format handler to read the data. Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. .\" OPTION: -from .TP \fB\-from \fIx1 y1 x2 y2\fR . Specifies a rectangular sub-region of the image file data to be copied to the destination image. If only \fIx1\fR and \fIy1\fR are specified, the region extends from (\fIx1,y1\fR) to the bottom-right corner of the image in the image file. If all four coordinates are specified, they specify diagonally opposite corners or the region. The default, if this option is not specified, is the whole of the image in the image file. .VS 9.0 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR . A specified \fImetadata\fR is passed to the image format driver when interpreting the data. Note that the current metadata of the image is not passed to the format driver and is not changed by the command. .VE 9.0 .\" OPTION: -shrink .TP \fB\-shrink\fR . If this option, the size of \fIimageName\fR will be reduced, if necessary, so that the region into which the image file data are read is at the bottom-right corner of the \fIimageName\fR. This option will not affect the width or height of the image if the user has specified a non-zero value for the \fB\-width\fR or \fB\-height\fR configuration option, respectively. .\" OPTION: -to .TP \fB\-to \fIx y\fR . Specifies the coordinates of the top-left corner of the region of \fIimageName\fR into which data from \fIfilename\fR are to be read. The default is (0,0). .RE .\" METHOD: redither .TP \fIimageName \fBredither\fR . The dithering algorithm used in displaying photo images propagates quantization errors from one pixel to its neighbors. If the image data for \fIimageName\fR is supplied in pieces, the dithered image may not be exactly correct. Normally the difference is not noticeable, but if it is a problem, this command can be used to recalculate the dithered image in each window where the image is displayed. .\" METHOD: transparency .TP \fIimageName \fBtransparency \fIsubcommand \fR?\fIarg ...\fR? . Allows examination and manipulation of the transparency information in the photo image. Several subcommands are available: .RS .TP \fIimageName \fBtransparency get \fIx y\fR ?\fB\-alpha\fR? .VS 9.0 Returns true if the pixel at (\fIx\fR,\fIy\fR) is fully transparent, false otherwise. If the option \fB\-alpha\fR is passed, returns the alpha value of the pixel instead, as an integer in the range 0 to 255. .VE 9.0 .TP \fIimageName \fBtransparency set \fIx y newVal\fR ?\fB\-alpha\fR? .VS 9.0 Change the transparency of the pixel at (\fIx\fR,\fIy\fR) to \fInewVal.\fR If no additional option is passed, \fInewVal\fR is interpreted as a boolean and the pixel is made fully transparent if that value is true, fully opaque otherwise. If the \fB\-alpha\fR option is passed, \fInewVal\fR is interpreted as an integral alpha value for the pixel, which must be in the range 0 to 255. .VE 9.0 .RE .\" METHOD: write .TP \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? . Writes image data from \fIimageName\fR to a file named \fIfilename\fR. The following options may be specified: .RS .\" OPTION: -background .TP \fB\-background\fI color\fR . If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color. .\" OPTION: -format .TP \fB\-format\fR {\fIformat-name\fR ?\fIoption value ...\fR?} . Specifies the name of the image file format handler to be used to write the data to the file and, optionally, options to pass to the format handler. Specifically, this subcommand searches for the first handler whose name matches an initial substring of \fIformat-name\fR and which has the capability to write an image file. If this option is not given, the format is guessed from the file extension. If that cannot be determined, this subcommand uses the first handler that has the capability to write an image file. Note that the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. .\" OPTION: -from .TP \fB\-from \fIx1 y1 x2 y2\fR . Specifies a rectangular region of \fIimageName\fR to be written to the image file. If only \fIx1\fR and \fIy1\fR are specified, the region extends from \fI(x1,y1)\fR to the bottom-right corner of \fIimageName\fR. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region. The default, if this option is not given, is the whole image. .\" OPTION: -grayscale .TP \fB\-grayscale\fR . If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. .VS 9.0 .\" OPTION: -metadata .TP \fB\-metadata\fI metadata\fR . Image format handler may use metadata to be included in the written file. The specified \fImetadata\fR is passed to the driver for inclusion in the file. If no \fB\-metadata\fR option is given, the current metadata of the image is used. .VE 9.0 .RE .SH "IMAGE FORMATS" .PP The photo image code is structured to allow handlers for additional image file formats to be added easily. The photo image code maintains a list of these handlers. Handlers are added to the list by registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The standard Tk distribution comes with handlers for PPM/PGM, PNG, GIF and (read-only) SVG formats, .VS 9.0 as well as the \fBdefault\fR handler to encode/decode image data in a human readable form. .VE 9.0 These handlers are automatically registered on initialization. .PP When reading an image file or processing string data specified with the \fB\-data\fR configuration option, the photo image code invokes each handler in turn until one is found that claims to be able to read the data in the file or string. Usually this will find the correct handler, but if it does not, the user may give a format name with the \fB\-format\fR option to specify which handler to use. In this case, the photo image code will try those handlers whose names begin with the string specified for the \fB\-format\fR option (the comparison is case-insensitive). For example, if the user specifies \fB\-format gif\fR, then a handler named GIF87 or GIF89 may be invoked, but a handler named JPEG may not (assuming that such handlers had been registered). .PP When writing image data to a file, the processing of the \fB\-format\fR option is slightly different: the string value given for the \fB\-format\fR option must begin with the complete name of the requested handler, and may contain additional information following that, which the handler can use, for example, to specify which variant to use of the formats supported by the handler. Note that not all image handlers may support writing transparency data to a file, even where the target image format does. .VS 9.0 .SS "THE DEFAULT IMAGE HANDLER" .PP The \fBdefault\fR image handler cannot be used to read or write data from/to a file. Its sole purpose is to encode and decode image data in string form in a clear text, human readable, form. The \fIimageName\fR \fBdata\fR subcommand uses this handler when no other format is specified. When reading image data from a string with \fIimageName\fR \fBput\fR or the \fB\-data\fR option, the default handler is treated as the other handlers. .PP Image data in the \fBdefault\fR string format is a (top-to-bottom) list of scan-lines, with each scan-line being a (left-to-right) list of pixel data. Every scan-line has the same length. The color and, optionally, alpha value of each pixel is specified in any of the forms described in the \fBCOLOR FORMATS\fR section below. .VE 9.0 .SS "FORMAT SUBOPTIONS" .PP .VS 8.6 Image formats may support sub-options, which are specified using additional words in the value to the \fB\-format\fR option. These suboptions can affect how image data is read or written to file or string. The nature and values of these options is up to the format handler. The built-in handlers support these suboptions: .\" OPTION -colorformat .VS 9.0 .TP \fBdefault \-colorformat\fI formatType\fR . The option is allowed when writing image data to a string with \fIimageName \fBdata\fR. Specifies the format to use for the color string of each pixel. \fIformatType\fR may be one of: \fBrgb\fR to encode pixel data in the form \fB#\fIRRGGBB\fR, \fBrgba\fR to encode pixel data in the form \fB#\fIRRGGBBAA\fR or \fBlist\fR to encode pixel data as a list with four elements. See \fBCOLOR FORMATS\fR below for details. The default is \fBrgb\fR. .VE 9.0 .\" OPTION -index .TP \fBgif \-index\fI indexValue\fR . The option has effect when reading image data from a file. When parsing a multi-part GIF image, Tk normally only accesses the first image. By giving the \fB\-index\fR sub-option, the \fIindexValue\fR'th value may be used instead. The \fIindexValue\fR must be an integer from 0 up to the number of image parts in the GIF data. .\" OPTION -alpha .TP \fBpng \-alpha\fI alphaValue\fR . The option has effect when reading image data from a file. Specifies an additional alpha filtering for the overall image, which allows the background on which the image is displayed to show through. This usually also has the effect of desaturating the image. The \fIalphaValue\fR must be between 0.0 and 1.0. .\" OPTION -dpi .\" OPTION -scale .\" OPTION -scaletowidth .\" OPTION -scaletoheight .TP \fBsvg \-dpi\fI dpiValue \fB\-scale\fI scaleValue \fB\-scaletowidth\fI width \fB\-scaletoheight\fI height\fR . \fIdpiValue\fR is used in conversion between given coordinates and screen resolution. The value must be greater than 0 and the default value is 96. .PP .RS \fIscaleValue\fR is used to scale the resulting image. The value must be greater than 0 and the default value is 1. \fIwidth\fR and \fIheight\fR are the width or height that the image will be adjusted to. Only one parameter among \fB\-scale\fR, \fB\-scaletowidth\fR and \fB\-scaletoheight\fR can be given at a time and the aspect ratio of the original image is always preserved. The \fBsvg\fR format supports a wide range of SVG features, but the full SVG standard is not available, for instance the 'text' feature is missing and silently ignored when reading the SVG data. The supported SVG features are: .TP \fBelements:\fR . g, path, rect, circle, ellipse, line, polyline, polygon, linearGradient, radialGradient, stop, defs, svg, style .TP \fBattributes:\fR . width, height, viewBox, preserveAspectRatio with none, xMin, xMid, xMax, yMin, yMid, yMax, slice .TP \fBgradient attributes:\fR . gradientUnits with objectBoundingBox, gradientTransform, cx, cy, r fx, fy x1, y1, x2, y2 spreadMethod with pad, reflect or repeat, xlink:href .TP \fBpoly attributes:\fR . points .TP \fBline attributes:\fR . x1, y1, x2, y2 .TP \fBellipse attributes:\fR . cx, cy, rx, ry .TP \fBcircle attributes:\fR . cx, cy, r .TP \fBrectangle attributes:\fR . x, y, width, height, rx, ry .TP \fBpath attributes:\fR . d with m, M, l, L, h, H, v, V, c, C, s, S, q, Q, t, T, a, A, z, Z .TP \fBstyle attributes:\fR . display with none, visibility, hidden, visible, fill with nonzero and evenodd, opacity, fill-opacity, stroke, stroke-width, stroke-dasharray, stroke-dashoffset, stroke-opacity, stroke-linecap with butt, round and square, stroke-linejoin with miter, round and bevel, stroke-miterlimit fill-rule, font-size, transform with matrix, translate, scale, rotate, skewX and skewY, stop-color, stop-opacity, offset, id, class .RE .PP .RS Currently only SVG images reading and conversion into (pixel-based format) photos is supported: Tk does not (yet) support bundling photo images in SVG vector graphics. .RE .VE 8.6 .VS 9.0 .SH "COLOR FORMATS" .PP The default image handler can represent/parse color and alpha values of a pixel in one of the formats listed below. If a color format does not contain transparency information, full opacity is assumed. The available color formats are: .IP \(bu 3 The empty string - interpreted as full transparency, the color value is undefined. .IP \(bu 3 Any value accepted by \fBTk_GetColor\fR, optionally followed by an alpha suffix. The alpha suffix may be one of: .RS .TP \fB@\fR\fIA\fR . The alpha value \fIA\fR must be a fractional value in the range 0.0 (fully transparent) to 1.0 (fully opaque). .TP \fB#\fR\fIX\fR . The alpha value \fIX\fR is a hexadecimal digit that specifies an integer alpha value in the range 0 (fully transparent) to 255 (fully opaque). This is expanded in range from 4 bits wide to 8 bits wide by multiplication by 0x11. .TP \fB#\fR\fIXX\fR . The alpha value \fIXX\fR is passed as two hexadecimal digits that specify an integer alpha value in the range 0 (fully transparent) to 255 (fully opaque). .RE .IP \(bu 3 A Tcl list with three or four integers in the range 0 to 255, specifying the values for the red, green, blue and (optionally) alpha channels respectively. .IP \(bu 3 \fB#\fR\fIRGBA\fR format: a \fB#\fR followed by four hexadecimal digits, where each digit is the value for the red, green, blue and alpha channels respectively. Each digit will be expanded internally to 8 bits by multiplication by 0x11. .IP \(bu 3 \fB#\fR\fIRRGGBBAA\fR format: \fB#\fR followed by eight hexadecimal digits, where each pair of subsequent digits represents the value for the red, green, blue and alpha channels respectively. .VE 9.0 .SH "COLOR ALLOCATION" .PP When a photo image is displayed in a window, the photo image code allocates colors to use to display the image and dithers the image, if necessary, to display a reasonable approximation to the image using the colors that are available. The colors are allocated as a color cube, that is, the number of colors allocated is the product of the number of shades of red, green and blue. .PP Normally, the number of colors allocated is chosen based on the depth of the window. For example, in an 8-bit PseudoColor window, the photo image code will attempt to allocate seven shades of red, seven shades of green and four shades of blue, for a total of 198 colors. In a 1-bit StaticGray (monochrome) window, it will allocate two colors, black and white. In a 24-bit DirectColor or TrueColor window, it will allocate 256 shades each of red, green and blue. Fortunately, because of the way that pixel values can be combined in DirectColor and TrueColor windows, this only requires 256 colors to be allocated. If not all of the colors can be allocated, the photo image code reduces the number of shades of each primary color and tries again. .PP The user can exercise some control over the number of colors that a photo image uses with the \fB\-palette\fR configuration option. If this option is used, it specifies the maximum number of shades of each primary color to try to allocate. It can also be used to force the image to be displayed in shades of gray, even on a color display, by giving a single number rather than three numbers separated by slashes. .VS 9.0 .SH "METADATA DICTIONARY" .PP Each image has a metadata dictionary property. This dictionary is not relevant to the bitmap representation of the image, but may contain additional information like resolution or comments. Image format drivers may output metadata when image data is parsed, or may use metadata to be included in image files or formats. .SS "METADATA KEYS (MULTIPLE FORMATS)" .PP Each image format driver supports an individual set of metadata dictionary keys. Predefined keys are: .IP \fBDPI\fR Horizontal image resolution in DPI as a double value. Supported by format \fBpng\fR. .IP \fBaspect\fR Aspect ratio horizontal divided by vertical as double value. Supported by formats \fBgif\fR and \fBpng\fR. .IP \fBcomment\fR Image text comment. Supported by formats \fBgif\fR and \fBpng\fR. .PP It is valid to set any key in the metadata dict. A format driver will ignore keys that it does not handle. .SS "METADATA KEYS FOR ANIMATED GIF INFORMATION" .PP The following metadata keys are reported when reading a \fBgif\fR format file. They are typically used in conjunction with the \fB\-index\fR option of an animated \fBgif\fR file to properly display the subimage sequence. The options are linked to each subimage selected by \fB\-index\fR. .TP \fBdelay time\fI time\fR . Update delay time in 10ms units. This key is only present if the delay time is not 0. .TP \fBdisposal method\fI method\fR . Disposal method of the preceeding image, if given for the current image. Possible values are: \fBdo not dispose\fR, \fBrestore to background color\fR, \fBrestore to previous\fR. .TP \fBuser interaction\fI bool\fR . The key is present with a value of 1, if user interaction is specified. Otherwise, the key is not present. .TP \fBupdate region\fI X0\fR, \fIY0\fR, \fIwidth\fR, \fIheight\fR . Update region of the current subimage, if subimage has not the same size as the full image. The pixel outside of this box are all fully transparent. .PP .VE 9.0 .SH CREDITS .PP The photo image type was designed and implemented by Paul Mackerras, based on his earlier photo widget and some suggestions from John Ousterhout. .SH EXAMPLE .PP Load an image from a file and tile it to the size of a window, which is useful for producing a tiled background: .PP .CS # These lines should be called once \fBimage create photo\fR untiled -file "theFile.ppm" \fBimage create photo\fR tiled # These lines should be called whenever .someWidget changes # size; a binding is useful here set width [winfo width .someWidget] set height [winfo height .someWidget] tiled \fBcopy\fR untiled -to 0 0 $width $height -shrink .CE .PP .VS 8.6 The PNG image loader allows the application of an additional alpha factor during loading, which is useful for generating images suitable for disabled buttons: .PP .CS \fBimage create photo\fR icon -file "icon.png" \fBimage create photo\fR iconDisabled -file "icon.png" \e -format "png -alpha 0.5" button .b -image icon -disabledimage iconDisabled .CE .VE 8.6 .PP .VS 9.0 Create a green box with a simple shadow effect .PP .CS \fBimage create photo\fR foo # Make a simple graduated fill varying in alpha for the shadow for {set i 14} {$i > 0} {incr i -1} { set i2 [expr {$i + 30}] foo \fBput\fR [format black#%x [expr {15-$i}]] -to $i $i $i2 $i2 } # Put a solid green rectangle on top foo \fBput\fR #F080 -to 0 0 30 30 .VE 9.0 .CE .SH "SEE ALSO" image(n) .SH KEYWORDS photo, image, color '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/place.n0000644001000000100000000002650115105057705017063 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH place n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME place \- Geometry manager for fixed or rubber-sheet placement .SH SYNOPSIS \fBplace \fIoption arg \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The placer is a geometry manager for Tk. It provides simple fixed placement of windows, where you specify the exact size and location of one window, called the \fIcontent\fR, within another window, called the \fIcontainer\fR. The placer also provides rubber-sheet placement, where you specify the size and location of the content in terms of the dimensions of the container, so that the content changes size and location in response to changes in the size of the container. Lastly, the placer allows you to mix these styles of placement so that, for example, the content has a fixed width and height but is centered inside the container. .PP .TP \fBplace \fIwindow option value \fR?\fIoption value ...\fR? . Arrange for the placer to manage the geometry of a content whose pathName is \fIwindow\fR. The remaining arguments consist of one or more \fIoption\-value\fR pairs that specify the way in which \fIwindow\fR's geometry is managed. \fIOption\fR may have any of the values accepted by the \fBplace configure\fR command. .\" METHOD: configure .TP \fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the geometry options of the content given by \fIwindow\fR. If no \fIoption\fR is specified, this command returns a list describing the available options (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. .RS .PP The following \fIoption\-value\fR pairs are supported: .\" OPTION: -anchor .TP \fB\-anchor \fIwhere\fR . \fIWhere\fR specifies which point of \fIwindow\fR is to be positioned at the (x,y) location selected by the \fB\-x\fR, \fB\-y\fR, \fB\-relx\fR, and \fB\-rely\fR options. The anchor point is in terms of the outer area of \fIwindow\fR including its border, if any. Thus if \fIwhere\fR is \fBse\fR then the lower-right corner of \fIwindow\fR's border will appear at the given (x,y) location in the container. The anchor position defaults to \fBnw\fR. .\" OPTION: -bordermode .TP \fB\-bordermode \fImode\fR . \fIMode\fR determines the degree to which borders within the container are used in determining the placement of the content. The default and most common value is \fBinside\fR. In this case the placer considers the area of the container to be the innermost area of the container, inside any border: an option of \fB\-x 0\fR corresponds to an x-coordinate just inside the border and an option of \fB\-relwidth 1.0\fR means \fIwindow\fR will fill the area inside the container's border. .RS .PP If \fImode\fR is \fBoutside\fR then the placer considers the area of the container to include its border; this mode is typically used when placing \fIwindow\fR outside its container, as with the options \fB\-x 0 \-y 0 \-anchor ne\fR. Lastly, \fImode\fR may be specified as \fBignore\fR, in which case borders are ignored: the area of the container is considered to be its official X area, which includes any internal border but no external border. A bordermode of \fBignore\fR is probably not very useful. .RE .\" OPTION: -height .TP \fB\-height \fIsize\fR . \fISize\fR specifies the height for \fIwindow\fR in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR). The height will be the outer dimension of \fIwindow\fR including its border, if any. If \fIsize\fR is an empty string, or if no \fB\-height\fR or \fB\-relheight\fR option is specified, then the height requested internally by the window will be used. .\" OPTION: -in .TP \fB\-in \fIcontainer\fR . \fIContainer\fR specifies the path name of the window relative to which \fIwindow\fR is to be placed. \fIContainer\fR must either be \fIwindow\fR's parent or a descendant of \fIwindow\fR's parent. In addition, \fIcontainer\fR and \fIwindow\fR must both be descendants of the same top-level window. These restrictions are necessary to guarantee that \fIwindow\fR is visible whenever \fIcontainer\fR is visible. If this option is not specified then the other window defaults to \fIwindow\fR's parent. .\" OPTION: -relheight .TP \fB\-relheight \fIsize\fR . \fISize\fR specifies the height for \fIwindow\fR. In this case the height is specified as a floating-point number relative to the height of the container: 0.5 means \fIwindow\fR will be half as high as the container, 1.0 means \fIwindow\fR will have the same height as the container, and so on. If both \fB\-height\fR and \fB\-relheight\fR are specified for a content, their values are summed. For example, \fB\-relheight 1.0 \-height \-2\fR makes the content 2 pixels shorter than the container. .\" OPTION: -relwidth .TP \fB\-relwidth \fIsize\fR . \fISize\fR specifies the width for \fIwindow\fR. In this case the width is specified as a floating-point number relative to the width of the container: 0.5 means \fIwindow\fR will be half as wide as the container, 1.0 means \fIwindow\fR will have the same width as the container, and so on. If both \fB\-width\fR and \fB\-relwidth\fR are specified for a content, their values are summed. For example, \fB\-relwidth 1.0 \-width 5\fR makes the content 5 pixels wider than the container. .\" OPTION: -relx .TP \fB\-relx \fIlocation\fR . \fILocation\fR specifies the x-coordinate within the container window of the anchor point for \fIwindow\fR. In this case the location is specified in a relative fashion as a floating-point number: 0.0 corresponds to the left edge of the container and 1.0 corresponds to the right edge of the container. \fILocation\fR need not be in the range 0.0\-1.0. If both \fB\-x\fR and \fB\-relx\fR are specified for a content then their values are summed. For example, \fB\-relx 0.5 \-x \-2\fR positions the left edge of the content 2 pixels to the left of the center of its container. .\" OPTION: -rely .TP \fB\-rely \fIlocation\fR . \fILocation\fR specifies the y-coordinate within the container window of the anchor point for \fIwindow\fR. In this case the value is specified in a relative fashion as a floating-point number: 0.0 corresponds to the top edge of the container and 1.0 corresponds to the bottom edge of the container. \fILocation\fR need not be in the range 0.0\-1.0. If both \fB\-y\fR and \fB\-rely\fR are specified for a content then their values are summed. For example, \fB\-rely 0.5 \-x 3\fR positions the top edge of the content 3 pixels below the center of its container. .\" OPTION: -width .TP \fB\-width \fIsize\fR . \fISize\fR specifies the width for \fIwindow\fR in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR). The width will be the outer width of \fIwindow\fR including its border, if any. If \fIsize\fR is an empty string, or if no \fB\-width\fR or \fB\-relwidth\fR option is specified, then the width requested internally by the window will be used. .\" OPTION: -x .TP \fB\-x \fIlocation\fR . \fILocation\fR specifies the x-coordinate within the container window of the anchor point for \fIwindow\fR. The location is specified in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR) and need not lie within the bounds of the container window. .\" OPTION: -y .TP \fB\-y \fIlocation\fR . \fILocation\fR specifies the y-coordinate within the container window of the anchor point for \fIwindow\fR. The location is specified in screen units (i.e. any of the forms accepted by \fBTk_GetPixels\fR) and need not lie within the bounds of the container window. .PP If the same value is specified separately with two different options, such as \fB\-x\fR and \fB\-relx\fR, then the most recent option is used and the older one is ignored. .RE .\" METHOD: content .TP \fBplace content \fIwindow\fR . Returns a list of all the content windows for which \fIwindow\fR is the container. If there is no content for \fIwindow\fR then an empty string is returned. .\" METHOD: forget .TP \fBplace forget \fIwindow\fR . Causes the placer to stop managing the geometry of \fIwindow\fR. As a side effect of this command \fIwindow\fR will be unmapped so that it does not appear on the screen. If \fIwindow\fR is not currently managed by the placer then the command has no effect. This command returns an empty string. .\" METHOD: info .TP \fBplace info \fIwindow\fR . Returns a list giving the current configuration of \fIwindow\fR. The list consists of \fIoption\-value\fR pairs in exactly the same form as might be specified to the \fBplace configure\fR command. .\" METHOD: slaves .TP \fBplace slaves \fIwindow\fR . Synonym for \fBplace content \fIwindow\fR. .PP If the configuration of a window has been retrieved with \fBplace info\fR, that configuration can be restored later by first using \fBplace forget\fR to erase any existing information for the window and then invoking \fBplace configure\fR with the saved information. .SH "FINE POINTS" .PP It is not necessary for the container window to be the parent of the content window. This feature is useful in at least two situations. First, for complex window layouts it means you can create a hierarchy of subwindows whose only purpose is to assist in the layout of the parent. The .QW "real children" of the parent (i.e. the windows that are significant for the application's user interface) can be children of the parent yet be placed inside the windows of the geometry-management hierarchy. This means that the path names of the .QW "real children" do not reflect the geometry-management hierarchy and users can specify options for the real children without being aware of the structure of the geometry-management hierarchy. .PP A second reason for having a container different than the content's parent is to tie two siblings together. For example, the placer can be used to force a window always to be positioned centered just below one of its siblings by specifying the configuration .CS \fB\-in \fIsibling\fB \-relx 0.5 \-rely 1.0 \-anchor n \-bordermode outside\fR .CE Whenever the sibling is repositioned in the future, the content will be repositioned as well. .PP Unlike many other geometry managers (such as the packer) the placer does not make any attempt to manipulate the geometry of the container windows or the parents of content windows (i.e. it does not set their requested sizes). To control the sizes of these windows, make them windows like frames and canvases that provide configuration options for this purpose. .SH EXAMPLE .PP Make the label occupy the middle bit of the toplevel, no matter how it is resized: .CS label .l -text "In the\enMiddle!" -bg black -fg white \fBplace\fR .l -relwidth .3 -relx .35 -relheight .3 -rely .35 .CE .SH "SEE ALSO" grid(n), pack(n) .SH KEYWORDS geometry manager, height, location, container, place, rubber sheet, content, width '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/popup.n0000644001000000100000000000273615105057705017146 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk_popup n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk_popup \- Post a popup menu .SH SYNOPSIS \fBtk_popup \fImenu x y \fR?\fIentry\fR? .BE .SH DESCRIPTION .PP This procedure posts a menu at a given position on the screen and configures Tk so that the menu and its cascaded children can be traversed with the mouse or the keyboard. \fIMenu\fR is the name of a menu widget and \fIx\fR and \fIy\fR are the root coordinates at which to display the menu. If \fIentry\fR is omitted or an empty string, the menu's upper left corner is positioned at the given point. Otherwise \fIentry\fR gives the index of an entry in \fImenu\fR and the menu will be positioned so that the entry is positioned over the given point. .SH EXAMPLE .PP How to attach a simple popup menu to a widget. .CS # Create a menu set m [menu .popupMenu] $m add command -label "Example 1" -command bell $m add command -label "Example 2" -command bell # Create something to attach it to pack [label .l -text "Click me!"] # Arrange for the menu to pop up when the label is clicked bind .l {\fBtk_popup\fR .popupMenu %X %Y} .CE .SH "SEE ALSO" bind(n), menu(n), tk_optionMenu(n) .SH KEYWORDS menu, popup '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/print.n0000644001000000100000000000434215105057705017132 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans.\" Text automatically generated by txt2man '\" '\" Copyright (c) 2021 Kevin Walzer/WordTech Communications LLC. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. .TH tk print n "" Tk "Tk Built-in Commands" .so man.macros .SH NAME print \- Print canvas and text widgets using native dialogs and APIs. .SH SYNOPSIS \fBtk print \fIwindow\fR . .SH DESCRIPTION .PP The \fBtk print\fR command posts a dialog that allows users to print output from the \fBcanvas\fR and \fBtext\fR widgets. The printing will be done using platform-native APIs and dialogs where available. .PP The \fBcanvas\fR widget has long supported PostScript export and both PostScript and text files can be sent directly to a printer on Unix-like systems using the .QW "lp" and .QW "lpr" Unix commands, and the \fBtk print\fR command does not supersede that functionality; it builds on it. The \fBtk print\fR command is a fuller implementation that uses native dialogs on macOS and Windows, and a Tk-based dialog that provides parallel functionality on X11. .SH PLATFORM NOTES .TP \fBmacOS\fR . The Mac implementation uses native print dialogs and relies on the underlying Common Unix Printing System (CUPS) to render text output from the text widget and PDF conversion of the canvas data to the printer or to a PDF file. .TP \fBWindows\fR . The Windows implementation is based on the GDI (Graphics Device Interface) API. Because there are slight differences in how GDI and Tk's \fBcanvas\fR widget display graphics, printed output from the \fBcanvas\fR on Windows may not be identical to screen rendering. .TP \fBX11\fR . The X11 implementation uses a Tk GUI to configure print jobs for sending to a printer via the .QW "lpr" or .QW "lp" commands. While these commands have a large number of parameters for configuring print jobs, printers vary widely in how they support these parameters. As a result, only printer selection and number of copies are configured as arguments to the print command; many aspects of print rendering, such as grayscale or color for the canvas, are instead configured when PostScript is generated. .SH "SEE ALSO" canvas(n), text(n), tk(n) .SH KEYWORDS print, output, graphics, text, canvas tk9.0.3/doc/QWinEvent.30000644001000000100000000000356515105057705017571 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_QueueWindowEvent 3 7.5 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CollapseMotionEvents, Tk_QueueWindowEvent \- Add a window event to the Tcl event queue .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_CollapseMotionEvents\fR(\fIdisplay, collapse\fR) .sp \fBTk_QueueWindowEvent\fR(\fIeventPtr, position\fR) .fi .SH ARGUMENTS .AS Tcl_QueuePosition position .AP Display *display in Display for which to control motion event collapsing. .AP int collapse in Indicates whether motion events should be collapsed or not. .AP XEvent *eventPtr in An event to add to the event queue. It is important that all unused fields of the structure be set to zero. .AP Tcl_QueuePosition position in Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, \fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR. .BE .SH DESCRIPTION .PP \fBTk_QueueWindowEvent\fR places a window event on Tcl's internal event queue for eventual servicing. It creates a Tcl_Event structure, copies the event into that structure, and calls \fBTcl_QueueEvent\fR to add the event to the queue. When the event is eventually removed from the queue it is processed just like all window events. .PP When multiple motion events are received for the same window in rapid succession, they are collapsed by default. This behavior can be controlled with \fBTk_CollapseMotionEvents\fR. \fBTk_CollapseMotionEvents\fR always returns the previous value for collapse behavior on the \fIdisplay\fR. .PP The \fIposition\fR argument to \fBTk_QueueWindowEvent\fR has the same significance as for \fBTcl_QueueEvent\fR; see the documentation for \fBTcl_QueueEvent\fR for details. .SH KEYWORDS callback, clock, handler, modal timeout, events tk9.0.3/doc/radiobutton.n0000644001000000100000000002762015105057705020334 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH radiobutton n 4.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME radiobutton \- Create and manipulate 'radiobutton' pick-one widgets .SH SYNOPSIS \fBradiobutton\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-disabledforeground \-padx \-activeforeground \-font \-pady \-anchor \-foreground \-relief \-background \-highlightbackground \-takefocus \-bitmap \-highlightcolor \-text \-borderwidth \-highlightthickness \-textvariable \-compound \-image \-underline \-cursor \-justify \-wraplength .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command Specifies a Tcl command to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. The button's global variable (\fB\-variable\fR option) will be updated before the command is invoked. .OP \-height height Height Specifies a desired height for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); for text it is in lines of text. If this option is not specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it. .OP \-indicatoron indicatorOn IndicatorOn Specifies whether or not the indicator should be drawn. Must be a proper boolean value. If false, the \fB\-relief\fR option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise. .OP \-offrelief offRelief OffRelief Specifies the relief for the checkbutton when the indicator is not drawn and the checkbutton is off. The default value is .QW raised . By setting this option to .QW flat and setting \fB\-indicatoron\fR to false and \fB\-overrelief\fR to .QW raised , the effect is achieved of having a flat button that raises on mouse-over and which is depressed when activated. This is the behavior typically exhibited by the Align-Left, Align-Right, and Center radiobuttons on the toolbar of a word-processor, for example. .OP \-overrelief overRelief OverRelief Specifies an alternative relief for the radiobutton, to be used when the mouse cursor is over the widget. This option can be used to make toolbar buttons, by configuring \fB\-relief flat \-overrelief raised\fR. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the radiobutton. The empty string is the default value. .OP \-selectcolor selectColor Background Specifies a background color to use when the button is selected. If \fBindicatorOn\fR is true then the color is used as the background for the indicator regardless of the select state. If \fB\-indicatoron\fR is false, this color is used as the background for the entire widget, in place of \fB\-background\fR or \fB\-activeBackground\fR, whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected. .OP \-selectimage selectImage SelectImage Specifies an image to display (in place of the \fB\-image\fR option) when the radiobutton is selected. This option is ignored unless the \fB\-image\fR option has been specified. .OP \-state state State Specifies one of three states for the radiobutton: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In normal state the radiobutton is displayed using the \fB\-foreground\fR and \fB\-background\fR options. The active state is typically used when the pointer is over the radiobutton. In active state the radiobutton is displayed using the \fB\-activeforeground\fR and \fB\-activebackground\fR options. Disabled state means that the radiobutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the \fB\-disabledforeground\fR and \fB\-background\fR options determine how the radiobutton is displayed. .OP \-tristateimage tristateImage TristateImage Specifies an image to display (in place of the \fB\-image\fR option) when the radiobutton is selected. This option is ignored unless the \fB\-image\fR option has been specified. .OP \-tristatevalue tristateValue Value Specifies the value that causes the radiobutton to display the multi-value selection, also known as the tri-state mode. Defaults to .QW "" . .OP \-value value Value Specifies value to store in the button's associated variable whenever this button is selected. .OP \-variable variable Variable Specifies the name of a global variable to set whenever this button is selected. Changes in this variable also cause the button to select or deselect itself. Defaults to the value \fBselectedButton\fR. .OP \-width width Width Specifies a desired width for the button. If an image or bitmap is being displayed in the button, the value is in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); for text it is in characters. If this option is not specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it. .BE .SH DESCRIPTION .PP The \fBradiobutton\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a radiobutton widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the radiobutton such as its colors, font, text, and initial relief. The \fBradiobutton\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A radiobutton is a widget that displays a textual string, bitmap or image and a diamond or circle called an \fIindicator\fR. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the \fB\-wraplength\fR option) and one of the characters may optionally be underlined using the \fB\-underline\fR option. A radiobutton has all of the behavior of a simple button: it can display itself in either of three different ways, according to the \fB\-state\fR option; it can be made to appear raised, sunken, or flat; it can be made to flash; and it invokes a Tcl command whenever mouse button 1 is clicked over the check button. .PP In addition, radiobuttons can be \fIselected\fR. If a radiobutton is selected, the indicator is normally drawn with a selected appearance, and a Tcl variable associated with the radiobutton is set to a particular value (normally 1). Under Unix, the indicator is drawn with a sunken relief and a special color. Under Windows, the indicator is drawn with a round mark inside. If the radiobutton is not selected, then the indicator is drawn with a deselected appearance, and the associated variable is set to a different value (typically 0). The indicator is drawn without a round mark inside. Typically, several radiobuttons share a single variable and the value of the variable indicates which radiobutton is to be selected. When a radiobutton is selected it sets the value of the variable to indicate that fact; each radiobutton also monitors the value of the variable and automatically selects and deselects itself when the variable's value changes. If the variable's value matches the \fB\-tristatevalue\fR, then the radiobutton is drawn using the tri-state mode. This mode is used to indicate mixed or multiple values. (This is used when the radiobutton represents the state of multiple items.) By default the variable \fBselectedButton\fR is used; its contents give the name of the button that is selected, or the empty string if no button associated with that variable is selected. The name of the variable for a radiobutton, plus the variable to be stored into it, may be modified with options on the command line or in the option database. Configuration options may also be used to modify the way the indicator is displayed (or whether it is displayed at all). By default a radiobutton is configured to select itself on button clicks. .SH "WIDGET COMMAND" .PP The \fBradiobutton\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for radiobutton widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR command. .\" METHOD: deselect .TP \fIpathName \fBdeselect\fR . Deselects the radiobutton and sets the associated variable to an empty string. If this radiobutton was not currently selected, the command has no effect. .\" METHOD: flash .TP \fIpathName \fBflash\fR . Flashes the radiobutton. This is accomplished by redisplaying the radiobutton several times, alternating between active and normal colors. At the end of the flash the radiobutton is left in the same normal/active state as when the command was invoked. This command is ignored if the radiobutton's state is \fBdisabled\fR. .\" METHOD: invoke .TP \fIpathName \fBinvoke\fR . Does just what would have happened if the user invoked the radiobutton with the mouse: selects the button and invokes its associated Tcl command, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the radiobutton. This command is ignored if the radiobutton's state is \fBdisabled\fR. .\" METHOD: select .TP \fIpathName \fBselect\fR . Selects the radiobutton and sets the associated variable to the value corresponding to this widget. .SH BINDINGS .PP Tk automatically creates class bindings for radiobuttons that give them the following default behavior: .IP [1] On Unix systems, a radiobutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the radiobutton. On Mac and Windows systems, when mouse button 1 is pressed over a radiobutton, the button activates whenever the mouse pointer is inside the button, and deactivates whenever the mouse pointer leaves the button. .IP [2] When mouse button 1 is pressed over a radiobutton it is invoked (it becomes selected and the command associated with the button is invoked, if there is one). .IP [3] When a radiobutton has the input focus, the space key causes the radiobutton to be invoked. .PP If the radiobutton's state is \fBdisabled\fR then none of the above actions occur: the radiobutton is completely non-responsive. .PP The behavior of radiobuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "SEE ALSO" checkbutton(n), labelframe(n), listbox(n), options(n), scale(n), ttk::radiobutton(n) .SH KEYWORDS radiobutton, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/raise.n0000644001000000100000000000366615105057705017111 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH raise n 3.3 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME raise \- Change a window's position in the stacking order .SH SYNOPSIS \fBraise \fIwindow \fR?\fIaboveThis\fR? .BE .SH DESCRIPTION .PP If the \fIaboveThis\fR argument is omitted then the command raises \fIwindow\fR so that it is above all of its siblings in the stacking order (it will not be obscured by any siblings and will obscure any siblings that overlap it). If \fIaboveThis\fR is specified then it must be the path name of a window that is either a sibling of \fIwindow\fR or the descendant of a sibling of \fIwindow\fR. In this case the \fBraise\fR command will insert \fIwindow\fR into the stacking order just above \fIaboveThis\fR (or the ancestor of \fIaboveThis\fR that is a sibling of \fIwindow\fR); this could end up either raising or lowering \fIwindow\fR. .PP All \fBtoplevel\fR windows may be restacked with respect to each other, whatever their relative path names, but the window manager is not obligated to strictly honor requests to restack. .PP On macOS raising an iconified \fBtoplevel\fR window causes it to be deiconified. .SH EXAMPLE .PP Make a button appear to be in a sibling frame that was created after it. This is is often necessary when building GUIs in the style where you create your activity widgets first before laying them out on the display: .CS button .b -text "Hi there!" pack [frame .f -background blue] pack [label .f.l1 -text "This is above"] pack .b -in .f pack [label .f.l2 -text "This is below"] \fBraise\fR .b .CE .SH "SEE ALSO" lower(n) .SH KEYWORDS obscure, raise, stacking order '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/Restack.30000644001000000100000000000304415105057705017275 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_RestackWindow 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_RestackWindow \- Change a window's position in the stacking order .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_RestackWindow\fR(\fItkwin, aboveBelow, other\fR) .fi .SH ARGUMENTS .AS Tk_Window aboveBelow .AP Tk_Window tkwin in Token for window to restack. .AP int aboveBelow in Indicates new position of \fItkwin\fR relative to \fIother\fR; must be \fBAbove\fR or \fBBelow\fR. .AP Tk_Window other in \fITkwin\fR will be repositioned just above or below this window. Must be a sibling of \fItkwin\fR or a descendant of a sibling. If NULL then \fItkwin\fR is restacked above or below all siblings. .BE .SH DESCRIPTION .PP \fBTk_RestackWindow\fR changes the stacking order of \fIwindow\fR relative to its siblings. If \fIother\fR is specified as NULL then \fIwindow\fR is repositioned at the top or bottom of its stacking order, depending on whether \fIaboveBelow\fR is \fBAbove\fR or \fBBelow\fR. If \fIother\fR has a non-NULL value then \fIwindow\fR is repositioned just above or below \fIother\fR. .PP The \fIaboveBelow\fR argument must have one of the symbolic values \fBAbove\fR or \fBBelow\fR. Both of these values are defined by the include file . .SH KEYWORDS above, below, obscure, stacking order tk9.0.3/doc/RestrictEv.30000644001000000100000000000657115105057705020003 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_RestrictEvents 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_RestrictEvents \- filter and selectively delay X events .SH SYNOPSIS .nf \fB#include \fR .sp Tk_RestrictProc * \fBTk_RestrictEvents\fR(\fIproc, arg, prevArgPtr\fR) .fi .SH ARGUMENTS .AS Tk_RestrictProc **prevArgPtr .AP Tk_RestrictProc *proc in Predicate procedure to call to filter incoming X events. NULL means do not restrict events at all. .AP void *arg in Arbitrary argument to pass to \fIproc\fR. .AP void **prevArgPtr out Pointer to place to save argument to previous restrict procedure. .BE .SH DESCRIPTION .PP This procedure is useful in certain situations where applications are only prepared to receive certain X events. After \fBTk_RestrictEvents\fR is called, \fBTcl_DoOneEvent\fR (and hence \fBTk_MainLoop\fR) will filter X input events through \fIproc\fR. \fIProc\fR indicates whether a given event is to be processed immediately, deferred until some later time (e.g. when the event restriction is lifted), or discarded. \fIProc\fR is a procedure with arguments and result that match the type \fBTk_RestrictProc\fR: .CS typedef Tk_RestrictAction \fBTk_RestrictProc\fR( void *\fIarg\fR, XEvent *\fIeventPtr\fR); .CE The \fIarg\fR argument is a copy of the \fIarg\fR passed to \fBTk_RestrictEvents\fR; it may be used to provide \fIproc\fR with information it needs to filter events. The \fIeventPtr\fR points to an event under consideration. \fIProc\fR returns a restrict action (enumerated type \fBTk_RestrictAction\fR) that indicates what \fBTcl_DoOneEvent\fR should do with the event. If the return value is \fBTK_PROCESS_EVENT\fR, then the event will be handled immediately. If the return value is \fBTK_DEFER_EVENT\fR, then the event will be left on the event queue for later processing. If the return value is \fBTK_DISCARD_EVENT\fR, then the event will be removed from the event queue and discarded without being processed. .PP \fBTk_RestrictEvents\fR uses its return value and \fIprevArgPtr\fR to return information about the current event restriction procedure (a NULL return value means there are currently no restrictions). These values may be used to restore the previous restriction state when there is no longer any need for the current restriction. .PP There are very few places where \fBTk_RestrictEvents\fR is needed. In most cases, the best way to restrict events is by changing the bindings with the \fBbind\fR Tcl command or by calling \fBTk_CreateEventHandler\fR and \fBTk_DeleteEventHandler\fR from C. The main place where \fBTk_RestrictEvents\fR must be used is when performing synchronous actions (for example, if you need to wait for a particular event to occur on a particular window but you do not want to invoke any handlers for any other events). The .QW obvious solution in these situations is to call \fBXNextEvent\fR or \fBXWindowEvent\fR, but these procedures cannot be used because Tk keeps its own event queue that is separate from the X event queue. Instead, call \fBTk_RestrictEvents\fR to set up a filter, then call \fBTcl_DoOneEvent\fR to retrieve the desired event(s). .SH KEYWORDS delay, event, filter, restriction tk9.0.3/doc/scale.n0000644001000000100000000002534415105057705017072 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH scale n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME scale \- Create and manipulate 'scale' value-controlled slider widgets .SH SYNOPSIS \fBscale\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-foreground \-relief \-background \-highlightbackground \-repeatdelay \-borderwidth \-highlightcolor \-repeatinterval \-cursor \-highlightthickness \-takefocus \-font \-orient \-troughcolor .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-bigincrement bigIncrement BigIncrement Some interactions with the scale cause its value to change by .QW large increments; this option specifies the size of the large increments. If specified as 0, the large increments default to 1/10 the range of the scale. .OP \-command command Command Specifies the prefix of a Tcl command to invoke whenever the scale's value is changed via a widget command. The actual command consists of this option followed by a space and a real number indicating the new value of the scale. .OP \-digits digits Digits An integer specifying how many significant digits should be retained when converting the value of the scale to a string. If the number is negative or zero, then the scale picks the smallest value that guarantees that every possible slider position prints as a different string. .OP \-from from From A real value corresponding to the left or top end of the scale. .OP \-label label Label A string to display as a label for the scale. For vertical scales the label is displayed just to the right of the top end of the scale. For horizontal scales the label is displayed just above the left end of the scale. If the option is specified as an empty string, no label is displayed. .OP \-length length Length Specifies the desired long dimension of the scale in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR). For vertical scales this is the scale's height; for horizontal scales it is the scale's width. .OP \-resolution resolution Resolution A real value specifying the resolution for the scale. If this value is greater than zero then the scale's value will always be rounded to an even multiple of this value, as will the endpoints of the scale. If the value is negative then no rounding occurs. Defaults to 1 (i.e., the value will be integral). .OP \-showvalue showValue ShowValue Specifies a boolean value indicating whether or not the current value of the scale is to be displayed. .OP \-sliderlength sliderLength SliderLength Specifies the size of the slider, measured in screen units along the slider's long dimension. The value may be specified in any of the forms acceptable to \fBTk_GetPixels\fR. .OP \-sliderrelief sliderRelief SliderRelief Specifies the relief to use when drawing the slider, such as \fBraised\fR or \fBsunken\fR. .OP \-state state State Specifies one of three states for the scale: \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. If the scale is disabled then the value may not be changed and the scale will not activate. If the scale is active, the slider is displayed using the color specified by the \fB\-activebackground\fR option. .OP \-tickinterval tickInterval TickInterval Must be a real value. Determines the spacing between numerical tick marks displayed below or to the left of the slider. The values will all be displayed with the same number of decimal places, which will be enough to ensure they are all accurate to within 20% of a tick interval. If 0, no tick marks will be displayed. .OP \-to to To Specifies a real value corresponding to the right or bottom end of the scale. This value may be either less than or greater than the \fB\-from\fR option. .OP \-variable variable Variable Specifies the name of a global variable to link to the scale. Whenever the value of the variable changes, the scale will update to reflect this value. Whenever the scale is manipulated interactively, the variable will be modified to reflect the scale's new value. .OP \-width width Width Specifies the desired narrow dimension of the scale in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR). For vertical scales this is the scale's width; for horizontal scales this is the scale's height. .BE .SH DESCRIPTION .PP The \fBscale\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a scale widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the scale such as its colors, orientation, and relief. The \fBscale\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A scale is a widget that displays a rectangular \fItrough\fR and a small \fIslider\fR. The trough corresponds to a range of real values (determined by the \fB\-from\fR, \fB\-to\fR, and \fB\-resolution\fR options), and the position of the slider selects a particular real value. The slider's position (and hence the scale's value) may be adjusted with the mouse or keyboard as described in the \fBBINDINGS\fR section below. Whenever the scale's value is changed, a Tcl command is invoked (using the \fB\-command\fR option) to notify other interested widgets of the change. In addition, the value of the scale can be linked to a Tcl variable (using the \fB\-variable\fR option), so that changes in either are reflected in the other. .PP Three annotations may be displayed in a scale widget: a label appearing at the top right of the widget (top left for horizontal scales), a number displayed just to the left of the slider (just above the slider for horizontal scales), and a collection of numerical tick marks just to the left of the current value (just below the trough for horizontal scales). Each of these three annotations may be enabled or disabled using the configuration options. .SH "WIDGET COMMAND" .PP The \fBscale\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for scale widgets: .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBscale\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBscale\fR command. .\" METHOD: coords .TP \fIpathName \fBcoords \fR?\fIvalue\fR? . Returns a list whose elements are the x and y coordinates of the point along the centerline of the trough that corresponds to \fIvalue\fR. If \fIvalue\fR is omitted then the scale's current value is used. .\" METHOD: get .TP \fIpathName \fBget\fR ?\fIx y\fR? . If \fIx\fR and \fIy\fR are omitted, returns the current value of the scale. If \fIx\fR and \fIy\fR are specified, they give pixel coordinates within the widget; the command returns the scale value corresponding to the given pixel. Only one of \fIx\fR or \fIy\fR is used: for horizontal scales \fIy\fR is ignored, and for vertical scales \fIx\fR is ignored. .\" METHOD: identify .TP \fIpathName \fBidentify \fIx y\fR . Returns a string indicating what part of the scale lies under the coordinates given by \fIx\fR and \fIy\fR. A return value of \fBslider\fR means that the point is over the slider; \fBtrough1\fR means that the point is over the portion of the slider above or to the left of the slider; and \fBtrough2\fR means that the point is over the portion of the slider below or to the right of the slider. If the point is not over one of these elements, an empty string is returned. .\" METHOD: set .TP \fIpathName \fBset \fIvalue\fR . This command is invoked to change the current value of the scale, and hence the position at which the slider is displayed. \fIValue\fR gives the new value for the scale. The command has no effect if the scale is disabled. .SH BINDINGS .PP Tk automatically creates class bindings for scales that give them the following default behavior. Where the behavior is different for vertical and horizontal scales, the horizontal behavior is described in parentheses. .IP [1] If button 1 is pressed in the trough, the scale's value will be incremented or decremented by the value of the \fB\-resolution\fR option so that the slider moves in the direction of the cursor. If the button is held down, the action auto-repeats. .IP [2] If button 1 is pressed over the slider, the slider can be dragged with the mouse. .IP [3] If button 1 is pressed in the trough with the Control key down, the slider moves all the way to the end of its range, in the direction towards the mouse cursor. .IP [4] If button 2 is pressed, the scale's value is set to the mouse position. If the mouse is dragged with button 2 down, the scale's value changes with the drag. .IP [5] The Up and Left keys move the slider up (left) by the value of the \fB\-resolution\fR option. .IP [6] The Down and Right keys move the slider down (right) by the value of the \fB\-resolution\fR option. .IP [7] Control-Up and Control-Left move the slider up (left) by the value of the \fB\-bigincrement\fR option. .IP [8] Control-Down and Control-Right move the slider down (right) by the value of the \fB\-bigincrement\fR option. .IP [9] Home moves the slider to the top (left) end of its range. .IP [10] End moves the slider to the bottom (right) end of its range. .PP If the scale is disabled using the \fB\-state\fR option then none of the above bindings have any effect. .PP The behavior of scales can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "SEE ALSO" ttk::scale(n) .SH KEYWORDS scale, slider, trough, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/scrollbar.n0000644001000000100000000003301015105057705017753 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH scrollbar n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME scrollbar \- Create and manipulate 'scrollbar' scrolling control and indicator widgets .SH SYNOPSIS \fBscrollbar\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-highlightcolor \-repeatdelay \-background \-highlightthickness \-repeatinterval \-borderwidth \-jump \-takefocus \-cursor \-orient \-troughcolor \-highlightbackground \-relief .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-activerelief activeRelief ActiveRelief Specifies the relief to use when displaying the element that is active, if any. Elements other than the active element are always displayed with a raised relief. .OP \-command command Command Specifies the prefix of a Tcl command to invoke to change the view in the widget associated with the scrollbar. When a user requests a view change by manipulating the scrollbar, a Tcl command is invoked. The actual command consists of this option followed by additional information as described later. This option almost always has a value such as \fB.t xview\fR or \fB.t yview\fR, consisting of the name of a widget and either \fBxview\fR (if the scrollbar is for horizontal scrolling) or \fByview\fR (for vertical scrolling). All scrollable widgets have \fBxview\fR and \fByview\fR commands that take exactly the additional arguments appended by the scrollbar as described in \fBSCROLLING COMMANDS\fR below. .OP \-elementborderwidth elementBorderWidth BorderWidth Specifies the width of borders drawn around the internal elements of the scrollbar (the two arrows and the slider). The value may have any of the forms acceptable to \fBTk_GetPixels\fR. If this value is the empty string (the default), the value of the \fB\-borderwidth\fR option is used in its place. .OP \-width width Width Specifies the desired narrow dimension of the scrollbar window, not including 3-D border, if any. For vertical scrollbars this will be the width and for horizontal scrollbars this will be the height. The value may have any of the forms acceptable to \fBTk_GetPixels\fR. .BE .SH DESCRIPTION .PP The \fBscrollbar\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a scrollbar widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the scrollbar such as its colors, orientation, and relief. The \fBscrollbar\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A scrollbar is a widget that displays two arrows, one at each end of the scrollbar, and a \fIslider\fR in the middle portion of the scrollbar. It provides information about what is visible in an \fIassociated window\fR that displays a document of some sort (such as a file being edited or a drawing). The position and size of the slider indicate which portion of the document is visible in the associated window. For example, if the slider in a vertical scrollbar covers the top third of the area between the two arrows, it means that the associated window displays the top third of its document. .PP Scrollbars can be used to adjust the view in the associated window by clicking or dragging with the mouse. See the \fBBINDINGS\fR section below for details. .SH "ELEMENTS" .PP A scrollbar displays five elements, which are referred to in the widget commands for the scrollbar: .IP \fBarrow1\fR 10 The top or left arrow in the scrollbar. .IP \fBtrough1\fR 10 The region between the slider and \fBarrow1\fR. .IP \fBslider\fR 10 The rectangle that indicates what is visible in the associated widget. .IP \fBtrough2\fR 10 The region between the slider and \fBarrow2\fR. .IP \fBarrow2\fR 10 The bottom or right arrow in the scrollbar. .SH "WIDGET COMMAND" .PP The \fBscrollbar\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for scrollbar widgets: .\" METHOD: activate .TP \fIpathName \fBactivate \fR?\fIelement\fR? . Marks the element indicated by \fIelement\fR as active, which causes it to be displayed as specified by the \fB\-activebackground\fR and \fB\-activerelief\fR options. The only element values understood by this command are \fBarrow1\fR, \fBslider\fR, or \fBarrow2\fR. If any other value is specified then no element of the scrollbar will be active. If \fIelement\fR is not specified, the command returns the name of the element that is currently active, or an empty string if no element is active. .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBscrollbar\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBscrollbar\fR command. .\" METHOD: delta .TP \fIpathName \fBdelta \fIdeltaX deltaY\fR . Returns a real number indicating the fractional change in the scrollbar setting that corresponds to a given change in slider position. For example, if the scrollbar is horizontal, the result indicates how much the scrollbar setting must change to move the slider \fIdeltaX\fR pixels to the right (\fIdeltaY\fR is ignored in this case). If the scrollbar is vertical, the result indicates how much the scrollbar setting must change to move the slider \fIdeltaY\fR pixels down. The arguments and the result may be zero or negative. .\" METHOD: fraction .TP \fIpathName \fBfraction \fIx y\fR . Returns a real number between 0 and 1 indicating where the point given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar. The value 0 corresponds to the top or left of the trough, the value 1 corresponds to the bottom or right, 0.5 corresponds to the middle, and so on. \fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar widget. If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest point in the trough is used. .\" METHOD: get .TP \fIpathName \fBget\fR . Returns the scrollbar settings in the form of a list whose elements are the arguments to the most recent \fBset\fR widget command. .\" METHOD: identify .TP \fIpathName \fBidentify \fIx y\fR . Returns the name of the element under the point given by \fIx\fR and \fIy\fR (such as \fBarrow1\fR), or an empty string if the point does not lie in any element of the scrollbar. \fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar widget. .\" METHOD: set .TP \fIpathName \fBset \fIfirst last\fR . This command is invoked by the scrollbar's associated widget to tell the scrollbar about the current view in the widget. The command takes two arguments, each of which is a real fraction between 0 and 1. The fractions describe the range of the document that is visible in the associated widget. For example, if \fIfirst\fR is 0.2 and \fIlast\fR is 0.4, it means that the first part of the document visible in the window is 20% of the way through the document, and the last visible part is 40% of the way through. .SH "SCROLLING COMMANDS" .PP When the user interacts with the scrollbar, for example by dragging the slider, the scrollbar notifies the associated widget that it must change its view. The scrollbar makes the notification by evaluating a Tcl command generated from the scrollbar's \fB\-command\fR option. The command may take any of the following forms. In each case, \fIprefix\fR is the contents of the \fB\-command\fR option, which usually has a form like .QW "\fB.t yview\fR" . .\" METHOD: moveto .TP \fIprefix \fBmoveto \fIfraction\fR . \fIFraction\fR is a real number between 0 and 1. The widget should adjust its view so that the point given by \fIfraction\fR appears at the beginning of the widget. If \fIfraction\fR is 0 it refers to the beginning of the document. 1.0 refers to the end of the document, 0.333 refers to a point one-third of the way through the document, and so on. .\" METHOD: scroll .TP \fIprefix \fBscroll \fInumber \fBpages\fR . The widget should adjust its view by \fInumber\fR pages. It is up to the widget to define the meaning of a page; typically it is slightly less than what fits in the window, so that there is a slight overlap between the old and new views. \fINumber\fR is either 1, which means the next page should become visible, or \-1, which means that the previous page should become visible. Fractional numbers are rounded away from 0, so scrolling 0.001 pages has the same effect as scrolling 1 page. .TP \fIprefix \fBscroll \fInumber \fBunits\fR . The widget should adjust its view by \fInumber\fR units. The units are defined in whatever way makes sense for the widget, such as characters or lines in a text widget. \fINumber\fR is either 1, which means one unit should scroll off the top or left of the window, or \-1, which means that one unit should scroll off the bottom or right of the window. Fractional numbers are rounded away from 0, so scrolling 0.001 units has the same effect as scrolling 1 unit. .SH BINDINGS .PP Tk automatically creates class bindings for scrollbars that give them the following default behavior. If the behavior is different for vertical and horizontal scrollbars, the horizontal behavior is described in parentheses. .IP [1] Pressing button 1 over \fBarrow1\fR causes the view in the associated widget to shift up (left) by one unit so that the document appears to move down (right) one unit. If the button is held down, the action auto-repeats. .IP [2] Pressing button 1 over \fBtrough1\fR causes the view in the associated widget to shift up (left) by one screenful so that the document appears to move down (right) one screenful. If the button is held down, the action auto-repeats. .IP [3] Pressing button 1 over the slider and dragging causes the view to drag with the slider. If the \fBjump\fR option is true, then the view does not drag along with the slider; it changes only when the mouse button is released. .IP [4] Pressing button 1 over \fBtrough2\fR causes the view in the associated widget to shift down (right) by one screenful so that the document appears to move up (left) one screenful. If the button is held down, the action auto-repeats. .IP [5] Pressing button 1 over \fBarrow2\fR causes the view in the associated widget to shift down (right) by one unit so that the document appears to move up (left) one unit. If the button is held down, the action auto-repeats. .IP [6] If button 2 is pressed over the trough or the slider, it sets the view to correspond to the mouse position; dragging the mouse with button 2 down causes the view to drag with the mouse. If button 2 is pressed over one of the arrows, it causes the same behavior as pressing button 1. .IP [7] If button 1 is pressed with the Control key down, then if the mouse is over \fBarrow1\fR or \fBtrough1\fR the view changes to the very top (left) of the document; if the mouse is over \fBarrow2\fR or \fBtrough2\fR the view changes to the very bottom (right) of the document; if the mouse is anywhere else then the button press has no effect. .IP [8] In vertical scrollbars the Up and Down keys have the same behavior as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively. In horizontal scrollbars these keys have no effect. .IP [9] In vertical scrollbars Control-Up and Control-Down have the same behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. In horizontal scrollbars these keys have no effect. .IP [10] In horizontal scrollbars the Up and Down keys have the same behavior as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively. In vertical scrollbars these keys have no effect. .IP [11] In horizontal scrollbars Control-Up and Control-Down have the same behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. In vertical scrollbars these keys have no effect. .IP [12] The Prior and Next keys have the same behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. .IP [13] The Home key adjusts the view to the top (left edge) of the document. .IP [14] The End key adjusts the view to the bottom (right edge) of the document. .SH EXAMPLE .PP Create a window with a scrollable \fBtext\fR widget: .CS toplevel .tl text .tl.t -yscrollcommand {.tl.s set} \fBscrollbar\fR .tl.s -command {.tl.t yview} grid .tl.t .tl.s -sticky nsew grid columnconfigure .tl 0 -weight 1 grid rowconfigure .tl 0 -weight 1 .CE .SH "SEE ALSO" ttk::scrollbar(n) .SH KEYWORDS scrollbar, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/selection.n0000644001000000100000000002355715105057705017774 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH selection n 8.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME selection \- Manipulate the X selection .SH SYNOPSIS \fBselection \fIoption\fR ?\fIarg ...\fR? .BE .SH DESCRIPTION .PP This command provides a Tcl interface to the X selection mechanism and implements the full selection functionality described in the X Inter-Client Communication Conventions Manual (ICCCM). .PP Note that for management of the \fBCLIPBOARD\fR selection (see below), the \fBclipboard\fR command may also be used. .PP The first argument to \fBselection\fR determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported: .\" METHOD: clear .TP \fBselection clear\fR ?\fB\-displayof\fI window\fR? ?\fB\-selection\fI selection\fR? . If \fIselection\fR exists anywhere on \fIwindow\fR's display, clear it so that no window owns the selection anymore. \fISelection\fR specifies the X selection that should be cleared, and should be an atom name such as \fBPRIMARY\fR or \fBCLIPBOARD\fR; see the Inter-Client Communication Conventions Manual for complete details. \fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . Returns an empty string. .\" METHOD: get .TP \fBselection get\fR ?\fB\-displayof\fI window\fR? ?\fB\-selection\fI selection\fR? ?\fB\-type\fI type\fR? . Retrieves the value of \fIselection\fR from \fIwindow\fR's display and returns it as a result. \fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . \fIType\fR specifies the form in which the selection is to be returned (the desired .QW target for conversion, in ICCCM terminology), and should be an atom name such as \fBSTRING\fR or \fBFILE_NAME\fR; see the Inter-Client Communication Conventions Manual for complete details. \fIType\fR defaults to \fBSTRING\fR. The selection owner may choose to return the selection in any of several different representation formats, such as \fBSTRING\fR, \fBUTF8_STRING\fR, \fBATOM\fR, \fBINTEGER\fR, etc. (this format is different than the selection type; see the ICCCM for all the confusing details). If the selection is returned in a non-string format, such as \fBINTEGER\fR or \fBATOM\fR, the \fBselection\fR command converts it to string format as a collection of fields separated by spaces: atoms are converted to their textual names, and anything else is converted to hexadecimal integers. Note that \fBselection get\fR does not retrieve the selection in the \fBUTF8_STRING\fR format unless told to. .\" METHOD: handle .TP \fBselection handle\fR ?\fB\-selection\fI s\fR? ?\fB\-type\fI t\fR? ?\fB\-format\fI f\fR? \fIwindow command\fR . Creates a handler for selection requests, such that \fIcommand\fR will be executed whenever selection \fIs\fR is owned by \fIwindow\fR and someone attempts to retrieve it in the form given by type \fIt\fR (e.g. \fIt\fR is specified in the \fBselection get\fR command). \fIS\fR defaults to \fBPRIMARY\fR, \fIt\fR defaults to \fBSTRING\fR, and \fIf\fR defaults to \fBSTRING\fR. If \fIcommand\fR is an empty string then any existing handler for \fIwindow\fR, \fIt\fR, and \fIs\fR is removed. Note that when the selection is handled as type \fBSTRING\fR it is also automatically handled as type \fBUTF8_STRING\fR as well. .RS .PP When \fIselection\fR is requested, \fIwindow\fR is the selection owner, and \fItype\fR is the requested type, \fIcommand\fR will be executed as a Tcl command with two additional numbers appended to it (with space separators). The two additional numbers are \fIoffset\fR and \fImaxChars\fR: \fIoffset\fR specifies a starting character position in the selection and \fImaxChars\fR gives the maximum number of characters to retrieve. The command should return a value consisting of at most \fImaxChars\fR of the selection, starting at position \fIoffset\fR. For very large selections (larger than \fImaxChars\fR) the selection will be retrieved using several invocations of \fIcommand\fR with increasing \fIoffset\fR values. If \fIcommand\fR returns a string whose length is less than \fImaxChars\fR, the return value is assumed to include all of the remainder of the selection; if the length of \fIcommand\fR's result is equal to \fImaxChars\fR then \fIcommand\fR will be invoked again, until it eventually returns a result shorter than \fImaxChars\fR. The value of \fImaxChars\fR will always be relatively large (thousands of characters). .PP If \fIcommand\fR returns an error then the selection retrieval is rejected just as if the selection did not exist at all. .PP The \fIformat\fR argument specifies the representation that should be used to transmit the selection to the requester (the second column of Table 2 of the ICCCM), and defaults to \fBSTRING\fR. If \fIformat\fR is \fBSTRING\fR, the selection is transmitted as 8-bit ASCII characters (i.e. just in the form returned by \fIcommand\fR, in the system \fBencoding\fR; the \fBUTF8_STRING\fR format always uses UTF-8 as its encoding). If \fIformat\fR is \fBATOM\fR, then the return value from \fIcommand\fR is divided into fields separated by white space; each field is converted to its atom value, and the 32-bit atom value is transmitted instead of the atom name. For any other \fIformat\fR, the return value from \fIcommand\fR is divided into fields separated by white space and each field is converted to a 32-bit integer; an array of integers is transmitted to the selection requester. .PP The \fIformat\fR argument is needed only for compatibility with selection requesters that do not use Tk. If Tk is being used to retrieve the selection then the value is converted back to a string at the requesting end, so \fIformat\fR is irrelevant. .RE .\" METHOD: own .TP \fBselection own\fR ?\fB\-displayof\fI window\fR? ?\fB\-selection\fI selection\fR? .TP \fBselection own\fR ?\fB\-command\fI command\fR? ?\fB\-selection\fI selection\fR? \fIwindow\fR . The first form of \fBselection own\fR returns the path name of the window in this application that owns \fIselection\fR on the display containing \fIwindow\fR, or an empty string if no window in this application owns the selection. \fISelection\fR defaults to \fBPRIMARY\fR and \fIwindow\fR defaults to .QW . . .RS .PP The second form of \fBselection own\fR causes \fIwindow\fR to become the new owner of \fIselection\fR on \fIwindow\fR's display, returning an empty string as result. The existing owner, if any, is notified that it has lost the selection. If \fIcommand\fR is specified, it is a Tcl script to execute when some other window claims ownership of the selection away from \fIwindow\fR. \fISelection\fR defaults to PRIMARY. .RE .SH WIDGET FACILITIES .PP The \fBtext\fR, \fBentry\fR, \fBttk::entry\fR, \fBlistbox\fR, \fBspinbox\fR and \fBttk::spinbox\fR widgets have the option \fB\-exportselection\fR. If a widget has this option set to boolean \fBtrue\fR, then (in an unsafe interpreter) a selection made in the widget is automatically written to the \fBPRIMARY\fR selection. .PP A GUI event, for example \fB<>\fR, can copy the \fBPRIMARY\fR selection to certain widgets. This copy is implemented by a widget binding to the event. The binding script makes appropriate calls to the \fBselection\fR command. .PP .SH PORTABILITY ISSUES .PP On X11, the \fBPRIMARY\fR selection is a system-wide feature of the X server, allowing communication between different processes that are X11 clients. .PP On Windows, the \fBPRIMARY\fR selection is not provided by the system, but only by Tk, and so it is shared only between windows of a parent interpreter and its child interpreters. It is not shared between interpreters in different processes or different threads. Each parent interpreter has a separate \fBPRIMARY\fR selection that is shared only with its child interpreters which are not safe interpreters. .PP .SH SECURITY .PP A safe interpreter cannot read from the \fBPRIMARY\fR selection because its \fBselection\fR command is hidden. For this reason the \fBPRIMARY\fR selection cannot be written to the Tk widgets of a safe interpreter. .PP A Tk widget can have its option \fB\-exportselection\fR set to boolean \fBtrue\fR, but in a safe interpreter this option has no effect: writing from the widget to the \fBPRIMARY\fR selection is disabled. .PP These are security features. A safe interpreter may run untrusted code, and it is a security risk if this untrusted code can read or write the \fBPRIMARY\fR selection used by other interpreters. .PP .SH EXAMPLES .PP On X11 platforms, one of the standard selections available is the \fBSECONDARY\fR selection. Hardly anything uses it, but here is how to read it using Tk: .PP .CS set selContents [\fBselection get\fR -selection SECONDARY] .CE .PP Many different types of data may be available for a selection; the special type \fBTARGETS\fR allows you to get a list of available types: .PP .CS foreach type [\fBselection get\fR -type TARGETS] { puts "Selection PRIMARY supports type $type" } .CE .PP To claim the selection, you must first set up a handler to supply the data for the selection. Then you have to claim the selection... .CS # Set up the data handler ready for incoming requests set foo "This is a string with some data in it... blah blah" \fBselection handle\fR -selection SECONDARY . getData proc getData {offset maxChars} { puts "Retrieving selection starting at $offset" return [string range $::foo $offset [expr {$offset+$maxChars-1}]] } # Now we grab the selection itself puts "Claiming selection" \fBselection own\fR -command lost -selection SECONDARY . proc lost {} { puts "Lost selection" } .CE .SH "SEE ALSO" clipboard(n) .SH KEYWORDS clear, format, handler, ICCCM, own, selection, target, type '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/send.n0000644001000000100000000001067215105057705016732 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH send n 4.0 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME send \- Execute a command in a different application .SH SYNOPSIS \fBsend ?\fIoptions\fR? \fIapp cmd \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP This command arranges for \fIcmd\fR (and \fIarg\fRs) to be executed in the application named by \fIapp\fR. It returns the result or error from that command execution. \fIApp\fR may be the name of any application whose main window is on the display containing the sender's main window; it need not be within the same process. If no \fIarg\fR arguments are present, then the command to be executed is contained entirely within the \fIcmd\fR argument. If one or more \fIarg\fRs are present, they are concatenated to form the command to be executed, just as for the \fBeval\fR command. .PP If the initial arguments of the command begin with .QW \- they are treated as options. The following options are currently defined: .\" OPTION: -async .TP \fB\-async\fR . Requests asynchronous invocation. In this case the \fBsend\fR command will complete immediately without waiting for \fIcmd\fR to complete in the target application; no result will be available and errors in the sent command will be ignored. If the target application is in the same process as the sending application then the \fB\-async\fR option is ignored. .\" OPTION: -displayof .TP \fB\-displayof\fI pathName\fR . Specifies that the target application's main window is on the display of the window given by \fIpathName\fR, instead of the display containing the application's main window. .\" OPTION: -- .TP \fB\-\|\-\fR . Serves no purpose except to terminate the list of options. This option is needed only if \fIapp\fR could contain a leading .QW \- character. .SH "APPLICATION NAMES" .PP The name of an application is set initially from the name of the program or script that created the application. You can query and change the name of an application with the \fBtk appname\fR command. .SH "DISABLING SENDS" .PP If the \fBsend\fR command is removed from an application (e.g. with the command \fBrename\fR \fBsend {}\fR) then the application will not respond to incoming send requests anymore, nor will it be able to issue outgoing requests. Communication can be reenabled by invoking the \fBtk appname\fR command. .SH SECURITY .PP The \fBsend\fR command is potentially a serious security loophole. On Unix, any application that can connect to your X server can send scripts to your applications. These incoming scripts can use Tcl to read and write your files and invoke subprocesses under your name. Host-based access control such as that provided by \fBxhost\fR is particularly insecure, since it allows anyone with an account on particular hosts to connect to your server, and if disabled it allows anyone anywhere to connect to your server. In order to provide at least a small amount of security, Tk checks the access control being used by the server and rejects incoming sends unless (a) \fBxhost\fR-style access control is enabled (i.e. only certain hosts can establish connections) and (b) the list of enabled hosts is empty. This means that applications cannot connect to your server unless they use some other form of authorization such as that provide by \fBxauth\fR. Under Windows, \fBsend\fR is currently disabled. Most of the functionality is provided by the \fBdde\fR command instead. .SH LIMITATIONS .PP Under macOS/aqua, the send command works only with interpreters that exist in the same process (these are returned by "winfo interps"). Invocations that target an interpreter that exists in another process don't accomplish anything. .SH EXAMPLE .PP This script fragment can be used to make an application that only runs once on a particular display. .CS if {[tk appname FoobarApp] ne "FoobarApp"} { \fBsend\fR -async FoobarApp RemoteStart $argv exit } # The command that will be called remotely, which raises # the application main window and opens the requested files proc RemoteStart args { raise . foreach filename $args { OpenFile $filename } } .CE .SH KEYWORDS application, dde, name, remote execution, security, send '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/SetAppName.30000644001000000100000000000442115105057705017676 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_SetAppName 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_SetAppName \- Set the name of an application for 'send' commands .SH SYNOPSIS .nf \fB#include \fR .sp const char * \fBTk_SetAppName\fR(\fItkwin, name\fR) .fi .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window in application. Used only to select a particular application. .AP "const char" *name in Name under which to register the application. .BE .SH DESCRIPTION .PP \fBTk_SetAppName\fR associates a name with a given application and records that association on the display containing with the application's main window. After this procedure has been invoked, other applications on the display will be able to use the \fBsend\fR command to invoke operations in the application. If \fIname\fR is already in use by some other application on the display, then a new name will be generated by appending .QW "\fB #2\fR" to \fIname\fR; if this name is also in use, the number will be incremented until an unused name is found. The return value from the procedure is a pointer to the name actually used. .PP If the application already has a name when \fBTk_SetAppName\fR is called, then the new name replaces the old name. .PP \fBTk_SetAppName\fR also adds a \fBsend\fR command to the application's interpreter, which can be used to send commands from this application to others on any of the displays where the application has windows. .PP The application's name registration persists until the interpreter is deleted or the \fBsend\fR command is deleted from \fIinterp\fR, at which point the name is automatically unregistered and the application becomes inaccessible via \fBsend\fR. The application can be made accessible again by calling \fBTk_SetAppName\fR. .PP \fBTk_SetAppName\fR is called automatically by \fBTk_Init\fR, so applications do not normally need to call it explicitly. .PP The command \fBtk appname\fR provides Tcl-level access to the functionality of \fBTk_SetAppName\fR. .SH KEYWORDS application, name, register, send command tk9.0.3/doc/SetCaret.30000644001000000100000000000174015105057705017414 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2002 ActiveState Corporation. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_SetCaretPos 3 8.4 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_SetCaretPos \- set the display caret location .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_SetCaretPos\fR(\fItkwin, x, y, height\fR) .fi .SH ARGUMENTS .AP Tk_Window tkwin in Token for window. .AP int x in Window-relative x coordinate. .AP int y in Window-relative y coordinate. .AP int h in Height of the caret in the window. .BE .SH DESCRIPTION .PP \fBTk_SetCaretPos\fR sets the caret location for the display of the specified Tk_Window \fItkwin\fR. The caret is the per-display cursor location used for indicating global focus (e.g. to comply with Microsoft Accessibility guidelines), as well as for location of the over-the-spot XIM (X Input Methods) or Windows IME windows. .SH KEYWORDS caret, cursor tk9.0.3/doc/SetClass.30000644001000000100000000000372115105057705017424 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_SetClass 3 "" Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_SetClass, Tk_Class \- set or retrieve a window's class .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_SetClass\fR(\fItkwin, class\fR) .sp Tk_Uid \fBTk_Class\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window parent .AP Tk_Window tkwin in Token for window. .AP char *class in New class name for window. .BE .SH DESCRIPTION .PP \fBTk_SetClass\fR is called to associate a class with a particular window. The \fIclass\fR string identifies the type of the window; all windows with the same general class of behavior (button, menu, etc.) should have the same class. By convention all class names start with a capital letter, and there exists a Tcl command with the same name as each class (except all in lower-case) which can be used to create and manipulate windows of that class. A window's class string is initialized to NULL when the window is created. .PP For main windows, Tk automatically propagates the name and class to the WM_CLASS property used by window managers. This happens either when a main window is actually created (e.g. in \fBTk_MakeWindowExist\fR), or when \fBTk_SetClass\fR is called, whichever occurs later. If a main window has not been assigned a class then Tk will not set the WM_CLASS property for the window. .PP \fBTk_Class\fR is a macro that returns the current value of \fItkwin\fR's class. The value is returned as a Tk_Uid, which may be used just like a string pointer but also has the properties of a unique identifier (see the manual entry for \fBTk_GetUid\fR for details). If \fItkwin\fR has not yet been given a class, then \fBTk_Class\fR will return NULL. .SH KEYWORDS class, unique identifier, window, window manager tk9.0.3/doc/SetClassProcs.30000644001000000100000000000626115105057705020435 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2000 Ajuba Solutions. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_SetClassProcs 3 8.4 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_SetClassProcs \- register widget specific procedures .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_SetClassProcs\fR(\fItkwin, procs, instanceData\fR) .fi .SH ARGUMENTS .AS Tk_ClassProc instanceData .AP Tk_Window tkwin in Token for window to modify. .AP "const Tk_ClassProcs" *procs in Pointer to data structure containing widget specific procedures. The data structure pointed to by \fIprocs\fR must be static: Tk keeps a reference to it as long as the window exists. .AP void *instanceData in Arbitrary one-word value to pass to widget callbacks. .BE .SH DESCRIPTION .PP \fBTk_SetClassProcs\fR is called to register a set of procedures that are used as callbacks in different places. .PP The structure pointed to by \fIprocs\fR contains the following: .CS typedef struct { Tcl_Size \fIsize\fR; Tk_ClassWorldChangedProc *\fIworldChangedProc\fR; Tk_ClassCreateProc *\fIcreateProc\fR; Tk_ClassModalProc *\fImodalProc\fR; } \fBTk_ClassProcs\fR; .CE The \fIsize\fR field is used to simplify future expansion of the structure. It should always be set to (literally) \fBsizeof(Tk_ClassProcs)\fR. .PP \fIworldChangedProc\fR is invoked when the system has altered in some way that requires some reaction from the widget. For example, when a font alias (see the \fBfont\fR manual entry) is reconfigured, widgets configured to use that font alias must update their display accordingly. \fIworldChangedProc\fR should have arguments and results that match the type \fBTk_ClassWorldChangedProc\fR: .CS typedef void \fBTk_ClassWorldChangedProc\fR( void *\fIinstanceData\fR); .CE The \fIinstanceData\fR parameter passed to the \fIworldChangedProc\fR will be identical to the \fIinstanceData\fR parameter passed to \fBTk_SetClassProcs\fR. .PP \fIcreateProc\fR is used to create platform-dependent windows. It is invoked by \fBTk_MakeWindowExist\fR. \fIcreateProc\fR should have arguments and results that match the type \fBTk_ClassCreateProc\fR: .CS typedef Window \fBTk_ClassCreateProc\fR( Tk_Window \fItkwin\fR, Window \fIparent\fR, void *\fIinstanceData\fR); .CE The \fItkwin\fR and \fIinstanceData\fR parameters will be identical to the \fItkwin\fR and \fIinstanceData\fR parameters passed to \fBTk_SetClassProcs\fR. The \fIparent\fR parameter will be the parent of the window to be created. The \fIcreateProc\fR should return the created window. .PP \fImodalProc\fR is invoked after all bindings on a widget have been triggered in order to handle a modal loop. \fImodalProc\fR should have arguments and results that match the type \fBTk_ClassModalProc\fR: .CS typedef void \fBTk_ClassModalProc\fR( Tk_Window \fItkwin\fR, XEvent *\fIeventPtr\fR); .CE The \fItkwin\fR parameter to \fImodalProc\fR will be identical to the \fItkwin\fR parameter passed to \fBTk_SetClassProcs\fR. The \fIeventPtr\fR parameter will be a pointer to an XEvent structure describing the event being processed. .SH KEYWORDS callback, class tk9.0.3/doc/SetGrid.30000644001000000100000000000442315105057705017244 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_SetGrid 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_SetGrid, Tk_UnsetGrid \- control the grid for interactive resizing .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_SetGrid\fR(\fItkwin, reqWidth, reqHeight, widthInc, heightInc\fR) .sp \fBTk_UnsetGrid\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window heightInc .AP Tk_Window tkwin in Token for window. .AP int reqWidth in Width in grid units that corresponds to the pixel dimension \fItkwin\fR has requested via \fBTk_GeometryRequest\fR. .AP int reqHeight in Height in grid units that corresponds to the pixel dimension \fItkwin\fR has requested via \fBTk_GeometryRequest\fR. .AP int widthInc in Width of one grid unit, in pixels. .AP int heightInc in Height of one grid unit, in pixels. .BE .SH DESCRIPTION .PP \fBTk_SetGrid\fR turns on gridded geometry management for \fItkwin\fR's toplevel window and specifies the geometry of the grid. \fBTk_SetGrid\fR is typically invoked by a widget when its \fBsetGrid\fR option is true. It restricts interactive resizing of \fItkwin\fR's toplevel window so that the space allocated to the toplevel is equal to its requested size plus or minus even multiples of \fIwidthInc\fR and \fIheightInc\fR. Furthermore, the \fIreqWidth\fR and \fIreqHeight\fR values are passed to the window manager so that it can report the window's size in grid units during interactive resizes. If \fItkwin\fR's configuration changes (e.g., the size of a grid unit changes) then the widget should invoke \fBTk_SetGrid\fR again with the new information. .PP \fBTk_UnsetGrid\fR cancels gridded geometry management for \fItkwin\fR's toplevel window. .PP For each toplevel window there can be at most one internal window with gridding enabled. If \fBTk_SetGrid\fR or \fBTk_UnsetGrid\fR is invoked when some other window is already controlling gridding for \fItkwin\fR's toplevel, the calls for the new window have no effect. .PP See the \fBwm\fR manual entry for additional information on gridded geometry management. .SH KEYWORDS grid, window, window manager tk9.0.3/doc/SetOptions.30000644001000000100000000010457215105057705020020 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions \- process configuration options .SH SYNOPSIS .nf \fB#include \fR .sp Tk_OptionTable \fBTk_CreateOptionTable\fR(\fIinterp, templatePtr\fR) .sp \fBTk_DeleteOptionTable\fR(\fIoptionTable\fR) .sp int \fBTk_InitOptions\fR(\fIinterp, recordPtr, optionTable, tkwin\fR) .sp int \fBTk_SetOptions\fR(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fR) .sp \fBTk_FreeSavedOptions\fR(\fIsavedPtr\fR) .sp \fBTk_RestoreSavedOptions\fR(\fIsavedPtr\fR) .sp Tcl_Obj * \fBTk_GetOptionValue\fR(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fR) .sp Tcl_Obj * \fBTk_GetOptionInfo\fR(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fR) .sp \fBTk_FreeConfigOptions\fR(\fIrecordPtr, optionTable, tkwin\fR) .fi .SH ARGUMENTS .AS Tk_SavedOptions "*const objv[]" in/out .AP Tcl_Interp *interp in A Tcl interpreter. Most procedures use this only for returning error messages; if it is NULL then no error messages are returned. For \fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the interpreter in which the option table will be used. .AP "const Tk_OptionSpec" *templatePtr in Points to an array of static information that describes the configuration options that are supported. Used to build a Tk_OptionTable. The information pointed to by this argument must exist for the lifetime of the Tk_OptionTable. .AP Tk_OptionTable optionTable in Token for an option table. Must have been returned by a previous call to \fBTk_CreateOptionTable\fR. .AP void *recordPtr in/out Points to structure in which values of configuration options are stored; fields of this record are modified by procedures such as \fBTk_SetOptions\fR and read by procedures such as \fBTk_GetOptionValue\fR. .AP Tk_Window tkwin in For options such as \fBTK_OPTION_COLOR\fR, this argument indicates the window in which the option will be used. If \fIoptionTable\fR uses no window-dependent options, then a NULL value may be supplied for this argument. .AP Tcl_Size objc in Number of values in \fIobjv\fR. .AP Tcl_Obj "*const *objv" in Command-line arguments for setting configuring options. .AP Tk_SavedOptions *savePtr out If not NULL, the structure pointed to by this argument is filled in with the old values of any options that were modified and old values are restored automatically if an error occurs in \fBTk_SetOptions\fR. .AP int *maskPtr out If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the bit-wise OR of the \fItypeMask\fR fields for the options that were modified. .AP Tk_SavedOptions *savedPtr in/out Points to a structure previously filled in by \fBTk_SetOptions\fR with old values of modified options. .AP Tcl_Obj *namePtr in The value of this object is the name of a particular option. If NULL is passed to \fBTk_GetOptionInfo\fR then information is returned for all options. Must not be NULL when \fBTk_GetOptionValue\fR is called. .AP "type name" type in The name of the type of a record. .AP "field name" field in The name of a field in records of type \fItype\fR. .BE .SH DESCRIPTION .PP These procedures handle most of the details of parsing configuration options such as those for Tk widgets. Given a description of what options are supported, these procedures handle all the details of parsing options and storing their values into a C structure associated with the widget or object. The procedures were designed primarily for widgets in Tk, but they can also be used for other kinds of objects that have configuration options. In the rest of this manual page .QW widget will be used to refer to the object whose options are being managed; in practice the object may not actually be a widget. The term .QW "widget record" is used to refer to the C-level structure in which information about a particular widget or object is stored. .PP Note that the easiest way to learn how to use these procedures is to look at a working example. In Tk, the simplest example is the code that implements the button family of widgets, which is in \fBtkButton.c\fR. Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR. .PP In order to use these procedures, the code that implements the widget must contain a static array of Tk_OptionSpec structures. This is a template that describes the various options supported by that class of widget; there is a separate template for each kind of widget. The template contains information such as the name of each option, its type, its default value, and where the value of the option is stored in the widget record. See TEMPLATES below for more detail. .PP In order to process configuration options efficiently, the static template must be augmented with additional information that is available only at runtime. The procedure \fBTk_CreateOptionTable\fR creates this dynamic information from the template and returns a Tk_OptionTable token that describes both the static and dynamic information. All of the other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable token as argument. Typically, \fBTk_CreateOptionTable\fR is called the first time that a widget of a particular class is created and the resulting Tk_OptionTable is used in the future for all widgets of that class. A Tk_OptionTable may be used only in a single interpreter, given by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR. When an option table is no longer needed \fBTk_DeleteOptionTable\fR should be called to free all of its resources. All of the option tables for a Tcl interpreter are freed automatically if the interpreter is deleted. .PP \fBTk_InitOptions\fR is invoked when a new widget is created to set the default values. \fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR) and a pointer to a widget record (\fIrecordPtr\fR), which is the C structure that holds information about this widget. \fBTk_InitOptions\fR uses the information in the option table to choose an appropriate default for each option, then it stores the default value directly into the widget record, overwriting any information that was already present in the widget record. \fBTk_InitOptions\fR normally returns \fBTCL_OK\fR. If an error occurred while setting the default values (e.g., because a default value was erroneous) then \fBTCL_ERROR\fR is returned and an error message is left in \fIinterp\fR's result if \fIinterp\fR is not NULL. For any widget's configuration option that has \fBTK_OPTION_DONT_SET_DEFAULT\fR set in its \fIflags\fR field, the above initialization is fully skipped, see below. .PP \fBTk_SetOptions\fR is invoked to modify configuration options based on information specified in a Tcl command. The command might be one that creates a new widget, or a command that modifies options on an existing widget. The \fIobjc\fR and \fIobjv\fR arguments describe the values of the arguments from the Tcl command. \fIObjv\fR must contain an even number of objects: the first object of each pair gives the name of an option and the second object gives the new value for that option. \fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that the new value of the option conforms to the type in \fIoptionTable\fR, and stores the value of the option into the widget record given by \fIrecordPtr\fR. \fBTk_SetOptions\fR normally returns \fBTCL_OK\fR. If an error occurred (such as an unknown option name or an illegal option value) then \fBTCL_ERROR\fR is returned and an error message is left in \fIinterp\fR's result if \fIinterp\fR is not NULL. .PP \fBTk_SetOptions\fR has two additional features. First, if the \fImaskPtr\fR argument is not NULL then it points to an integer value that is filled in with information about the options that were modified. For each option in the template passed to \fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field. The bits of this field are defined by the code that implements the widget; for example, each bit might correspond to a particular configuration option. Alternatively, bits might be used functionally. For example, one bit might be used for redisplay: all options that affect the widget's display, such that changing the option requires the widget to be redisplayed, might have that bit set. Another bit might indicate that the geometry of the widget must be recomputed, and so on. \fBTk_SetOptions\fR OR's together the \fItypeMask\fR fields from all the options that were modified and returns this value at *\fImaskPtr\fR; the caller can then use this information to optimize itself so that, for example, it does not redisplay the widget if the modified options do not affect the widget's appearance. .PP The second additional feature of \fBTk_SetOptions\fR has to do with error recovery. If an error occurs while processing configuration options, this feature makes it possible to restore all the configuration options to their previous values. Errors can occur either while processing options in \fBTk_SetOptions\fR or later in the caller. In many cases the caller does additional processing after \fBTk_SetOptions\fR returns; for example, it might use an option value to set a trace on a variable and may detect an error if the variable is an array instead of a scalar. Error recovery is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized Tk_SavedOptions structure on the caller's stack. \fBTk_SetOptions\fR overwrites the structure pointed to by \fIsavePtr\fR with information about the old values of any options modified by the procedure. If \fBTk_SetOptions\fR returns successfully, the caller uses the structure in one of two ways. If the caller completes its processing of the new options without any errors, then it must pass the structure to \fBTk_FreeSavedOptions\fR so that the old values can be freed. If the caller detects an error in its processing of the new options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR, which will copy the old values back into the widget record and free the new values. If \fBTk_SetOptions\fR detects an error then it automatically restores any options that had already been modified and leaves *\fIsavePtr\fR in an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or \fBTk_RestoreSavedOptions\fR. If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then \fBTk_SetOptions\fR frees each old option value immediately when it sets a new value for the option. In this case, if an error occurs in the third option, the old values for the first two options cannot be restored. .PP \fBTk_GetOptionValue\fR returns the current value of a configuration option for a particular widget. The \fInamePtr\fR argument contains the name of an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR to lookup the option and extract its value from the widget record pointed to by \fIrecordPtr\fR, then it returns an object containing that value. If an error occurs (e.g., because \fInamePtr\fR contains an unknown option name) then NULL is returned and an error message is left in \fIinterp\fR's result unless \fIinterp\fR is NULL. .PP \fBTk_GetOptionInfo\fR returns information about configuration options in a form suitable for \fBconfigure\fR widget commands. If the \fInamePtr\fR argument is not NULL, it points to an object that gives the name of a configuration option; \fBTk_GetOptionInfo\fR returns an object containing a list with five elements, which are the name of the option, the name and class used for the option in the option database, the default value for the option, and the current value for the option. If the \fInamePtr\fR argument is NULL, then \fBTk_GetOptionInfo\fR returns information about all options in the form of a list of lists; each sublist describes one option. Synonym options are handled differently depending on whether \fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for each synonym option has only two elements, which are the name of the option and the name of the other option that it refers to; if \fInamePtr\fR is non-NULL and names a synonym option then the object returned is the five-element list for the other option that the synonym refers to. If an error occurs (e.g., because \fInamePtr\fR contains an unknown option name) then NULL is returned and an error message is left in \fIinterp\fR's result unless \fIinterp\fR is NULL. .PP \fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted. It frees all of the resources associated with any of the configuration options defined in \fIrecordPtr\fR by \fIoptionTable\fR. .SH "TEMPLATES" .PP The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR via its \fItemplatePtr\fR argument describes the configuration options supported by a particular class of widgets. Each structure specifies one configuration option and has the following fields: .CS typedef struct { Tk_OptionType \fItype\fR; const char *\fIoptionName\fR; const char *\fIdbName\fR; const char *\fIdbClass\fR; const char *\fIdefValue\fR; Tcl_Size \fIobjOffset\fR; Tcl_Size \fIinternalOffset\fR; int \fIflags\fR; const void *\fIclientData\fR; int \fItypeMask\fR; } \fBTk_OptionSpec\fR; .CE The \fItype\fR field indicates what kind of configuration option this is (e.g. \fBTK_OPTION_COLOR\fR for a color value, or \fBTK_OPTION_INT\fR for an integer value). \fIType\fR determines how the value of the option is parsed (more on this below). The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR; it is the name used for the option in Tcl commands and passed to procedures via the \fIobjc\fR or \fInamePtr\fR arguments. The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR to look up a default value for this option in the option database; if \fIdbName\fR is NULL then the option database is not used by \fBTk_InitOptions\fR for this option. The \fIdefValue\fR field specifies a default value for this configuration option if no value is specified in the option database. The \fIobjOffset\fR and \fIinternalOffset\fR fields indicate where to store the value of this option in widget records (more on this below); values for the \fIobjOffset\fR and \fIinternalOffset\fR fields should always be generated with the \fBoffsetof\fR macro. The \fIflags\fR field contains additional information to control the processing of this configuration option (see below for details). \fIClientData\fR provides additional type-specific data needed by certain types. For instance, for \fBTK_OPTION_COLOR\fR types, \fIclientData\fR is a string giving the default value to use on monochrome displays. See the descriptions of the different types below for details. The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to return information about which options were modified; see the description of \fBTk_SetOptions\fR above for details. .PP When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an option into the widget record, they can do it in either of two ways. If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than or equal to zero, then the value of the option is stored as a (Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR. If the \fIinternalOffset\fR field of the Tk_OptionSpec is greater than or equal to zero, then the value of the option is stored in a type-specific internal form at the location in the widget record given by \fIinternalOffset\fR. For example, if the option's type is \fBTK_OPTION_INT\fR then the internal form is an integer. If the \fIobjOffset\fR or \fIinternalOffset\fR field is negative then the value is not stored in that form. At least one of the offsets must be greater than or equal to zero. .PP The \fIflags\fR field consists of one or more bits ORed together. The following flags are supported: .IP \fBTK_OPTION_NULL_OK\fR If this bit is set for an option then an empty string will be accepted as the value for the option and the resulting internal form will be a NULL pointer, a zero value, or \fBNone\fR, depending on the type of the option. If the flag is not set then empty strings will result in errors. \fBTK_OPTION_NULL_OK\fR is typically used to allow a feature to be turned off entirely, e.g. set a cursor value to \fBNone\fR so that a window simply inherits its parent's cursor. Not all option types support the \fBTK_OPTION_NULL_OK\fR flag; for those that do, there is an explicit indication of that fact in the descriptions below. .IP \fBTK_OPTION_DONT_SET_DEFAULT\fR If this bit is set for an option then no default value will be set in \fBTk_InitOptions\fR for this option. Neither the option database, nor any system default value, nor \fIoptionTable\fR are used to give a default value to this option. Instead it is assumed that the caller has already supplied a default value in the widget code. .IP \fBTK_OPTION_ENUM_VAR\fR If this value is set for an option, then it indicates the the internalOffset points to an enum variable in stead of an int variable. Only useful in combination with \fBTK_OPTION_STRING_TABLE\fR, \fBTK_OPTION_BOOLEAN\fR, \fBTK_OPTION_ANCHOR\fR, \fBTK_OPTION_JUSTIFY\fR, or \fBTK_OPTION_ANCHOR\fR. .IP \fBTK_OPTION_VAR(\fItype\fB)\fR If this value is set for an option, then it indicates the the internalOffset points to a \fItype\fR variable in stead of an int variable. Only useful in combination with \fBTK_OPTION_STRING_TABLE\fR or \fBTK_OPTION_BOOLEAN\fR, or as \fBTK_OPTION_VAR(Tcl_Size)\fR with \fBTK_OPTION_INT\fR .RS .PP The \fItype\fR field of each Tk_OptionSpec structure determines how to parse the value of that configuration option. The legal value for \fItype\fR, and the corresponding actions, are described below. If the type requires a \fItkwin\fR value to be passed into procedures like \fBTk_SetOptions\fR, or if it uses the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated explicitly; if not mentioned, the type requires neither \fItkwin\fR nor \fIclientData\fR. .RE .IP \fBTK_OPTION_ANCHOR\fR The value must be a standard anchor position such as \fBne\fR or \fBcenter\fR. The internal form is a Tk_Anchor value like the ones returned by \fBTk_GetAnchorFromObj\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if the empty string is specified as the value for the option, the integer relief value is set to \fBTK_ANCHOR_NULL\fR. .IP \fBTK_OPTION_BITMAP\fR The value must be a standard Tk bitmap name. The internal form is a Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_BOOLEAN\fR The value must be a standard boolean value such as \fBtrue\fR or \fBno\fR. The internal form is an integer with value 0 or 1. Note that if the \fIobjOffset\fR field is not used, information about the original value of this option will be lost. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to -1. .IP \fBTK_OPTION_BORDER\fR The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. The internal form is a Tk_3DBorder token like the ones returned by \fBTk_Alloc3DBorderFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_COLOR\fR The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. The internal form is an (XColor *) token like the ones returned by \fBTk_AllocColorFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_CURSOR\fR The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR. The internal form is a Tk_Cursor token like the ones returned by \fBTk_AllocCursorFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and when the option is set the cursor for the window is changed by calling \fBXDefineCursor\fR. This option type also supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_CUSTOM\fR This option allows applications to define new option types. The clientData field of the entry points to a structure defining the new option type. See the section \fBCUSTOM OPTION TYPES\fR below for details. .IP \fBTK_OPTION_DOUBLE\fR The string value must be a floating-point number in the format accepted by \fBstrtol\fR. The internal form is a C \fBdouble\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to NaN. .IP \fBTK_OPTION_END\fR Marks the end of the template. There must be a Tk_OptionSpec structure with \fItype\fR \fBTK_OPTION_END\fR at the end of each template. If the \fIclientData\fR field of this structure is not NULL, then it points to an additional array of Tk_OptionSpec's, which is itself terminated by another \fBTK_OPTION_END\fR entry. Templates may be chained arbitrarily deeply. This feature allows common options to be shared by several widget classes. .IP \fBTK_OPTION_FONT\fR The value must be a standard font name such as \fBTimes 16\fR. The internal form is a Tk_Font handle like the ones returned by \fBTk_AllocFontFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_INT\fR The string value must be an integer in the format accepted by \fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to specify octal or hexadecimal numbers, respectively). The internal form is a C \fBint\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to INT_MIN. .IP \fBTK_OPTION_INDEX\fR The string value must be an index in the format accepted by \fBTcl_GetIntForIndex()\fR or the empty string. The internal form is a C \fBint\fR value. If the string starts with \fB\-\fR, the internal representation will be set to INT_MIN. If the string has the form \fBend-???\fR, then the result will be a negative number: \fB-1\fR stands for \fBend\fR, \fB-2\fR stands for \fBend-1\fR and so on. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to INT_MIN. .IP \fBTK_OPTION_JUSTIFY\fR The value must be a standard justification value such as \fBleft\fR. The internal form is a Tk_Justify like the values returned by \fBTk_GetJustifyFromObj\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if the empty string is specified as the value for the option, the integer relief value is set to \fBTK_JUSTIFY_NULL\fR. .IP \fBTK_OPTION_PIXELS\fR The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR. The internal form is an integer value giving a distance in pixels, like the values returned by \fBTk_GetPixelsFromObj\fR. Note that if the \fIobjOffset\fR field is not used, information about the original value of this option will be lost. See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to INT_MIN. .IP \fBTK_OPTION_RELIEF\fR The value must be standard relief such as \fBraised\fR. The internal form is an integer relief value such as \fBTK_RELIEF_RAISED\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to \fBTK_RELIEF_NULL\fR. .IP \fBTK_OPTION_STRING\fR The value may be any string. The internal form is a (char *) pointer that points to a dynamically allocated copy of the value. This option type supports the \fBTK_OPTION_NULL_OK\fR flag. .IP \fBTK_OPTION_STRING_TABLE\fR For this type, \fIclientData\fR is a pointer to an array of strings suitable for passing to \fBTcl_GetIndexFromObj\fR. The value must be one of the strings in the table, or a unique abbreviation of one of the strings. The internal form is an integer giving the index into the table of the matching string, like the return value from \fBTcl_GetStringFromObj\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to -1. .IP \fBTK_OPTION_SYNONYM\fR This type is used to provide alternative names for an option (for example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR). The \fBclientData\fR field is a string that gives the name of another option in the same table. Whenever the synonym option is used, the information from the other option will be used instead. .IP \fBTK_OPTION_WINDOW\fR The value must be a window path name. The internal form is a \fBTk_Window\fR token for the window. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR (in order to identify the application), and it supports the \fBTK_OPTION_NULL_OK\fR flag. .SH "STORAGE MANAGEMENT ISSUES" .PP If a field of a widget record has its offset stored in the \fIobjOffset\fR or \fIinternalOffset\fR field of a Tk_OptionSpec structure then the procedures described here will handle all of the storage allocation and resource management issues associated with the field. When the value of an option is changed, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR) will automatically free any resources associated with the old value, such as Tk_Fonts for \fBTK_OPTION_FONT\fR options or dynamically allocated memory for \fBTK_OPTION_STRING\fR options. For an option stored as an object using the \fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the object pointed to by the \fIobjv\fR value from the call to \fBTk_SetOptions\fR. The reference count for this object is incremented when a pointer to it is stored in the widget record and decremented when the option is modified. When the widget is deleted \fBTk_FreeConfigOptions\fR should be invoked; it will free the resources associated with all options and decrement reference counts for any objects. .PP However, the widget code is responsible for storing NULL or \fBNone\fR in all pointer and token fields before invoking \fBTk_InitOptions\fR. This is needed to allow proper cleanup in the rare case where an error occurs in \fBTk_InitOptions\fR. .SH "OBJOFFSET VS. INTERNALOFFSET" .PP In most cases it is simplest to use the \fIinternalOffset\fR field of a Tk_OptionSpec structure and not the \fIobjOffset\fR field. This makes the internal form of the value immediately available to the widget code so the value does not have to be extracted from an object each time it is used. However, there are two cases where the \fIobjOffset\fR field is useful. The first case is for \fBTK_OPTION_PIXELS\fR options. In this case, the internal form is an integer pixel value that is valid only for a particular screen. If the value of the option is retrieved, it will be returned as a simple number. For example, after the command \fB.b configure \-borderwidth 2m\fR, the command \fB.b configure \-borderwidth\fR might return 7, which is the integer pixel value corresponding to \fB2m\fR. Unfortunately, this loses the original screen-independent value. Thus for \fBTK_OPTION_PIXELS\fR options it is better to use the \fIobjOffset\fR field. In this case the original value of the option is retained in the object and can be returned when the option is retrieved. It might seem convenient to use the \fIinternalOffset\fR field as well, so that the integer value is immediately available for use in the widget code. But if scaling is involved, \fIinternalOffset\fR won't change value when the scaling changes. Therefore it is better always to use \fBTk_GetPixelsFromObj\fR to extract the integer value from the object whenever it is needed. Note: the problem of losing information on retrievals exists only for \fBTK_OPTION_PIXELS\fR options. .PP The second reason to use the \fIobjOffset\fR field is in order to implement new types of options not supported by these procedures. To implement a new type of option, you can use \fBTK_OPTION_STRING\fR as the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field but not the \fIinternalOffset\fR field. Then, after calling \fBTk_SetOptions\fR, convert the object to internal form yourself. .PP Ttk widgets do not support the \fIinternalOffset\fR machinery. Option values of Ttk widgets are always stored as (Tcl_Obj *), meaning that the \fIobjOffset\fR field must be used. .SH "CUSTOM OPTION TYPES" .PP Applications can extend the built-in configuration types with additional configuration types by writing procedures to parse, print, free, and restore saved copies of the type and creating a structure pointing to those procedures: .CS typedef struct { const char *\fIname\fR; Tk_CustomOptionSetProc *\fIsetProc\fR; Tk_CustomOptionGetProc *\fIgetProc\fR; Tk_CustomOptionRestoreProc *\fIrestoreProc\fR; Tk_CustomOptionFreeProc *\fIfreeProc\fR; void *\fIclientData\fR; } \fBTk_ObjCustomOption\fR; typedef int \fBTk_CustomOptionSetProc\fR( void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, Tk_Window \fItkwin\fR, Tcl_Obj **\fIvaluePtr\fR, char *\fIrecordPtr\fR, Tcl_Size \fIinternalOffset\fR, char *\fIsaveInternalPtr\fR, int \fIflags\fR); typedef Tcl_Obj *\fBTk_CustomOptionGetProc\fR( void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIrecordPtr\fR, Tcl_Size \fIinternalOffset\fR); typedef void \fBTk_CustomOptionRestoreProc\fR( void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIinternalPtr\fR, char *\fIsaveInternalPtr\fR); typedef void \fBTk_CustomOptionFreeProc\fR( void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIinternalPtr\fR); .CE .PP The Tk_ObjCustomOption structure contains six fields: a name for the custom option type; pointers to the four procedures; and a \fIclientData\fR value to be passed to those procedures when they are invoked. The \fIclientData\fR value typically points to a structure containing information that is needed by the procedures when they are parsing and printing options. \fIRestoreProc\fR and \fIfreeProc\fR may be NULL, indicating that no function should be called for those operations. .PP The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to convert a Tcl_Obj into an internal representation and store the resulting value in the widget record. The arguments are: .RS .IP \fIclientData\fR A copy of the \fIclientData\fR field in the Tk_ObjCustomOption structure. .IP \fIinterp\fR A pointer to a Tcl interpreter, used for error reporting. .IP \fITkwin\fR A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR .IP \fIvaluePtr\fR A pointer to a reference to a Tcl_Obj describing the new value for the option; it could have been specified explicitly in the call to \fBTk_SetOptions\fR or it could come from the option database or a default. If the objOffset for the option is non-negative (the option value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj pointer referenced by \fIvaluePtr\fR is the pointer that will be stored at the objOffset for the option. \fISetProc\fR may modify the value if necessary; for example, \fIsetProc\fR may change the value to NULL to support the \fBTK_OPTION_NULL_OK\fR flag. .IP \fIrecordPtr\fR A pointer to the start of the widget record to modify. .IP \fIinternalOffset\fR Offset in bytes from the start of the widget record to the location where the internal representation of the option value is to be placed. .IP \fIsaveInternalPtr\fR A pointer to storage allocated in a Tk_SavedOptions structure for the internal representation of the original option value. Before setting the option to its new value, \fIsetProc\fR should set the value referenced by \fIsaveInternalPtr\fR to the original value of the option in order to support \fBTk_RestoreSavedOptions\fR. .IP \fIflags\fR A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the option .RE .PP \fISetProc\fR returns a standard Tcl result: \fBTCL_OK\fR to indicate successful processing, or \fBTCL_ERROR\fR to indicate a failure of any kind. An error message may be left in the Tcl interpreter given by \fIinterp\fR in the case of an error. .PP The \fIgetProc\fR procedure is invoked by \fBTk_GetOptionValue\fR and \fBTk_GetOptionInfo\fR to retrieve a Tcl_Obj representation of the internal representation of an option. The \fIclientData\fR argument is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIRecordPtr\fR is a pointer to the beginning of the widget record to query. \fIInternalOffset\fR is the offset in bytes from the beginning of the widget record to the location where the internal representation of the option value is stored. \fIGetProc\fR must return a pointer to a Tcl_Obj representing the value of the option. .PP The \fIrestoreProc\fR procedure is invoked by \fBTk_RestoreSavedOptions\fR to restore a previously saved internal representation of a custom option value. The \fIclientData\fR argument is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR is a pointer to the location where internal representation of the option value is stored. \fISaveInternalPtr\fR is a pointer to the saved value. \fIRestoreProc\fR must copy the value from \fIsaveInternalPtr\fR to \fIinternalPtr\fR to restore the value. \fIRestoreProc\fR need not free any memory associated with either \fIinternalPtr\fR or \fIsaveInternalPtr\fR; \fIfreeProc\fR will be invoked to free that memory if necessary. \fIRestoreProc\fR has no return value. .PP The \fIfreeProc\fR procedure is invoked by \fBTk_SetOptions\fR and \fBTk_FreeSavedOptions\fR to free any storage allocated for the internal representation of a custom option. The \fIclientData\fR argument is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR is a pointer to the location where the internal representation of the option value is stored. The \fIfreeProc\fR must free any storage associated with the option. \fIFreeProc\fR has no return value. .SH KEYWORDS anchor, bitmap, boolean, border, color, configuration option, cursor, double, font, integer, justify, pixels, relief, screen distance, synonym tk9.0.3/doc/SetVisual.30000644001000000100000000000336015105057705017621 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_SetWindowVisual 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_SetWindowVisual \- change visual characteristics of window .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_SetWindowVisual\fR(\fItkwin, visual, depth, colormap\fR) .fi .SH ARGUMENTS .AS "Tk_Window int" colormap .AP Tk_Window tkwin in Token for window. .AP Visual *visual in New visual type to use for \fItkwin\fR. .AP "int" depth in Number of bits per pixel desired for \fItkwin\fR. .AP Colormap colormap in New colormap for \fItkwin\fR, which must be compatible with \fIvisual\fR and \fIdepth\fR. .BE .SH DESCRIPTION .PP When Tk creates a new window it assigns it the default visual characteristics (visual, depth, and colormap) for its screen. \fBTk_SetWindowVisual\fR may be called to change them. \fBTk_SetWindowVisual\fR must be called before the window has actually been created in X (e.g. before \fBTk_MapWindow\fR or \fBTk_MakeWindowExist\fR has been invoked for the window). The safest thing is to call \fBTk_SetWindowVisual\fR immediately after calling \fBTk_CreateWindow\fR. If \fItkwin\fR has already been created before \fBTk_SetWindowVisual\fR is called then it returns 0 and does not make any changes; otherwise it returns 1 to signify that the operation completed successfully. .PP Note that \fBTk_SetWindowVisual\fR should not be called if you just want to change a window's colormap without changing its visual or depth; call \fBTk_SetWindowColormap\fR instead. .SH KEYWORDS colormap, depth, visual tk9.0.3/doc/spinbox.n0000644001000000100000000006621315105057705017465 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2000 Jeffrey Hobbs. '\" Copyright (c) 2000 Ajuba Solutions. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH spinbox n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME spinbox \- Create and manipulate 'spinbox' value spinner widgets .SH SYNOPSIS \fBspinbox\fI pathName \fR?\fIoptions\fR? .SO \-activebackground \-highlightthickness \-repeatinterval \-background \-insertbackground \-selectbackground \-borderwidth \-insertborderwidth \-selectborderwidth \-cursor \-insertontime \-selectforeground \-exportselection \-insertwidth \-takefocus \-font \-insertofftime \-textvariable \-foreground \-justify \-xscrollcommand \-highlightbackground \-relief \-highlightcolor \-repeatdelay \-placeholder \-placeholderforeground .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-buttonbackground buttonBackground Background The background color to be used for the spin buttons. .OP \-buttoncursor buttonCursor Cursor The cursor to be used when over the spin buttons. If this is empty (the default), a default cursor will be used. .OP \-buttondownrelief buttonDownRelief Relief The relief to be used for the upper spin button. .OP \-buttonuprelief buttonUpRelief Relief The relief to be used for the lower spin button. .OP \-command command Command Specifies a Tcl command to invoke whenever a spinbutton is invoked. The command recognizes several percent substitutions: \fB%W\fR for the widget path, \fB%s\fR for the current value of the widget, and \fB%d\fR for the direction of the button pressed (\fBup\fR or \fBdown\fR). .OP \-disabledbackground disabledBackground DisabledBackground Specifies the background color to use when the spinbox is disabled. If this option is the empty string, the normal background color is used. .OP \-disabledforeground disabledForeground DisabledForeground Specifies the foreground color to use when the spinbox is disabled. If this option is the empty string, the normal foreground color is used. .OP \-format format Format Specifies an alternate format to use when setting the string value when using the \fB\-from\fR and \fB\-to\fR range. This must be a format specifier of the form \fB%.f\fR, as it will format a floating-point number. .OP \-from from From A floating-point value corresponding to the lowest value for a spinbox, to be used in conjunction with \fB\-to\fR and \fB\-increment\fR. When all are specified correctly, the spinbox will use these values to control its contents. If this value is greater than the \fB\-to\fR option, then \fB\-from\fR and \fB\-to\fR values are automatically swapped. If \fB\-values\fR is specified, it supersedes this option. .OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand Specifies a script to eval when \fB\-validatecommand\fR returns 0. Setting it to an empty string disables this feature (the default). The best use of this option is to set it to \fIbell\fR. See \fBVALIDATION\fR below for more information. .OP \-increment increment Increment A floating-point value specifying the increment. When used with \fB\-from\fR and \fB\-to\fR, the value in the widget will be adjusted by \fB\-increment\fR when a spin button is pressed (up adds the value, down subtracts the value). .OP \-readonlybackground readonlyBackground ReadonlyBackground Specifies the background color to use when the spinbox is readonly. If this option is the empty string, the normal background color is used. .OP \-state state State Specifies one of three states for the spinbox: \fBnormal\fR, \fBdisabled\fR, or \fBreadonly\fR. If the spinbox is readonly, then the value may not be changed using widget commands and no insertion cursor will be displayed, even if the input focus is in the widget; the contents of the widget may still be selected. If the spinbox is disabled, the value may not be changed, no insertion cursor will be displayed, the contents will not be selectable, and the spinbox may be displayed in a different color, depending on the values of the \fB\-disabledforeground\fR and \fB\-disabledbackground\fR options. .OP \-to to To A floating-point value corresponding to the highest value for the spinbox, to be used in conjunction with \fB\-from\fR and \fB\-increment\fR. When all are specified correctly, the spinbox will use these values to control its contents. If this value is less than the \fB\-from\fR option, then \fB\-from\fR and \fB\-to\fR values are automatically swapped. If \fB\-values\fR is specified, it supersedes this option. .OP \-validate validate Validate Specifies the mode in which validation should operate: \fBnone\fR, \fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. It defaults to \fBnone\fR. When you want validation, you must explicitly state which mode you wish to use. See \fBVALIDATION\fR below for more. .OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand Specifies a script to evaluate when you want to validate the input in the widget. Setting it to an empty string disables this feature (the default). Validation occurs according to the value of \fB\-validate\fR. This command must return a valid Tcl boolean value. If it returns 0 (or the valid Tcl boolean equivalent) then the value of the widget will not change and the \fB\-invalidcommand\fR will be evaluated if it is set. If it returns 1, then value will be changed. See \fBVALIDATION\fR below for more information. .OP \-values values Values Must be a proper list value. If specified, the spinbox will use these values as to control its contents, starting with the first value. This option has precedence over the \fB\-from\fR and \fB\-to\fR range. .OP \-width width Width Specifies an integer value indicating the desired width of the spinbox window, in average-size characters of the widget's font. If the value is negative or zero, the widget picks a size just large enough to hold its current text. .OP \-wrap wrap wrap Must be a proper boolean value. If on, the spinbox will wrap around the values of data in the widget. .BE .SH DESCRIPTION .PP The \fBspinbox\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a spinbox widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the spinbox such as its colors, font, and relief. The \fBspinbox\fR command returns its \fIpathName\fR argument. At the time this command is invoked, there must not exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist. .PP A \fBspinbox\fR is an extended \fBentry\fR widget that allows he user to move, or spin, through a fixed set of ascending or descending values such as times or dates in addition to editing the value as in an \fBentry\fR. When first created, a spinbox's string is empty. A portion of the spinbox may be selected as described below. If a spinbox is exporting its selection (see the \fB\-exportselection\fR option), then it will observe the standard protocols for handling the selection; spinbox selections are available as type \fBSTRING\fR. Spinboxes also observe the standard Tk rules for dealing with the input focus. When a spinbox has the input focus it displays an \fIinsertion cursor\fR to indicate where new characters will be inserted. .PP Spinboxes are capable of displaying strings that are too long to fit entirely within the widget's window. In this case, only a portion of the string will be displayed; commands described below may be used to change the view in the window. Spinboxes use the standard \fB\-xscrollcommand\fR mechanism for interacting with scrollbars (see the description of the \fB\-xscrollcommand\fR option for details). They also support scanning, as described below. .SH VALIDATION .PP Validation works by setting the \fB\-validatecommand\fR option to a script which will be evaluated according to the \fB\-validate\fR option as follows: .PP .IP \fBnone\fR 10 Default. This means no validation will occur. .IP \fBfocus\fR 10 The \fB\-validatecommand\fR will be called when the spinbox receives or loses focus. .IP \fBfocusin\fR 10 The \fB\-validatecommand\fR will be called when the spinbox receives focus. .IP \fBfocusout\fR 10 The \fB\-validatecommand\fR will be called when the spinbox loses focus. .IP \fBkey\fR 10 The \fB\-validatecommand\fR will be called when the spinbox is edited. .IP \fBall\fR 10 The \fB\-validatecommand\fR will be called for all above conditions. .PP It is possible to perform percent substitutions on the \fB\-validatecommand\fR and \fB\-invalidcommand\fR scripts, just as you would in a \fBbind\fR script. The following substitutions are recognized: .PP .IP \fB%d\fR 5 Type of action: 1 for \fBinsert\fR, 0 for \fBdelete\fR, or \-1 for focus, forced or textvariable validation. .IP \fB%i\fR 5 Index of char string to be inserted/deleted, if any, otherwise \-1. .IP \fB%P\fR 5 The value of the spinbox should edition occur. If you are configuring the spinbox widget to have a new textvariable, this will be the value of that textvariable. .IP \fB%s\fR 5 The current value of spinbox before edition. .IP \fB%S\fR 5 The text string being inserted/deleted, if any. Otherwise it is an empty string. .IP \fB%v\fR 5 The type of validation currently set. .IP \fB%V\fR 5 The type of validation that triggered the callback (key, focusin, focusout, forced). .IP \fB%W\fR 5 The name of the spinbox widget. .PP In general, the \fB\-textvariable\fR and \fB\-validatecommand\fR can be dangerous to mix. Any problems have been overcome so that using the \fB\-validatecommand\fR will not interfere with the traditional behavior of the spinbox widget. Using the \fB\-textvariable\fR for read-only purposes will never cause problems. The danger comes when you try set the \fB\-textvariable\fR to something that the \fB\-validatecommand\fR would not accept, which causes \fB\-validate\fR to become \fBnone\fR (the \fB\-invalidcommand\fR will not be triggered). The same happens when an error occurs evaluating the \fB\-validatecommand\fR. .PP Primarily, an error will occur when the \fB\-validatecommand\fR or \fB\-invalidcommand\fR encounters an error in its script while evaluating or \fB\-validatecommand\fR does not return a valid Tcl boolean value. The \fB\-validate\fR option will also set itself to \fBnone\fR when you edit the spinbox widget from within either the \fB\-validatecommand\fR or the \fB\-invalidcommand\fR. Such editions will override the one that was being validated. If you wish to edit the value of the widget during validation and still have the \fB\-validate\fR option set, you should include the command .CS \fI%W config -validate %v\fR .CE in the \fB\-validatecommand\fR or \fB\-invalidcommand\fR (whichever one you were editing the spinbox widget from). It is also recommended to not set an associated \fB\-textvariable\fR during validation, as that can cause the spinbox widget to become out of sync with the \fB\-textvariable\fR. .PP Also, the \fB\-validate\fR option will set itself to \fBnone\fR when the spinbox value gets changed because of adjustment of \fB\-from\fR or \fB\-to\fR and the \fB\-validatecommand\fR returns false. For instance .CS \fIspinbox pathName -from 1 -to 10 -validate all -validatecommand {return 0}\fR .CE will in fact set the \fB\-validate\fR option to \fBnone\fR because the default value for the spinbox gets changed (due to the \fB\-from\fR and \fB\-to\fR options) to a value not accepted by the validation script. .PP Moreover, forced validation is performed when invoking any spinbutton of the spinbox. If the validation script returns false in this situation, then the \fB\-validate\fR option will be automatically set to \fBnone\fR. .SH "WIDGET COMMAND" .PP The \fBspinbox\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. .SS INDICES .PP Many of the widget commands for spinboxes take one or more indices as arguments. An index specifies a particular character in the spinbox's string, in any of the following ways: .TP 12 \fInumber\fR . Specifies the character as a numerical index, where 0 corresponds to the first character in the string. .TP 12 \fBanchor\fR . Indicates the anchor point for the selection, which is set with the \fBselect from\fR and \fBselect adjust\fR widget commands. .TP 12 \fBend\fR . Indicates the character just after the last one in the spinbox's string. This is equivalent to specifying a numerical index equal to the length of the spinbox's string. .TP 12 \fBinsert\fR . Indicates the character adjacent to and immediately following the insertion cursor. .TP 12 \fBsel.first\fR . Indicates the first character in the selection. It is an error to use this form if the selection is not in the spinbox window. .TP 12 \fBsel.last\fR . Indicates the character just after the last one in the selection. It is an error to use this form if the selection is not in the spinbox window. .TP 12 \fB@\fInumber\fR . In this form, \fInumber\fR is treated as an x-coordinate in the spinbox's window; the character spanning that x-coordinate is used. For example, .QW \fB@0\fR indicates the left-most character in the window. .LP Abbreviations may be used for any of the forms above, e.g. .QW \fBe\fR or .QW \fBsel.f\fR . In general, out-of-range indices are automatically rounded to the nearest legal value. Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. .SS SUBCOMMANDS .PP The following commands are possible for spinbox widgets: .\" METHOD: bbox .TP \fIpathName \fBbbox \fIindex\fR . Returns a list of four numbers describing the bounding box of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBspinbox\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBspinbox\fR command. .\" METHOD: delete .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? . Delete one or more elements of the spinbox. \fIFirst\fR is the index of the first character to delete, and \fIlast\fR is the index of the character just after the last one to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, i.e. a single character is deleted. This command returns an empty string. .\" METHOD: get .TP \fIpathName \fBget\fR . Returns the spinbox's string. .\" METHOD: icursor .TP \fIpathName \fBicursor \fIindex\fR . Arrange for the insertion cursor to be displayed just before the character given by \fIindex\fR. Returns an empty string. .\" METHOD: identify .TP \fIpathName \fBidentify\fI x y\fR . Returns the name of the window element corresponding to coordinates \fIx\fR and \fIy\fR in the spinbox. Return value is one of: \fBnone\fR, \fBbuttondown\fR, \fBbuttonup\fR, \fBentry\fR. .\" METHOD: index .TP \fIpathName \fBindex\fI index\fR . Returns the numerical index corresponding to \fIindex\fR. .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex string\fR . Insert the characters of \fIstring\fR just before the character indicated by \fIindex\fR. Returns an empty string. .\" METHOD: invoke .TP \fIpathName \fBinvoke\fI element\fR . Causes the specified element, either \fBbuttondown\fR or \fBbuttonup\fR, to be invoked, triggering the action associated with it. .\" METHOD: scan .TP \fIpathName \fBscan\fI option args\fR . This command is used to implement scanning on spinboxes. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx\fR . Records \fIx\fR and the current view in the spinbox window; used in conjunction with later \fBscan dragto\fR commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. .TP \fIpathName \fBscan dragto \fIx\fR . This command computes the difference between its \fIx\fR argument and the \fIx\fR argument to the last \fBscan mark\fR command for the widget. It then adjusts the view left or right by 10 times the difference in x-coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the spinbox at high speed through the window. The return value is an empty string. .RE .\" METHOD: selection .TP \fIpathName \fBselection \fIoption arg\fR . This command is used to adjust the selection within a spinbox. It has several forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBselection adjust \fIindex\fR . Locate the end of the selection nearest to the character given by \fIindex\fR, and adjust that end of the selection to be at \fIindex\fR (i.e. including but not going beyond \fIindex\fR). The other end of the selection is made the anchor point for future \fBselect to\fR commands. If the selection is not currently in the spinbox, then a new selection is created to include the characters between \fIindex\fR and the most recent selection anchor point, inclusive. Returns an empty string. .TP \fIpathName \fBselection clear\fR . Clear the selection if it is currently in this widget. If the selection is not in this widget then the command has no effect. Returns an empty string. .TP \fIpathName \fBselection element\fR ?\fIelement\fR? . Sets or gets the currently selected element. If a spinbutton element is specified, it will be displayed depressed. .TP \fIpathName \fBselection from \fIindex\fR . Set the selection anchor point to just before the character given by \fIindex\fR. Does not change the selection. Returns an empty string. .TP \fIpathName \fBselection present\fR . Returns 1 if there is are characters selected in the spinbox, 0 if nothing is selected. .TP \fIpathName \fBselection range \fIstart end\fR . Sets the selection to include the characters starting with the one indexed by \fIstart\fR and ending with the one just before \fIend\fR. If \fIend\fR refers to the same character as \fIstart\fR or an earlier one, then the spinbox's selection is cleared. .TP \fIpathName \fBselection to \fIindex\fR . If \fIindex\fR is before the anchor point, set the selection to the characters from \fIindex\fR up to but not including the anchor point. If \fIindex\fR is the same as the anchor point, do nothing. If \fIindex\fR is after the anchor point, set the selection to the characters from the anchor point up to but not including \fIindex\fR. The anchor point is determined by the most recent \fBselect from\fR or \fBselect adjust\fR command in this widget. If the selection is not in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string. .RE .\" METHOD: set .TP \fIpathName \fBset\fR ?\fIstring\fR? . If \fIstring\fR is specified, the spinbox will try and set it to this value, otherwise it just returns the spinbox's string. If validation is on, it will occur when setting the string. .\" METHOD: validate .TP \fIpathName \fBvalidate\fR . This command is used to force an evaluation of the \fB\-validatecommand\fR independent of the conditions specified by the \fB\-validate\fR option. This is done by temporarily setting the \fB\-validate\fR option to \fBall\fR. It returns 0 or 1. .\" METHOD: xview .TP \fIpathName \fBxview \fIargs\fR . This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR . Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the spinbox's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP \fIpathName \fBxview \fIindex\fR . Adjusts the view in the window so that the character given by \fIindex\fR is displayed at the left edge of the window. .TP \fIpathName \fBxview moveto\fI fraction\fR . Adjusts the view in the window so that the character \fIfraction\fR of the way through the text appears at the left edge of the window. \fIFraction\fR must be a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR . This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer or a float, but if it is a float then it is converted to an integer, rounded away from 0. \fIWhat\fR must be either \fBpages\fR or \fBunits\fR or an abbreviation of one of these. If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by \fInumber\fR average-width characters on the display. .RE .SH "DEFAULT BINDINGS" .PP Tk automatically creates class bindings for spinboxes that give them the following default behavior. In the descriptions below, .QW word refers to a contiguous group of letters, digits, or .QW _ characters, or any single character other than these. .IP [1] Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse. .IP [2] Double-clicking with mouse button 1 selects the word under the mouse and positions the insertion cursor at the beginning of the word. Dragging after a double click will stroke out a selection consisting of whole words. .IP [3] Triple-clicking with mouse button 1 selects all of the text in the spinbox and positions the insertion cursor before the first character. .IP [4] The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words. .IP [5] Clicking mouse button 1 with the Control key down will position the insertion cursor in the spinbox without affecting the selection. .IP [6] If any normal printing characters are typed in a spinbox, they are inserted at the point of the insertion cursor. .IP [7] The view in the spinbox can be adjusted by dragging with the middle mouse button (button 2, or button 3 in TkAqua). If the middle mouse button is clicked without moving the mouse, the selection is copied into the spinbox at the position of the mouse cursor. .IP [8] If the mouse is dragged out of the spinbox on the left or right sides while button 1 is pressed, the spinbox will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window). .IP [9] The Left and Right keys move the insertion cursor one character to the left or right; they also clear any selection in the spinbox and set the selection anchor. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f behave the same as Control-Left and Control-Right, respectively. .IP [10] The Home key, or Control-a, will move the insertion cursor to the beginning of the spinbox and clear any selection in the spinbox. Shift-Home moves the insertion cursor to the beginning of the spinbox and also extends the selection to that point. .IP [11] The End key, or Control-e, will move the insertion cursor to the end of the spinbox and clear any selection in the spinbox. Shift-End moves the cursor to the end and extends the selection to that point. .IP [12] The Select key and Control-Space set the selection anchor to the position of the insertion cursor. They do not affect the current selection. Shift-Select and Control-Shift-Space adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was not any selection previously. .IP [13] Control-/ selects all the text in the spinbox. .IP [14] Control-\e clears any selection in the spinbox. .IP [15] The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection. .IP [16] The F20 key (labelled Cut on many Sun workstations) or Control-w copies the selection in the widget to the clipboard and deletes the selection. If there is no selection in the widget then these keys have no effect. .IP [17] The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the contents of the clipboard at the position of the insertion cursor. .IP [18] The Delete key deletes the selection, if there is one in the spinbox. If there is no selection, it deletes the character to the right of the insertion cursor. .IP [19] The BackSpace key and Control-h delete the selection, if there is one in the spinbox. If there is no selection, it deletes the character to the left of the insertion cursor. .IP [20] Control-d deletes the character to the right of the insertion cursor. .IP [21] Meta-d deletes the word to the right of the insertion cursor. .IP [22] Control-k deletes all the characters to the right of the insertion cursor. .IP [23] Control-t reverses the order of the two characters to the right of the insertion cursor. .PP If the spinbox is disabled using the \fB\-state\fR option, then the spinbox's view can still be adjusted and text in the spinbox can still be selected, but no insertion cursor will be displayed and no text modifications will take place. .PP The behavior of spinboxes can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "SEE ALSO" ttk::spinbox(n) .SH KEYWORDS spinbox, entry, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/StrictMotif.30000644001000000100000000000215615105057705020153 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_StrictMotif 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_StrictMotif \- Return value of tk_strictMotif variable .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_StrictMotif\fR(\fItkwin\fR) .fi .SH ARGUMENTS .AS Tk_Window tkwin .AP Tk_Window tkwin in Token for window. .BE .SH DESCRIPTION .PP This procedure returns the current value of the \fBtk_strictMotif\fR variable in the interpreter associated with \fItkwin\fR's application. The value is returned as an integer that is either 0 or 1. 1 means that strict Motif compliance has been requested, so anything that is not part of the Motif specification should be avoided. 0 means that .QW Motif-like is good enough, and extra features are welcome. .PP This procedure uses a link to the Tcl variable to provide much faster access to the variable's value than could be had by calling \fBTcl_GetVar\fR. .SH KEYWORDS Motif compliance, tk_strictMotif variable tk9.0.3/doc/sysnotify.n0000644001000000100000000000355015105057705020045 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans.\" Text automatically generated by txt2man '\" '\" Copyright (c) 2020 Kevin Walzer/WordTech Communications LLC. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk sysnotify n "" Tk "Tk Built-In Commands" .so man.macros .BS .SH NAME sysnotify \- Creates a notification window with a title and message. .SH SYNOPSIS \fBtk sysnotify\fI title message\fR .BE .SH DESCRIPTION .PP The \fBtk sysnotify\fR command creates a platform-specific system notification alert. Its intent is to provide a brief, unobtrusive notification to the user by popping up a window that briefly appears in a corner of the screen. .SH EXAMPLE .PP Here is an example of the \fBtk sysnotify\fR code: .PP .CS tk sysnotify "Alert" \e "This is just a test of the Tk System Notification Code." .CE .SH PLATFORM NOTES .PP The macOS and Windows versions are native implementations using system API's. The X11 version has a conditional dependency on libnotify, and falls back to a Tcl-only implementation if libnotify is not installed. On each platform the notification includes a platform-specific default image to accompany the text. .TP \fBmacOS\fR . The macOS version will request permission from the user to authorize notifications. This must be activated in Apple's System Preferences Notifications section. .RS .PP If deploying an application using the standalone version of Wish.app, setting the bundle ID in the applications Info.plist file to begin with .QW \fBcom\fR seems necessary for notifications to work. Using a different prefix for the bundle ID, such as something like .QW \fBtk.tcl.tkchat\fR , will cause notifications to silently fail. .RE .TP \fBWindows\fR . The image is taken from the system tray, i.e., \fBsysnotify\fR can only be called when a \fBsystray\fR was installed. . .SH KEYWORDS notify, alert tk9.0.3/doc/systray.n0000644001000000100000000000640315105057705017514 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans.\" Text automatically generated by txt2man '\" '\" Copyright (c) 2020 Kevin Walzer/WordTech Communications LLC. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk systray n "" Tk "Tk Built-In Commands" .so man.macros .BS .SH NAME systray \- Creates an icon display in the platform-specific system tray. .SH SYNOPSIS .nf \fBtk systray create \-image \fIimage\fR ?\fB\-text \fItext\fR? ?\fB\-button1 \fIcallback\fR? ?\fB\-button3 \fIcallback\fR? \fBtk systray configure \fI?option? ?value option value ...?\fR \fBtk systray exists\fR \fBtk systray destroy\fR .fi .BE .SH DESCRIPTION .PP .\" METHOD: create The \fBtk systray create\fR command creates an icon in the platform-specific tray. The widget is configured with a Tk image for the icon display, an optional string for display in a tooltip, and optional callbacks that are bound to and . .PP .\" METHOD: configure The \fBtk systray configure\fR command sets one or more options of the systray icon. Configurable options are the same as for the \fBcreate\fR subcommand. When a single option name is given, the command returns the current value of this option. When no option is given this command returns the list of all options and their current value. .PP .\" METHOD: exists The \fBtk systray exists\fR command checks whether a systray icon was created. It returns a boolean. .PP .\" METHOD: destroy The \fBtk systray destroy\fR command removes the icon from display and deallocates it. .PP From a user-interface standpoint, only one icon per interpreter is supported; attempts to create additional icons will return an error. The existing tray icon can be modified with different images and strings to indicate app state. Loading additional interpreters into a running instance of Wish will allow additional icons to be displayed. .SH EXAMPLE .PP Here is an example of the \fBtk systray\fR code: .CS image create photo book -data \e R0lGODlhDwAPAKIAAP//////AP8AAMDAwICAgAAAAAAAAAAAACwAAAAADwAPAAADSQhA2u5ksPeKABKSCaya29d4WKgERFF0l1IMQCAKatvBJ0OTdzzXI1xMB3TBZAvATtB6NSLKleXi3OBoLqrVgc0yv+DVSEUuFxIAOw== tk systray create -image book -text "tk systray sample" \e -button1 {puts "Here is the tk systray output"} \e -button3 {puts "here is alternate output"} .CE .PP Here is an example of modifying the \fBtk systray\fR icon: .CS image create photo book_page -data \e R0lGODlhCwAPAKIAAP//////AMDAwICAgAAA/wAAAAAAAAAAACwAAAAACwAPAAADMzi6CzAugiAgDGE68aB0RXgRJBFVX0SNpQlUWfahQOvSsgrX7eZJMlQMWBEYj8iQchlKAAA7 tk systray configure -image book_page -text "Updated sample" \e -button1 {puts "Different output from the tk systray"} \e -button3 {puts "and more different output from the tk systray"} .CE .SH PLATFORM NOTES .PP The X11 implementation is supported on a "best efforts" basis because it is dependent on the window manager. The "text" flag, which is implemented as a tooltip, does not always display if the WM does not support such features; the systray icon itself may not even display with some window managers. .PP On Windows, the Tk image provided in the \fB\-image\fR option must be a photo image. On other platforms either a bitmap image or a photo image may be provided. .SH KEYWORDS image, callback tk9.0.3/doc/text.n0000644001000000100000000033766715105057705017005 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH text n 8.5 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate 'text' hypertext editing widgets .SH SYNOPSIS .nf \fBtext\fI pathName \fR?\fIoptions\fR? \fBtk_textCopy\fI pathName\fR \fBtk_textCut\fI pathName\fR \fBtk_textPaste\fI pathName\fR .fi .SO \-background \-highlightthickness \-relief \-borderwidth \-insertbackground \-selectbackground \-cursor \-insertborderwidth \-selectborderwidth \-exportselection \-insertofftime \-selectforeground \-font \-insertontime \-setgrid \-foreground \-insertwidth \-takefocus \-highlightbackground \-padx \-xscrollcommand \-highlightcolor \-pady \-yscrollcommand .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-autoseparators autoSeparators AutoSeparators Specifies a boolean that says whether separators are automatically inserted in the undo stack. Only meaningful when the \fB\-undo\fR option is true. .OP \-blockcursor blockCursor BlockCursor Specifies a boolean that says whether the blinking insertion cursor should be drawn as a character-sized rectangular block. If false (the default) a thin vertical line is used for the insertion cursor. For further discussion refer to section \fBTHE INSERTION CURSOR\fR below. .OP \-endline endLine EndLine Specifies an integer line index representing the line of the underlying textual data store that should be just after the last line contained in the widget. This allows a text widget to reflect only a portion of a larger piece of text. Instead of an integer, the empty string can be provided to this configuration option, which will configure the widget to end at the very last line in the textual data store. .OP \-height height Height Specifies the desired height for the window, in units of characters in the font given by the \fB\-font\fR option. Must be at least one. .OP \-inactiveselectbackground inactiveSelectBackground Foreground Specifies the colour to use for the selection (the \fBsel\fR tag) when the window does not have the input focus. If empty, \fB{}\fR, then no selection is shown when the window does not have the focus. .OP \-insertunfocussed insertUnfocussed InsertUnfocussed .VS 8.6 Specifies how to display the insertion cursor when the widget does not have the focus. Must be \fBnone\fR (the default) which means to not display the cursor, \fBhollow\fR which means to display a hollow box, or \fBsolid\fR which means to display a solid box. Note that \fBhollow\fR and \fBsolid\fR will appear very similar when the \fB\-blockcursor\fR option is false. .VE 8.6 .OP \-maxundo maxUndo MaxUndo Specifies the maximum number of compound undo actions on the undo stack. A zero or a negative value imply an unlimited undo stack. .OP \-spacing1 spacing1 Spacing1 Requests additional space above each text line in the widget, using any of the standard forms for screen distances. If a line wraps, this option only applies to the first line on the display. This option may be overridden with \fB\-spacing1\fR options in tags. .OP \-spacing2 spacing2 Spacing2 For lines that wrap (so that they cover more than one line on the display) this option specifies additional space to provide between the display lines that represent a single line of text. The value may have any of the standard forms for screen distances. This option may be overridden with \fB\-spacing2\fR options in tags. .OP \-spacing3 spacing3 Spacing3 Requests additional space below each text line in the widget, using any of the standard forms for screen distances. If a line wraps, this option only applies to the last line on the display. This option may be overridden with \fB\-spacing3\fR options in tags. .OP \-startline startLine StartLine Specifies an integer line index representing the first line of the underlying textual data store that should be contained in the widget. This allows a text widget to reflect only a portion of a larger piece of text. Instead of an integer, the empty string can be provided to this configuration option, which will configure the widget to start at the very first line in the textual data store. .OP \-state state State Specifies one of two states for the text: \fBnormal\fR or \fBdisabled\fR. If the text is disabled then characters may not be inserted or deleted and no insertion cursor will be displayed, even if the input focus is in the widget. .OP \-tabs tabs Tabs Specifies a set of tab stops for the window. The option's value consists of a list of screen distances giving the positions of the tab stops, each of which is a distance relative to the left edge of the widget (excluding borders, padding, etc). Each position may optionally be followed in the next list element by one of the keywords \fBleft\fR, \fBright\fR, \fBcenter\fR, or \fBnumeric\fR, which specifies how to justify text relative to the tab stop. \fBLeft\fR is the default; it causes the text following the tab character to be positioned with its left edge at the tab position. \fBRight\fR means that the right edge of the text following the tab character is positioned at the tab position, and \fBcenter\fR means that the text is centered at the tab position. \fBNumeric\fR means that the decimal point in the text is positioned at the tab position; if there is no decimal point then the least significant digit of the number is positioned just to the left of the tab position; if there is no number in the text then the text is right-justified at the tab position. For example, .QW "\fB\-tabs {2c left 4c 6c center}\fR" creates three tab stops at two-centimeter intervals; the first two use left justification and the third uses center justification. .RS .PP If the list of tab stops does not have enough elements to cover all of the tabs in a text line, then Tk extrapolates new tab stops using the spacing and alignment from the last tab stop in the list. Tab distances must be strictly positive, and must always increase from one tab stop to the next (if not, an error is thrown). The value of the \fB\-tabs\fR option may be overridden by \fB\-tabs\fR options in tags. .PP If no \fB\-tabs\fR option is specified, or if it is specified as an empty list, then Tk uses default tabs spaced every eight (average size) characters. To achieve a different standard spacing, for example every 4 characters, simply configure the widget with .QW "\fB\-tabs \N'34'[expr {4 * [font measure $font 0]}] left\N'34' \-tabstyle wordprocessor\fR" . .RE .OP \-tabstyle tabStyle TabStyle Specifies how to interpret the relationship between tab stops on a line and tabs in the text of that line. The value must be \fBtabular\fR (the default) or \fBwordprocessor\fR. Note that tabs are interpreted as they are encountered in the text. If the tab style is \fBtabular\fR then the \fIn\fR'th tab character in the line's text will be associated with the \fIn\fR'th tab stop defined for that line. If the tab character's x coordinate falls to the right of the \fIn\fR'th tab stop, then a gap of a single space will be inserted as a fallback. If the tab style is \fBwordprocessor\fR then any tab character being laid out will use (and be defined by) the first tab stop to the right of the preceding characters already laid out on that line. The value of the \fB\-tabstyle\fR option may be overridden by \fB\-tabstyle\fR options in tags. .OP \-undo undo Undo Specifies a boolean that says whether the undo mechanism is active or not. .OP \-width width Width Specifies the desired width for the window in units of characters in the font given by the \fB\-font\fR option. If the font does not have a uniform width then the width of the character .QW 0 is used in translating from character units to screen units. .OP \-wrap wrap Wrap Specifies how to handle lines in the text that are too long to be displayed in a single line of the text's window. The value must be \fBnone\fR or \fBchar\fR or \fBword\fR. A wrap mode of \fBnone\fR means that each line of text appears as exactly one line on the screen; extra characters that do not fit on the screen are not displayed. In the other modes each line of text will be broken up into several screen lines if necessary to keep all the characters visible. In \fBchar\fR mode a screen line break may occur after any character; in \fBword\fR mode a line break will only be made at word boundaries. .BE .SH DESCRIPTION .PP The \fBtext\fR command creates a new window (given by the \fIpathName\fR argument) and makes it into a text widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the text such as its default background color and relief. The \fBtext\fR command returns the path name of the new window. .PP A text widget displays one or more lines of text and allows that text to be edited. Text widgets support four different kinds of annotations on the text, called tags, marks, embedded windows or embedded images. Tags allow different portions of the text to be displayed with different fonts and colors. In addition, Tcl commands can be associated with tags so that scripts are invoked when particular actions such as keystrokes and mouse button presses occur in particular ranges of the text. See \fBTAGS\fR below for more details. .PP The second form of annotation consists of floating markers in the text called .QW marks . Marks are used to keep track of various interesting positions in the text as it is edited. See \fBMARKS\fR below for more details. .PP The third form of annotation allows arbitrary windows to be embedded in a text widget. See \fBEMBEDDED WINDOWS\fR below for more details. .PP The fourth form of annotation allows Tk images to be embedded in a text widget. See \fBEMBEDDED IMAGES\fR below for more details. .PP The text widget also has a built-in undo/redo mechanism. See \fBTHE UNDO MECHANISM\fR below for more details. .PP The text widget allows for the creation of peer widgets. These are other text widgets which share the same underlying data (text, marks, tags, images, etc). See \fBPEER WIDGETS\fR below for more details. .SH INDICES .PP Many of the widget commands for texts take one or more indices as arguments. An index is a string used to indicate a particular place within a text, such as a place to insert characters or one endpoint of a range of characters to delete. Indices have the syntax .CS \fIbase modifier modifier modifier ...\fR .CE Where \fIbase\fR gives a starting point and the \fImodifier\fRs adjust the index from the starting point (e.g. move forward or backward one character). Every index must contain a \fIbase\fR, but the \fImodifier\fRs are optional. Most modifiers (as documented below) allow an optional submodifier. Valid submodifiers are \fBany\fR and \fBdisplay\fR. If the submodifier is abbreviated, then it must be followed by whitespace, but otherwise there need be no space between the submodifier and the following \fImodifier\fR. Typically the \fBdisplay\fR submodifier adjusts the meaning of the following \fImodifier\fR to make it refer to visual or non-elided units rather than logical units, but this is explained for each relevant case below. Lastly, where \fIcount\fR is used as part of a modifier, it can be positive or negative, so .QW "\fIbase\fR \- \-3 lines" is perfectly valid (and equivalent to .QW "\fIbase\fR +3lines" ). .PP The \fIbase\fR for an index must have one of the following forms: .TP 12 \fIline\fB.\fIchar\fR . Indicates \fIchar\fR'th character on line \fIline\fR. Lines are numbered from 1 for consistency with other UNIX programs that use this numbering scheme. Within a line, characters are numbered from 0. If \fIchar\fR is \fBend\fR then it refers to the newline character that ends the line. .TP 12 \fB@\fIx\fB,\fIy\fR . Indicates the character that covers the pixel whose x and y coordinates within the text's window are \fIx\fR and \fIy\fR. .TP 12 \fBend\fR . Indicates the end of the text (the character just after the last newline). .TP 12 \fImark\fR . Indicates the character just after the mark whose name is \fImark\fR (see \fBMARKS\fR for details). .TP 12 \fItag\fB.first\fR . Indicates the first character in the text that has been tagged with \fItag\fR. This form generates an error if no characters are currently tagged with \fItag\fR. .TP 12 \fItag\fB.last\fR . Indicates the character just after the last one in the text that has been tagged with \fItag\fR. This form generates an error if no characters are currently tagged with \fItag\fR. .TP 12 \fIpathName\fR . Indicates the position of the embedded window whose name is \fIpathName\fR. This form generates an error if there is no embedded window by the given name. .TP 12 \fIimageName\fR . Indicates the position of the embedded image whose name is \fIimageName\fR. This form generates an error if there is no embedded image by the given name. .PP If the \fIbase\fR could match more than one of the above forms, such as a \fImark\fR and \fIimageName\fR both having the same value, then the form earlier in the above list takes precedence. If modifiers follow the base index, each one of them must have one of the forms listed below. Keywords such as \fBchars\fR and \fBwordend\fR may be abbreviated as long as the abbreviation is unambiguous. .TP \fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBchars\fR . Adjust the index forward by \fIcount\fR characters, moving to later lines in the text if necessary. If there are fewer than \fIcount\fR characters in the text after the current index, then set the index to the last index in the text. Spaces on either side of \fIcount\fR are optional. If the \fBdisplay\fR submodifier is given, elided characters are skipped over without being counted. If \fBany\fR is given, then all characters are counted. For historical reasons, if neither modifier is given then the count actually takes place in units of index positions (see \fBINDICES\fR for details). This behaviour may be changed in a future major release, so if you need an index count, you are encouraged to use \fBindices\fR instead wherever possible. .TP \fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBchars\fR . Adjust the index backward by \fIcount\fR characters, moving to earlier lines in the text if necessary. If there are fewer than \fIcount\fR characters in the text before the current index, then set the index to the first index in the text (1.0). Spaces on either side of \fIcount\fR are optional. If the \fBdisplay\fR submodifier is given, elided characters are skipped over without being counted. If \fBany\fR is given, then all characters are counted. For historical reasons, if neither modifier is given then the count actually takes place in units of index positions (see \fBINDICES\fR for details). This behavior may be changed in a future major release, so if you need an index count, you are encouraged to use \fBindices\fR instead wherever possible. .TP \fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBindices\fR . Adjust the index forward by \fIcount\fR index positions, moving to later lines in the text if necessary. If there are fewer than \fIcount\fR index positions in the text after the current index, then set the index to the last index position in the text. Spaces on either side of \fIcount\fR are optional. Note that an index position is either a single character or a single embedded image or embedded window. If the \fBdisplay\fR submodifier is given, elided indices are skipped over without being counted. If \fBany\fR is given, then all indices are counted; this is also the default behaviour if no modifier is given. .TP \fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBindices\fR . Adjust the index backward by \fIcount\fR index positions, moving to earlier lines in the text if necessary. If there are fewer than \fIcount\fR index positions in the text before the current index, then set the index to the first index position (1.0) in the text. Spaces on either side of \fIcount\fR are optional. If the \fBdisplay\fR submodifier is given, elided indices are skipped over without being counted. If \fBany\fR is given, then all indices are counted; this is also the default behaviour if no modifier is given. .TP \fB+ \fIcount\fR ?\fIsubmodifier\fR? \fBlines\fR . Adjust the index forward by \fIcount\fR lines, retaining the same character position within the line. If there are fewer than \fIcount\fR lines after the line containing the current index, then set the index to refer to the same character position on the last line of the text. Then, if the line is not long enough to contain a character at the indicated character position, adjust the character position to refer to the last character of the line (the newline). Spaces on either side of \fIcount\fR are optional. If the \fBdisplay\fR submodifier is given, then each visual display line is counted separately. Otherwise, if \fBany\fR (or no modifier) is given, then each logical line (no matter how many times it is visually wrapped) counts just once. If the relevant lines are not wrapped, then these two methods of counting are equivalent. .TP \fB\- \fIcount\fR ?\fIsubmodifier\fR? \fBlines\fR . Adjust the index backward by \fIcount\fR logical lines, retaining the same character position within the line. If there are fewer than \fIcount\fR lines before the line containing the current index, then set the index to refer to the same character position on the first line of the text. Then, if the line is not long enough to contain a character at the indicated character position, adjust the character position to refer to the last character of the line (the newline). Spaces on either side of \fIcount\fR are optional. If the \fBdisplay\fR submodifier is given, then each visual display line is counted separately. Otherwise, if \fBany\fR (or no modifier) is given, then each logical line (no matter how many times it is visually wrapped) counts just once. If the relevant lines are not wrapped, then these two methods of counting are equivalent. .TP ?\fIsubmodifier\fR? \fBlinestart\fR . Adjust the index to refer to the first index on the line. If the \fBdisplay\fR submodifier is given, this is the first index on the display line, otherwise on the logical line. .TP ?\fIsubmodifier\fR? \fBlineend\fR . Adjust the index to refer to the last index on the line (the newline). If the \fBdisplay\fR submodifier is given, this is the last index on the display line, otherwise on the logical line. .TP ?\fIsubmodifier\fR? \fBwordstart\fR . Adjust the index to refer to the first character of the word containing the current index. A word consists of any number of adjacent characters that are letters, digits, or underscores, or a single character that is not one of these. If the \fBdisplay\fR submodifier is given, this only examines non-elided characters, otherwise all characters (elided or not) are examined. .TP ?\fIsubmodifier\fR? \fBwordend\fR . Adjust the index to refer to the character just after the last one of the word containing the current index. If the current index refers to the last character of the text then it is not modified. If the \fBdisplay\fR submodifier is given, this only examines non-elided characters, otherwise all characters (elided or not) are examined. .PP If more than one modifier is present then they are applied in left-to-right order. For example, the index .QW "\fBend \- 1 chars\fR" refers to the next-to-last character in the text and .QW "\fBinsert wordstart \- 1 c\fR" refers to the character just before the first one in the word containing the insertion cursor. Modifiers are applied one by one in this left to right order, and after each step the resulting index is constrained to be a valid index in the text widget. So, for example, the index .QW "\fB1.0 \-1c +1c\fR" refers to the index .QW \fB2.0\fR . .PP Where modifiers result in index changes by display lines, display chars or display indices, and the \fIbase\fR refers to an index inside an elided tag, that base index is considered to be equivalent to the first following non-elided index. .SH TAGS .PP The first form of annotation in text widgets is a tag. A tag is a textual string that is associated with some of the characters in a text. Tags may contain arbitrary characters, but it is probably best to avoid using the characters .QW " " (space), \fB+\fR, or \fB\-\fR: these characters have special meaning in indices, so tags containing them cannot be used as indices. There may be any number of tags associated with characters in a text. Each tag may refer to a single character, a range of characters, or several ranges of characters. An individual character may have any number of tags associated with it. .PP A priority order is defined among tags, and this order is used in implementing some of the tag-related functions described below. When a tag is defined (by associating it with characters or setting its display options or binding commands to it), it is given a priority higher than any existing tag. The priority order of tags may be redefined using the .QW "\fIpathName \fBtag raise\fR" and .QW "\fIpathName \fBtag lower\fR" widget commands. .PP Tags serve three purposes in text widgets. First, they control the way information is displayed on the screen. By default, characters are displayed as determined by the \fB\-background\fR, \fB\-font\fR, and \fB\-foreground\fR options for the text widget. However, display options may be associated with individual tags using the .QW "\fIpathName \fBtag configure\fR" widget command. If a character has been tagged, then the display options associated with the tag override the default display style. The following options are currently supported for tags: .\" OPTION: -background .TP \fB\-background \fIcolor\fR . \fIColor\fR specifies the background color to use for characters associated with the tag. It may have any of the forms accepted by \fBTk_GetColor\fR. .\" OPTION: -bgstipple .TP \fB\-bgstipple \fIbitmap\fR . \fIBitmap\fR specifies a bitmap that is used as a stipple pattern for the background. It may have any of the forms accepted by \fBTk_GetBitmap\fR. If \fIbitmap\fR has not been specified, or if it is specified as an empty string, then a solid fill will be used for the background. .\" OPTION: -borderwidth .TP \fB\-borderwidth \fIpixels\fR . \fIPixels\fR specifies the width of a border to draw around the tag using any of the forms accepted by \fBTk_GetPixels\fR. This option should be used in conjunction with the \fB\-relief\fR option to provide the desired border. .\" OPTION: -elide .TP \fB\-elide \fIboolean\fR . \fIElide\fR specifies whether the data should be elided. Elided data (characters, images, embedded windows, etc.) is not displayed and takes no space on screen, but further on behaves just as normal data. .\" OPTION: -fgstipple .TP \fB\-fgstipple \fIbitmap\fR . \fIBitmap\fR specifies a bitmap that is used as a stipple pattern when drawing text and other foreground information such as underlines. It may have any of the forms accepted by \fBTk_GetBitmap\fR. If \fIbitmap\fR has not been specified, or if it is specified as an empty string, then a solid fill will be used. .\" OPTION: -font .TP \fB\-font \fIfontName\fR . \fIFontName\fR is the name of a font to use for drawing characters. It may have any of the forms accepted by \fBTk_GetFont\fR. .\" OPTION: -foreground .TP \fB\-foreground \fIcolor\fR . \fIColor\fR specifies the color to use when drawing text and other foreground information such as underlines. It may have any of the forms accepted by \fBTk_GetColor\fR. .\" OPTION: -justify .TP \fB\-justify \fIjustify\fR . If the first non-elided character of a display line has a tag for which this option has been specified, then \fIjustify\fR determines how to justify the line. It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR. If a line wraps, then the justification for each line on the display is determined by the first non-elided character of that display line. .\" OPTION: -lmargin1 .TP \fB\-lmargin1 \fIpixels\fR . If the first non-elided character of a text line has a tag for which this option has been specified, then \fIpixels\fR specifies how much the line should be indented from the left edge of the window. \fIPixels\fR may have any of the standard forms for screen distances. If a line of text wraps, this option only applies to the first line on the display; the \fB\-lmargin2\fR option controls the indentation for subsequent lines. .\" OPTION: -lmargin2 .TP \fB\-lmargin2 \fIpixels\fR . If the first non-elided character of a display line has a tag for which this option has been specified, and if the display line is not the first for its text line (i.e., the text line has wrapped), then \fIpixels\fR specifies how much the line should be indented from the left edge of the window. \fIPixels\fR may have any of the standard forms for screen distances. This option is only used when wrapping is enabled, and it only applies to the second and later display lines for a text line. .\" OPTION: -lmargincolor .TP \fB\-lmargincolor \fIcolor\fR . \fIColor\fR specifies the background color to use in regions that do not contain characters because they are indented by \fB\-lmargin1\fR or \fB\-lmargin2\fR. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color used is specified by the \fB\-background\fR tag option (or, if this is also unspecified, by the \fB\-background\fR widget option). .\" OPTION: -offset .TP \fB\-offset \fIpixels\fR . \fIPixels\fR specifies an amount by which the text's baseline should be offset vertically from the baseline of the overall line, in pixels. For example, a positive offset can be used for superscripts and a negative offset can be used for subscripts. \fIPixels\fR may have any of the standard forms for screen distances. .\" OPTION: -overstrike .TP \fB\-overstrike \fIboolean\fR . Specifies whether or not to draw a horizontal rule through the middle of characters. \fIBoolean\fR may have any of the forms accepted by \fBTcl_GetBoolean\fR. .\" OPTION: -overstrikefg .TP \fB\-overstrikefg \fIcolor\fR . \fIColor\fR specifies the color to use when displaying the overstrike. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color specified by the \fB\-foreground\fR tag option is used. .\" OPTION: -relief .TP \fB\-relief \fIrelief\fR . \fIRelief\fR specifies the relief style to use for drawing the border, in any of the forms accepted by \fBTk_GetRelief\fR. This option is used in conjunction with the \fB\-borderwidth\fR option to enable to the desired border appearance. .\" OPTION: -rmargin .TP \fB\-rmargin \fIpixels\fR . If the first non-elided character of a display line has a tag for which this option has been specified, then \fIpixels\fR specifies how wide a margin to leave between the end of the line and the right edge of the window. \fIPixels\fR may have any of the standard forms for screen distances. This option is only used when wrapping is enabled. If a text line wraps, the right margin for each line on the display is determined by the first non-elided character of that display line. .\" OPTION: -rmargincolor .TP \fB\-rmargincolor \fIcolor\fR . \fIColor\fR specifies the background color to use in regions that do not contain characters because they are indented by \fB\-rmargin\fR. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color used is specified by the \fB\-background\fR tag option (or, if this is also unspecified, by the \fB\-background\fR widget option). .\" OPTION: -selectbackground .TP \fB\-selectbackground \fIcolor\fR . \fIColor\fR specifies the background color to use when displaying selected items. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color specified by the \fB\-background\fR tag option is used. .\" OPTION: -selectforeground .TP \fB\-selectforeground \fIcolor\fR . \fIColor\fR specifies the foreground color to use when displaying selected items. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color specified by the \fB\-foreground\fR tag option is used. .\" OPTION: -spacing1 .TP \fB\-spacing1 \fIpixels\fR . \fIPixels\fR specifies how much additional space should be left above each text line, using any of the standard forms for screen distances. If a line wraps, this option only applies to the first line on the display. .\" OPTION: -spacing2 .TP \fB\-spacing2 \fIpixels\fR . For lines that wrap, this option specifies how much additional space to leave between the display lines for a single text line. \fIPixels\fR may have any of the standard forms for screen distances. .\" OPTION: -spacing3 .TP \fB\-spacing3 \fIpixels\fR . \fIPixels\fR specifies how much additional space should be left below each text line, using any of the standard forms for screen distances. If a line wraps, this option only applies to the last line on the display. .\" OPTION: -tabs .TP \fB\-tabs \fItabList\fR . \fITabList\fR specifies a set of tab stops in the same form as for the \fB\-tabs\fR option for the text widget. This option only applies to a display line if it applies to the first non-elided character on that display line. If this option is specified as an empty string, it cancels the option, leaving it unspecified for the tag (the default). If the option is specified as a non-empty string that is an empty list, such as \fB\-tags\0{\0}\fR, then it requests default 8-character tabs as described for the \fB\-tags\fR widget option. .\" OPTION: -tabstyle .TP \fB\-tabstyle \fIstyle\fR . \fIStyle\fR specifies either the \fItabular\fR or \fIwordprocessor\fR style of tabbing to use for the text widget. This option only applies to a display line if it applies to the first non-elided character on that display line. If this option is specified as an empty string, it cancels the option, leaving it unspecified for the tag (the default). .\" OPTION: -underline .TP \fB\-underline \fIboolean\fR . \fIBoolean\fR specifies whether or not to draw an underline underneath characters. It may have any of the forms accepted by \fBTcl_GetBoolean\fR. .\" OPTION: -underlinefg .TP \fB\-underlinefg \fIcolor\fR . \fIColor\fR specifies the color to use when displaying the underline. It may have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is specified as an empty string, then the color specified by the \fB\-foreground\fR tag option is used. .\" OPTION: -wrap .TP \fB\-wrap \fImode\fR . \fIMode\fR specifies how to handle lines that are wider than the text's window. This option only applies to a display line if it applies to the first non-elided character on that display line. It has the same legal values as the \fB\-wrap\fR option for the text widget: \fBnone\fR, \fBchar\fR, or \fBword\fR. If this tag option is specified, it overrides the \fB\-wrap\fR option for the text widget. .PP If a character has several tags associated with it, and if their display options conflict, then the options of the highest priority tag are used. If a particular display option has not been specified for a particular tag, or if it is specified as an empty string, then that option will never be used; the next-highest-priority tag's option will used instead. If no tag specifies a particular display option, then the default style for the widget will be used. .PP The second purpose for tags is event bindings. You can associate bindings with a tag in much the same way you can associate bindings with a widget class: whenever particular X events occur on characters with the given tag, a given Tcl command will be executed. Tag bindings can be used to give behaviors to ranges of characters; among other things, this allows hypertext-like features to be implemented. For details, see the description of the .QW "\fIpathName \fBtag bind\fR" widget command below. Tag bindings are shared between all peer widgets (including any bindings for the special \fBsel\fR tag). .PP The third use for tags is in managing the selection. See \fBTHE SELECTION\fR below. With the exception of the special \fBsel\fR tag, all tags are shared between peer text widgets, and may be manipulated on an equal basis from any such widget. The \fBsel\fR tag exists separately and independently in each peer text widget (but any tag bindings to \fBsel\fR are shared). .SH MARKS .PP The second form of annotation in text widgets is a mark. Marks are used for remembering particular places in a text. They are something like tags, in that they have names and they refer to places in the file, but a mark is not associated with particular characters. Instead, a mark is associated with the gap between two characters. Only a single position may be associated with a mark at any given time. If the characters around a mark are deleted the mark will still remain; it will just have new neighbor characters. In contrast, if the characters containing a tag are deleted then the tag will no longer have an association with characters in the file. Marks may be manipulated with the .QW "\fIpathName \fBmark\fR" widget command, and their current locations may be determined by using the mark name as an index in widget commands. .PP Each mark also has a .QW gravity , which is either \fBleft\fR or \fBright\fR. The gravity for a mark specifies what happens to the mark when text is inserted at the point of the mark. If a mark has left gravity, then the mark is treated as if it were attached to the character on its left, so the mark will remain to the left of any text inserted at the mark position. If the mark has right gravity, new text inserted at the mark position will appear to the left of the mark (so that the mark remains rightmost). The gravity for a mark defaults to \fBright\fR. .PP The name space for marks is different from that for tags: the same name may be used for both a mark and a tag, but they will refer to different things. .PP Two marks have special significance. First, the mark \fBinsert\fR is associated with the insertion cursor, as described under \fBTHE INSERTION CURSOR\fR below. Second, the mark \fBcurrent\fR is associated with the character closest to the mouse and is adjusted automatically to track the mouse position and any changes to the text in the widget (one exception: \fBcurrent\fR is not updated in response to mouse motions if a mouse button is down; the update will be deferred until all mouse buttons have been released). Neither of these special marks may be deleted. With the exception of these two special marks, all marks are shared between peer text widgets, and may be manipulated on an equal basis from any peer. .SH "EMBEDDED WINDOWS" .PP The third form of annotation in text widgets is an embedded window. Each embedded window annotation causes a window to be displayed at a particular point in the text. There may be any number of embedded windows in a text widget, and any widget may be used as an embedded window (subject to the usual rules for geometry management, which require the text window to be the parent of the embedded window or a descendant of its parent). .PP The embedded window's position on the screen will be updated as the text is modified or scrolled, and it will be mapped and unmapped as it moves into and out of the visible area of the text widget. Each embedded window occupies one unit's worth of index space in the text widget, and it may be referred to either by the name of its embedded window or by its position in the widget's index space. If the range of text containing the embedded window is deleted then the window is destroyed. Similarly if the text widget as a whole is deleted, then the window is destroyed. .PP Eliding an embedded window immediately after scheduling it for creation via \fIpathName \fBwindow create \fIindex \fB\-create\fR will prevent it from being effectively created. Uneliding an elided embedded window scheduled for creation via \fIpathName \fBwindow create \fIindex \fB\-create\fR will automatically trigger the associated creation script. After destroying an elided embedded window, the latter won't get automatically recreated. .PP When an embedded window is added to a text widget with the \fIpathName \fBwindow create\fR widget command, several configuration options may be associated with it. These options may be modified later with the \fIpathName \fBwindow configure\fR widget command. The following options are currently supported: .\" OPTION: -align .TP \fB\-align \fIwhere\fR . If the window is not as tall as the line in which it is displayed, this option determines where the window is displayed in the line. \fIWhere\fR must have one of the values \fBtop\fR (align the top of the window with the top of the line), \fBcenter\fR (center the window within the range of the line), \fBbottom\fR (align the bottom of the window with the bottom of the line's area), or \fBbaseline\fR (align the bottom of the window with the baseline of the line). .\" OPTION: -create .TP \fB\-create \fIscript\fR . Specifies a Tcl script that may be evaluated to create the window for the annotation. If no \fB\-window\fR option has been specified for the annotation this script will be evaluated when the annotation is about to be displayed on the screen. \fIScript\fR must create a window for the annotation and return the name of that window as its result. Two substitutions will be performed in \fIscript\fR before evaluation. \fI%W\fR will be substituted by the name of the parent text widget, and \fI%%\fR will be substituted by a single \fI%\fR. If the annotation's window should ever be deleted, \fIscript\fR will be evaluated again the next time the annotation is displayed. .\" OPTION: -padx .TP \fB\-padx \fIpixels\fR . \fIPixels\fR specifies the amount of extra space to leave on each side of the embedded window. It may have any of the usual forms defined for a screen distance. .\" OPTION: -pady .TP \fB\-pady \fIpixels\fR . \fIPixels\fR specifies the amount of extra space to leave on the top and on the bottom of the embedded window. It may have any of the usual forms defined for a screen distance. .\" OPTION: -stretch .TP \fB\-stretch \fIboolean\fR . If the requested height of the embedded window is less than the height of the line in which it is displayed, this option can be used to specify whether the window should be stretched vertically to fill its line. If the \fB\-pady\fR option has been specified as well, then the requested padding will be retained even if the window is stretched. .\" OPTION: -window .TP \fB\-window \fIpathName\fR . Specifies the name of a window to display in the annotation. Note that if a \fIpathName\fR has been set, then later configuring a window to the empty string will not delete the widget corresponding to the old \fIpathName\fR. Rather it will remove the association between the old \fIpathName\fR and the text widget. If multiple peer widgets are in use, it is usually simpler to use the \fB\-create\fR option if embedded windows are desired in each peer. .SH "EMBEDDED IMAGES" .PP The final form of annotation in text widgets is an embedded image. Each embedded image annotation causes an image to be displayed at a particular point in the text. There may be any number of embedded images in a text widget, and a particular image may be embedded in multiple places in the same text widget. .PP The embedded image's position on the screen will be updated as the text is modified or scrolled. Each embedded image occupies one unit's worth of index space in the text widget, and it may be referred to either by its position in the widget's index space, or the name it is assigned when the image is inserted into the text widget with \fIpathName \fBimage create\fR. If the range of text containing the embedded image is deleted then that copy of the image is removed from the screen. .PP Eliding an embedded image immediately after scheduling it for creation via \fIpathName \fBimage create \fIindex \fB\-create\fR will prevent it from being effectively created. Uneliding an elided embedded image scheduled for creation via \fIpathName \fBimage create \fIindex \fB\-create\fR will automatically trigger the associated creation script. After destroying an elided embedded image, the latter won't get automatically recreated. .PP When an embedded image is added to a text widget with the \fIpathName \fBimage create\fR widget command, a name unique to this instance of the image is returned. This name may then be used to refer to this image instance. The name is taken to be the value of the \fB\-name\fR option (described below). If the \fB\-name\fR option is not provided, the \fB\-image\fR name is used instead. If the \fIimageName\fR is already in use in the text widget, then \fB#\fInn\fR is added to the end of the \fIimageName\fR, where \fInn\fR is an arbitrary integer. This insures the \fIimageName\fR is unique. Once this name is assigned to this instance of the image, it does not change, even though the \fB\-image\fR or \fB\-name\fR values can be changed with \fIpathName \fBimage configure\fR. .PP When an embedded image is added to a text widget with the \fIpathName \fBimage create\fR widget command, several configuration options may be associated with it. These options may be modified later with the \fIpathName \fBimage configure\fR widget command. The following options are currently supported: .\" OPTION: -align .TP \fB\-align \fIwhere\fR . If the image is not as tall as the line in which it is displayed, this option determines where the image is displayed in the line. \fIWhere\fR must have one of the values \fBtop\fR (align the top of the image with the top of the line), \fBcenter\fR (center the image within the range of the line), \fBbottom\fR (align the bottom of the image with the bottom of the line's area), or \fBbaseline\fR (align the bottom of the image with the baseline of the line). .\" OPTION: -image .TP \fB\-image \fIimage\fR . Specifies the name of the Tk image to display in the annotation. If \fIimage\fR is not a valid Tk image, then an error is returned. .\" OPTION: -name .TP \fB\-name \fIImageName\fR . Specifies the name by which this image instance may be referenced in the text widget. If \fIImageName\fR is not supplied, then the name of the Tk image is used instead. If the \fIimageName\fR is already in use, \fI#nn\fR is appended to the end of the name as described above. .\" OPTION: -padx .TP \fB\-padx \fIpixels\fR . \fIPixels\fR specifies the amount of extra space to leave on each side of the embedded image. It may have any of the usual forms defined for a screen distance. .\" OPTION: -pady .TP \fB\-pady \fIpixels\fR . \fIPixels\fR specifies the amount of extra space to leave on the top and on the bottom of the embedded image. It may have any of the usual forms defined for a screen distance. .SH "THE SELECTION" .PP Selection support is implemented via tags. If the \fB\-exportselection\fR option for the text widget is true then the \fBsel\fR tag will be associated with the selection: .IP [1] Whenever characters are tagged with \fBsel\fR the text widget will claim ownership of the selection. .IP [2] Attempts to retrieve the selection will be serviced by the text widget, returning all the characters with the \fBsel\fR tag. .IP [3] If the selection is claimed away by another application or by another window within this application, then the \fBsel\fR tag will be removed from all characters in the text. .IP [4] Whenever the \fBsel\fR tag range changes a virtual event \fB<>\fR is generated. It might also be generated when selection is affected but not actually changed. Further, multiple selection changes could happen before events can be processed leading to multiple events with the same visible selection. .PP The \fBsel\fR tag is automatically defined when a text widget is created, and it may not be deleted with the .QW "\fIpathName \fBtag delete\fR" widget command. Furthermore, the \fB\-selectbackground\fR, \fB\-selectborderwidth\fR, and \fB\-selectforeground\fR options for the text widget are tied to the \fB\-background\fR, \fB\-borderwidth\fR, and \fB\-foreground\fR options for the \fBsel\fR tag: changes in either will automatically be reflected in the other. Also the \fB\-inactiveselectbackground\fR option for the text widget is used instead of \fB\-selectbackground\fR when the text widget does not have the focus. This allows programmatic control over the visualization of the \fBsel\fR tag for foreground and background windows, or to have \fBsel\fR not shown at all (when \fB\-inactiveselectbackground\fR is empty) for background windows. Each peer text widget has its own \fBsel\fR tag which can be separately configured and set. .SH "THE INSERTION CURSOR" .PP The mark named \fBinsert\fR has special significance in text widgets. It is defined automatically when a text widget is created and it may not be unset with the .QW "\fIpathName \fBmark unset\fR" widget command. The \fBinsert\fR mark represents the position of the insertion cursor, and the insertion cursor will automatically be drawn at this point whenever the text widget has the input focus. .PP The \fB\-blockcursor\fR widget option controls the drawing of the cursor. However, drawing the cursor as a solid blinking block is not exactly performed as in real or emulated terminals. The character at the cursor position is always drawn in it's foreground color, i.e. not in "reverse video", which can lead to unwanted visual effects and even hide the character entirely, when the cursor is in its on-state. .SH "THE MODIFIED FLAG" .PP The text widget can keep track of changes to the content of the widget by means of the modified flag. Inserting or deleting text will set this flag. The flag can be queried, set and cleared programmatically as well. Whenever the flag changes state a \fB<>\fR virtual event is generated. See the \fIpathName \fBedit modified\fR widget command for more details. .SH "THE UNDO MECHANISM" .PP The text widget has an unlimited undo and redo mechanism (when the \fB\-undo\fR widget option is true) which records every insert and delete action on a stack. .PP Boundaries (called .QW separators ) are inserted between edit actions. The purpose of these separators is to group inserts, deletes and replaces into one compound edit action. When undoing a change everything between two separators will be undone. The undone changes are then moved to the redo stack, so that an undone edit can be redone again. The redo stack is cleared whenever new edit actions are recorded on the undo stack. The undo and redo stacks can be cleared to keep their depth under control. .PP Separators are inserted automatically when the \fB\-autoseparators\fR widget option is true. You can insert separators programmatically as well. If a separator is already present at the top of the undo stack no other will be inserted. That means that two separators on the undo stack are always separated by at least one insert or delete action. .PP The \fB<>\fR virtual event is generated every time the undo stack or the redo stack becomes empty or unempty. .PP The undo mechanism is also linked to the modified flag. This means that undoing or redoing changes can take a modified text widget back to the unmodified state or vice versa. The modified flag will be set automatically to the appropriate state. This automatic coupling does not work when the modified flag has been set by the user, until the flag has been reset again. .PP See below for the \fIpathName \fBedit\fR widget command that controls the undo mechanism. .SH "PEER WIDGETS" .PP The text widget has a separate store of all its data concerning each line's textual contents, marks, tags, images and windows, and the undo stack. .PP While this data store cannot be accessed directly (i.e. without a text widget as an intermediary), multiple text widgets can be created, each of which present different views on the same underlying data. Such text widgets are known as peer text widgets. .PP As text is added, deleted, edited and coloured in any one widget, and as images, marks, tags are adjusted, all such changes will be reflected in all peers. .PP All data and markup is shared, except for a few small details. First, the \fBsel\fR tag may be set and configured (in its display style) differently for each peer. Second, each peer has its own \fBinsert\fR and \fBcurrent\fR mark positions (but all other marks are shared). Third, embedded windows, which are arbitrary other widgets, cannot be shared between peers. This means the \fB\-window\fR option of embedded windows is independently set for each peer (it is advisable to use the \fB\-create\fR script capabilities to allow each peer to create its own embedded windows as needed). Fourth, all of the configuration options of each peer (e.g. \fB\-font\fR, etc) can be set independently, with the exception of \fB\-undo\fR, \fB\-maxundo\fR, \fB\-autoseparators\fR (i.e. all undo, redo and modified state issues are shared). .PP Finally any single peer need not contain all lines from the underlying data store. When creating a peer, a contiguous range of lines (e.g. only lines 52 through 125) may be specified. This allows a peer to contain just a small portion of the overall text. The range of lines will expand and contract as text is inserted or deleted. The peer will only ever display complete lines of text (one cannot share just part of a line). If the peer's contents contracts to nothing (i.e. all complete lines in the peer widget have been deleted from another widget), then it is impossible for new lines to be inserted. The peer will simply become an empty shell on which the background can be configured, but which will never show any content (without manual reconfiguration of the start and end lines). Note that a peer which does not contain all of the underlying data store still has indices numbered from .QW 1.0 to .QW end . It is simply that those indices reflect a subset of the total data, and data outside the contained range is not accessible to the peer. This means that the command \fIpeerName \fBindex end\fR may return quite different values in different peers. Similarly, commands like \fIpeerName \fBtag ranges\fR will not return index ranges outside that which is meaningful to the peer. The configuration options \fB\-startline\fR and \fB\-endline\fR may be used to control how much of the underlying data is contained in any given text widget. .PP Note that peers are really peers. Deleting the .QW original text widget will not cause any other peers to be deleted, or otherwise affected. .PP See below for the \fIpathName \fBpeer\fR widget command that controls the creation of peer widgets. .SH "ASYNCHRONOUS UPDATE OF LINE HEIGHTS" .PP In order to maintain a responsive user-experience, the text widget calculates lines metrics (line heights in pixels) asynchronously. Because of this, some commands of the text widget may return wrong results if the asynchronous calculations are not finished at the time of calling. This applies to \fIpathName \fBcount \-ypixels\fR and \fIpathName \fByview\fR. .PP Again for performance reasons, it would not be appropriate to let these commands always wait for the end of the update calculation each time they are called. In most use cases of these commands a more or less inaccurate result does not really matter compared to execution speed. .PP In case accurate result is needed (and if the text widget is managed by a geometry manager), one can resort to \fIpathName \fBsync\fR and \fIpathName \fBpendingsync\fR to control the synchronization of the view of text widgets. .PP The \fB<>\fR virtual event fires when the line heights of the text widget become obsolete (due to some editing command or configuration change), and again when the internal data of the text widget are back in sync with the widget view. The detail field (%d substitution) is either true (when the widget is in sync) or false (when it is not). .PP \fIpathName \fBsync\fR, \fIpathName \fBpendingsync\fR and \fB<>\fR apply to each text widget independently of its peers. .PP Examples of use: .CS ## Example 1: # immediately complete line metrics at any cost (GUI unresponsive) $w sync $w yview moveto $fraction ## Example 2: # synchronously wait for up-to-date line metrics (GUI responsive) # before executing the scheduled command, but don't block execution flow $w sync -command [list $w yview moveto $fraction] ## Example 3: # init set yud($w) 0 proc updateaction w { \&set ::yud($w) 1 \&# any other update action here... } # runtime, synchronously wait for up-to-date line metrics (GUI responsive) $w sync -command [list updateaction $w] vwait yud($w) $w yview moveto $fraction ## Example 4: # init set todo($w) {} proc updateaction w { \&foreach cmd $::todo($w) {uplevel #0 $cmd} \&set todo($w) {} } # runtime lappend todo($w) [list $w yview moveto $fraction] $w sync -command [list updateaction $w] ## Example 5: # init set todo($w) {} bind $w <> { \&if {%d} { \&\&foreach cmd $todo(%W) {eval $cmd} \&\&set todo(%W) {} \&} } # runtime if {![$w pendingsync]} { \&$w yview moveto $fraction } else { \&lappend todo($w) [list $w yview moveto $fraction] } .CE .SH "WIDGET COMMAND" .PP The \fBtext\fR command creates a new Tcl command whose name is the same as the path name of the text's window. This command may be used to invoke various operations on the widget. It has the following general form: .CS \fIpathName option \fR?\fIarg ...\fR? .CE \fIPathName\fR is the name of the command, which is the same as the text widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for text widgets: .\" METHOD: bbox .TP \fIpathName \fBbbox \fIindex\fR . Returns a list of four elements describing the screen area of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the character, and the last two elements give the width and height of the area. If the character is only partially visible on the screen, then the return value reflects just the visible part. If the character is not visible on the screen then the return value is an empty list. .\" METHOD: cget .TP \fIpathName \fBcget\fI option\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBtext\fR command. .\" METHOD: compare .TP \fIpathName \fBcompare\fI index1 op index2\fR . Compares the indices given by \fIindex1\fR and \fIindex2\fR according to the relational operator given by \fIop\fR, and returns 1 if the relationship is satisfied and 0 if it is not. \fIOp\fR must be one of the operators <, <=, ==, >=, >, or !=. If \fIop\fR is == then 1 is returned if the two indices refer to the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR refers to an earlier character in the text than \fIindex2\fR, and so on. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBtext\fR command. .\" METHOD: count .TP \fIpathName \fBcount\fR ?\fIoptions\fR? \fIindex1 index2\fR . Counts the number of relevant things between the two indices. If \fIindex1\fR is after \fIindex2\fR, the result will be a negative number (and this holds for each of the possible options). The actual items which are counted depend on the options given. The result is a list of integers, one for the result of each counting option given. Valid counting options are \fB\-chars\fR, \fB\-displaychars\fR, \fB\-displayindices\fR, \fB\-displaylines\fR, \fB\-indices\fR, \fB\-lines\fR, \fB\-xpixels\fR and \fB\-ypixels\fR. The default value, if no option is specified, is \fB\-indices\fR. There is an additional possible option \fB\-update\fR which is a modifier. If given (and if the text widget is managed by a geometry manager), then all subsequent options ensure that any possible out of date information is recalculated. This currently only has any effect for the \fB\-ypixels\fR count (which, if \fB\-update\fR is not given, will use the text widget's current cached value for each line). This \fB\-update\fR option is obsoleted by \fIpathName \fBsync\fR, \fIpathName \fBpendingsync\fR and \fB<>\fR. The count options are interpreted as follows: .RS .IP \fB\-chars\fR count all characters, whether elided or not. Do not count embedded windows or images. .IP \fB\-displaychars\fR count all non-elided characters. .IP \fB\-displayindices\fR count all non-elided characters, windows and images. .IP \fB\-displaylines\fR count all display lines (i.e. counting one for each time a line wraps) from the line of the first index up to, but not including the display line of the second index. Therefore if they are both on the same display line, zero will be returned. By definition displaylines are visible and therefore this only counts portions of actual visible lines. .IP \fB\-indices\fR count all characters and embedded windows or images (i.e. everything which counts in text-widget index space), whether they are elided or not. .IP \fB\-lines\fR count all logical lines (irrespective of wrapping) from the line of the first index up to, but not including the line of the second index. Therefore if they are both on the same line, zero will be returned. Logical lines are counted whether they are currently visible (non-elided) or not. .IP \fB\-xpixels\fR count the number of horizontal pixels from the first pixel of the first index to (but not including) the first pixel of the second index. To count the total desired width of the text widget (assuming wrapping is not enabled), first find the longest line and then use .QW ".text count \-xpixels \N'34'${line}.0\N'34' \N'34'${line}.0 lineend\N'34'" . .IP \fB\-ypixels\fR count the number of vertical pixels from the first pixel of the first index to (but not including) the first pixel of the second index. If both indices are on the same display line, zero will be returned. To count the total number of vertical pixels in the text widget, use .QW ".text count \-ypixels 1.0 end" , and to ensure this is up to date, use .QW ".text count \-update \-ypixels 1.0 end" . .PP The command returns a positive or negative integer corresponding to the number of items counted between the two indices. One such integer is returned for each counting option given, so a list is returned if more than one option was supplied. For example .QW ".text count \-xpixels \-ypixels 1.3 4.5" is perfectly valid and will return a list of two elements. .RE .\" METHOD: debug .TP \fIpathName \fBdebug \fR?\fIboolean\fR? . If \fIboolean\fR is specified, then it must have one of the true or false values accepted by Tcl_GetBoolean. If the value is a true one then internal consistency checks will be turned on in the B-tree code associated with text widgets. If \fIboolean\fR has a false value then the debugging checks will be turned off. In either case the command returns an empty string. If \fIboolean\fR is not specified then the command returns \fBon\fR or \fBoff\fR to indicate whether or not debugging is turned on. There is a single debugging switch shared by all text widgets: turning debugging on or off in any widget turns it on or off for all widgets. For widgets with large amounts of text, the consistency checks may cause a noticeable slow-down. .RS .PP When debugging is turned on, the drawing routines of the text widget set the global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR to the lists of indices that are redrawn. The values of these variables are tested by Tk's test suite. .RE .\" METHOD: delete .TP \fIpathName \fBdelete \fIindex1 \fR?\fIindex2 ...\fR? . Delete a range of characters from the text. If both \fIindex1\fR and \fIindex2\fR are specified, then delete all the characters starting with the one given by \fIindex1\fR and stopping just before \fIindex2\fR (i.e. the character at \fIindex2\fR is not deleted). If \fIindex2\fR does not specify a position later in the text than \fIindex1\fR then no characters are deleted. If \fIindex2\fR is not specified then the single character at \fIindex1\fR is deleted. Attempts to delete characters in a way that would leave the text without a newline as the last character will be tweaked by the text widget to avoid this. In particular, deletion of complete lines of text up to the end of the text will also delete the newline character just before the deleted block so that it is replaced by the new final newline of the text widget. The command returns an empty string. If more indices are given, multiple ranges of text will be deleted. All indices are first checked for validity before any deletions are made. They are sorted and the text is removed from the last range to the first range so deleted text does not cause an undesired index shifting side-effects. If multiple ranges with the same start index are given, then the longest range is used. If overlapping ranges are given, then they will be merged into spans that do not cause deletion of text outside the given ranges due to text shifted during deletion. .\" METHOD: dlineinfo .TP \fIpathName \fBdlineinfo \fIindex\fR . Returns a list with five elements describing the area occupied by the display line containing \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the line, the third and fourth elements give the width and height of the area, and the fifth element gives the position of the baseline for the line, measured down from the top of the area. All of this information is measured in pixels. If the current wrap mode is \fBnone\fR and the line extends beyond the boundaries of the window, the area returned reflects the entire area of the line, including the portions that are out of the window. If the line is shorter than the full width of the window then the area returned reflects just the portion of the line that is occupied by characters and embedded windows. If the display line containing \fIindex\fR is not visible on the screen then the return value is an empty list. .\" METHOD: dump .TP \fIpathName \fBdump \fR?\fIswitches\fR? \fIindex1 \fR?\fIindex2\fR? . Return the contents of the text widget from \fIindex1\fR up to, but not including \fIindex2\fR, including the text and information about marks, tags, and embedded windows. If \fIindex2\fR is not specified, then it defaults to one character past \fIindex1\fR. The information is returned in the following format: .RS .LP \fIkey1 value1 index1 key2 value2 index2\fR ... .LP The possible \fIkey\fR values are \fBtext\fR, \fBmark\fR, \fBtagon\fR, \fBtagoff\fR, \fBimage\fR, and \fBwindow\fR. The corresponding \fIvalue\fR is the text, mark name, tag name, image name, or window name. The \fIindex\fR information is the index of the start of the text, mark, tag transition, image or window. One or more of the following switches (or abbreviations thereof) may be specified to control the dump: .\" OPTION: -all .TP \fB\-all\fR . Return information about all elements: text, marks, tags, images and windows. This is the default. .\" OPTION: -command .TP \fB\-command \fIcommand\fR . Instead of returning the information as the result of the dump operation, invoke the \fIcommand\fR on each element of the text widget within the range. The command has three arguments appended to it before it is evaluated: the \fIkey\fR, \fIvalue\fR, and \fIindex\fR. .\" OPTION: -image .TP \fB\-image\fR . Include information about images in the dump results. .\" OPTION: -mark .TP \fB\-mark\fR . Include information about marks in the dump results. .\" OPTION: -tag .TP \fB\-tag\fR . Include information about tag transitions in the dump results. Tag information is returned as \fBtagon\fR and \fBtagoff\fR elements that indicate the begin and end of each range of each tag, respectively. .\" OPTION: -text .TP \fB\-text\fR . Include information about text in the dump results. The value is the text up to the next element or the end of range indicated by \fIindex2\fR. A text element does not span newlines. A multi-line block of text that contains no marks or tag transitions will still be dumped as a set of text segments that each end with a newline. The newline is part of the value. .\" OPTION: -window .TP \fB\-window\fR . Include information about embedded windows in the dump results. The value of a window is its Tk pathname, unless the window has not been created yet. (It must have a create script.) In this case an empty string is returned, and you must query the window by its index position to get more information. .RE .\" METHOD: edit .TP \fIpathName \fBedit \fIoption \fR?\fIarg ...\fR? . This command controls the undo mechanism and the modified flag. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBedit\fR argument. The following forms of the command are currently supported: .RS .TP \fIpathName \fBedit canredo\fR . Returns a boolean true if redo is possible, i.e. when the redo stack is not empty. Otherwise returns false. .TP \fIpathName \fBedit canundo\fR . Returns a boolean true if undo is possible, i.e. when the undo stack is not empty. Otherwise returns false. .TP \fIpathName \fBedit modified \fR?\fIboolean\fR? . If \fIboolean\fR is not specified, returns the modified flag of the widget. The insert, delete, edit undo and edit redo commands or the user can set or clear the modified flag. If \fIboolean\fR is specified, sets the modified flag of the widget to \fIboolean\fR. .TP \fIpathName \fBedit redo\fR . When the \fB\-undo\fR option is true, reapplies the last undone edits provided no other edits were done since then, and returns a list of indices indicating what ranges were changed by the redo operation. Generates an error when the redo stack is empty. Does nothing when the \fB\-undo\fR option is false. .TP \fIpathName \fBedit reset\fR . Clears the undo and redo stacks. .TP \fIpathName \fBedit separator\fR . Inserts a separator (boundary) on the undo stack. Does nothing when the \fB\-undo\fR option is false. .TP \fIpathName \fBedit undo\fR . Undoes the last edit action when the \fB\-undo\fR option is true, and returns a list of indices indicating what ranges were changed by the undo operation. An edit action is defined as all the insert and delete commands that are recorded on the undo stack in between two separators. Generates an error when the undo stack is empty. Does nothing when the \fB\-undo\fR option is false. .RE .\" METHOD: get .TP \fIpathName \fBget\fR ?\fB\-displaychars\fR? ?\fB\-\-\fR? \fIindex1\fR ?\fIindex2 ...\fR? . Return a range of characters from the text. The return value will be all the characters in the text starting with the one whose index is \fIindex1\fR and ending just before the one whose index is \fIindex2\fR (the character at \fIindex2\fR will not be returned). If \fIindex2\fR is omitted then the single character at \fIindex1\fR is returned. If there are no characters in the specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR is less than or equal to \fIindex1\fR) then an empty string is returned. If the specified range contains embedded windows, no information about them is included in the returned string. If multiple index pairs are given, multiple ranges of text will be returned in a list. Invalid ranges will not be represented with empty strings in the list. The ranges are returned in the order passed to \fIpathName \fBget\fR. If the \fB\-displaychars\fR option is given, then, within each range, only those characters which are not elided will be returned. This may have the effect that some of the returned ranges are empty strings. .\" METHOD: image .TP \fIpathName \fBimage \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate embedded images. The behavior of the command depends on the \fIoption\fR argument that follows the \fBimage\fR argument. The following forms of the command are currently supported: .RS .TP \fIpathName \fBimage cget \fIindex option\fR . Returns the value of a configuration option for an embedded image. \fIIndex\fR identifies the embedded image, and \fIoption\fR specifies a particular configuration option, which must be one of the ones listed in the section \fBEMBEDDED IMAGES\fR. .TP \fIpathName \fBimage configure \fIindex\fR ?\fIoption value ...\fR? . Query or modify the configuration options for an embedded image. If no \fIoption\fR is specified, returns a list describing all of the available options for the embedded image at \fIindex\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. See \fBEMBEDDED IMAGES\fR for information on the options that are supported. .TP \fIpathName \fBimage create \fIindex\fR ?\fIoption value ...\fR? . This command creates a new image annotation, which will appear in the text at the position given by \fIindex\fR. Any number of \fIoption\-value\fR pairs may be specified to configure the annotation. Returns a unique identifier that may be used as an index to refer to this image. See \fBEMBEDDED IMAGES\fR for information on the options that are supported, and a description of the identifier returned. .TP \fIpathName \fBimage names\fR . Returns a list whose elements are the names of all image instances currently embedded in \fIwindow\fR. .RE .\" METHOD: index .TP \fIpathName \fBindex \fIindex\fR . Returns the position corresponding to \fIindex\fR in the form \fIline.char\fR where \fIline\fR is the line number and \fIchar\fR is the character number. \fIIndex\fR may have any of the forms described under \fBINDICES\fR above. .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex chars \fR?\fItagList chars tagList ...\fR? . Inserts all of the \fIchars\fR arguments just before the character at \fIindex\fR. If \fIindex\fR refers to the end of the text (the character after the last newline) then the new text is inserted just before the last newline instead. If there is a single \fIchars\fR argument and no \fItagList\fR, then the new text will receive any tags that are present on both the character before and the character after the insertion point; if a tag is present on only one of these characters then it will not be applied to the new text. If \fItagList\fR is specified then it consists of a list of tag names; the new characters will receive all of the tags in this list and no others, regardless of the tags present around the insertion point. If multiple \fIchars\fR\-\fItagList\fR argument pairs are present, they produce the same effect as if a separate \fIpathName \fBinsert\fR widget command had been issued for each pair, in order. The last \fItagList\fR argument may be omitted. .\" METHOD: mark .TP \fIpathName \fBmark \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate marks. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBmark\fR argument. The following forms of the command are currently supported: .RS .TP \fIpathName \fBmark gravity \fImarkName\fR ?\fIdirection\fR? . If \fIdirection\fR is not specified, returns \fBleft\fR or \fBright\fR to indicate which of its adjacent characters \fImarkName\fR is attached to. If \fIdirection\fR is specified, it must be \fBleft\fR or \fBright\fR; the gravity of \fImarkName\fR is set to the given value. .TP \fIpathName \fBmark names\fR . Returns a list whose elements are the names of all the marks that are currently set. .TP \fIpathName \fBmark next \fIindex\fR . Returns the name of the next mark at or after \fIindex\fR. If \fIindex\fR is specified in numerical form, then the search for the next mark begins at that index. If \fIindex\fR is the name of a mark, then the search for the next mark begins immediately after that mark. This can still return a mark at the same position if there are multiple marks at the same index. These semantics mean that the \fBmark next\fR operation can be used to step through all the marks in a text widget in the same order as the mark information returned by the \fIpathName \fBdump\fR operation. If a mark has been set to the special \fBend\fR index, then it appears to be \fIafter \fBend\fR with respect to the \fIpathName \fBmark next\fR operation. An empty string is returned if there are no marks after \fIindex\fR. .TP \fIpathName \fBmark previous \fIindex\fR . Returns the name of the mark at or before \fIindex\fR. If \fIindex\fR is specified in numerical form, then the search for the previous mark begins with the character just before that index. If \fIindex\fR is the name of a mark, then the search for the next mark begins immediately before that mark. This can still return a mark at the same position if there are multiple marks at the same index. These semantics mean that the \fIpathName \fBmark previous\fR operation can be used to step through all the marks in a text widget in the reverse order as the mark information returned by the \fIpathName \fBdump\fR operation. An empty string is returned if there are no marks before \fIindex\fR. .TP \fIpathName \fBmark set \fImarkName index\fR . Sets the mark named \fImarkName\fR to a position just before the character at \fIindex\fR. If \fImarkName\fR already exists, it is moved from its old position; if it does not exist, a new mark is created. This command returns an empty string. .TP \fIpathName \fBmark unset \fImarkName \fR?\fImarkName markName ...\fR? . Remove the mark corresponding to each of the \fImarkName\fR arguments. The removed marks will not be usable in indices and will not be returned by future calls to .QW "\fIpathName \fBmark names\fR" . This command returns an empty string. .RE .\" METHOD: peer .TP \fIpathName \fBpeer \fIoption args\fR . This command is used to create and query widget peers. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBpeer create \fInewPathName\fR ?\fIoptions\fR? . Creates a peer text widget with the given \fInewPathName\fR, and any optional standard configuration options (as for the \fItext\fR command). By default the peer will have the same start and end line as the parent widget, but these can be overridden with the standard configuration options. .TP \fIpathName \fBpeer names\fR . Returns a list of peers of this widget (this does not include the widget itself). The order within this list is undefined. .RE .\" METHOD: pendingsync .TP \fIpathName \fBpendingsync\fR . Returns 1 if the line heights calculations are not up-to-date, 0 otherwise. .\" METHOD: replace .TP \fIpathName \fBreplace\fI index1 index2 chars\fR ?\fItagList chars tagList ...\fR? . Replaces the range of characters between \fIindex1\fR and \fIindex2\fR with the given characters and tags. See the section on \fIpathName \fBinsert\fR for an explanation of the handling of the \fItagList...\fR arguments, and the section on \fIpathName \fBdelete\fR for an explanation of the handling of the indices. If \fIindex2\fR corresponds to an index earlier in the text than \fIindex1\fR, an error will be generated. .RS .PP The deletion and insertion are arranged so that no unnecessary scrolling of the window or movement of insertion cursor occurs. In addition the undo/redo stack are correctly modified, if undo operations are active in the text widget. The command returns an empty string. .RE .\" METHOD: scan .TP \fIpathName \fBscan \fIoption args\fR . This command is used to implement scanning on texts. It has two forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBscan mark \fIx y\fR . Records \fIx\fR and \fIy\fR and the current view in the text window, for use in conjunction with later \fIpathName \fBscan dragto\fR commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. .TP \fIpathName \fBscan dragto \fIx y\fR . This command computes the difference between its \fIx\fR and \fIy\fR arguments and the \fIx\fR and \fIy\fR arguments to the last \fIpathName \fBscan mark\fR command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the text at high speed through the window. The return value is an empty string. .RE .\" METHOD: search .TP \fIpathName \fBsearch \fR?\fIswitches\fR? \fIpattern index \fR?\fIstopIndex\fR? . Searches the text in \fIpathName\fR starting at \fIindex\fR for a range of characters that matches \fIpattern\fR. If a match is found, the index of the first character in the match is returned as result; otherwise an empty string is returned. One or more of the following switches (or abbreviations thereof) may be specified to control the search: .RS .\" OPTION: -forwards .TP \fB\-forwards\fR . The search will proceed forward through the text, finding the first matching range starting at or after the position given by \fIindex\fR. This is the default. .\" OPTION: -backwards .TP \fB\-backwards\fR . The search will proceed backward through the text, finding the matching range closest to \fIindex\fR whose first character is before \fIindex\fR (it is not allowed to be at \fIindex\fR). Note that, for a variety of reasons, backwards searches can be substantially slower than forwards searches (particularly when using \fB\-regexp\fR), so it is recommended that performance-critical code use forward searches. .\" OPTION: -exact .TP \fB\-exact\fR . Use exact matching: the characters in the matching range must be identical to those in \fIpattern\fR. This is the default. .\" OPTION: -regexp .TP \fB\-regexp\fR . Treat \fIpattern\fR as a regular expression and match it against the text using the rules for regular expressions (see the \fBregexp\fR command and the \fBre_syntax\fR page for details). The default matching automatically passes both the \fB\-lineanchor\fR and \fB\-linestop\fR options to the regexp engine (unless \fB\-nolinestop\fR is used), so that \fI^$\fR match beginning and end of line, and \fI.\fR, \fI[^\fR sequences will never match the newline character \fI\en\fR. .\" OPTION: -nolinestop .TP \fB\-nolinestop\fR . This allows \fI.\fR and \fI[^\fR sequences to match the newline character \fI\en\fR, which they will otherwise not do (see the \fBregexp\fR command for details). This option is only meaningful if \fB\-regexp\fR is also given, and an error will be thrown otherwise. For example, to match the entire text, use .QW "\fIpathName \fBsearch \-nolinestop \-regexp\fR \N'34'.*\N'34' 1.0" . .\" OPTION: -nocase .TP \fB\-nocase\fR . Ignore case differences between the pattern and the text. .\" OPTION: -count .TP \fB\-count\fI varName\fR . The argument following \fB\-count\fR gives the name of a variable; if a match is found, the number of index positions between beginning and end of the matching range will be stored in the variable. If there are no embedded images or windows in the matching range (and there are no elided characters if \fB\-elide\fR is not given), this is equivalent to the number of characters matched. In either case, the range \fImatchIdx\fR to \fImatchIdx + $count chars\fR will return the entire matched text. .\" OPTION: -all .TP \fB\-all\fR . Find all matches in the given range and return a list of the indices of the first character of each match. If a \fB\-count\fI varName\fR switch is given, then \fIvarName\fR is also set to a list containing one element for each successful match. Note that, even for exact searches, the elements of this list may be different, if there are embedded images, windows or hidden text. Searches with \fB\-all\fR behave very similarly to the Tcl command \fBregexp \-all\fR, in that overlapping matches are not normally returned. For example, applying an \fB\-all\fR search of the pattern .QW \ew+ against .QW "hello there" will just match twice, once for each word, and matching .QW "Z[a\-z]+Z" against .QW ZooZooZoo will just match once. .\" OPTION: -overlap .TP \fB\-overlap\fR . When performing \fB\-all\fR searches, the normal behaviour is that matches which overlap an already-found match will not be returned. This switch changes that behaviour so that all matches which are not totally enclosed within another match are returned. For example, applying an \fB\-overlap\fR search of the pattern .QW \ew+ against .QW "hello there" will just match twice (i.e. no different to just \fB\-all\fR), but matching .QW Z[a\-z]+Z against .QW ZooZooZoo will now match twice. An error will be thrown if this switch is used without \fB\-all\fR. .\" OPTION: -strictlimits .TP \fB\-strictlimits\fR . When performing any search, the normal behaviour is that the start and stop limits are checked with respect to the start of the matching text. With the \fB\-strictlimits\fR flag, the entire matching range must lie inside the start and stop limits specified for the match to be valid. .\" OPTION: -elide .TP \fB\-elide\fR . Find elided (hidden) text as well. By default only displayed text is searched. .\" OPTION: -- .TP \fB\-\|\-\fR . This switch has no effect except to terminate the list of switches: the next argument will be treated as \fIpattern\fR even if it starts with \fB\-\fR. .PP The matching range may be within a single line of text, or run across multiple lines (if parts of the pattern can match a new-line). For regular expression matching one can use the various newline-matching features such as \fB$\fR to match the end of a line, \fB^\fR to match the beginning of a line, and to control whether \fB.\fR is allowed to match a new-line. If \fIstopIndex\fR is specified, the search stops at that index: for forward searches, no match at or after \fIstopIndex\fR will be considered; for backward searches, no match earlier in the text than \fIstopIndex\fR will be considered. If \fIstopIndex\fR is omitted, the entire text will be searched: when the beginning or end of the text is reached, the search continues at the other end until the starting location is reached again; if \fIstopIndex\fR is specified, no wrap-around will occur. This means that, for example, if the search is \fB\-forwards\fR but \fIstopIndex\fR is earlier in the text than \fIstartIndex\fR, nothing will ever be found. See \fBKNOWN BUGS\fR below for a number of minor limitations of the \fIpathName \fBsearch\fR command. .RE .\" METHOD: see .TP \fIpathName \fBsee \fIindex\fR . Adjusts the view in the window so that the character given by \fIindex\fR is completely visible. If \fIindex\fR is already visible then the command does nothing. If \fIindex\fR is a short distance out of view, the command adjusts the view just enough to make \fIindex\fR visible at the edge of the window. If \fIindex\fR is far out of view, then the command centers \fIindex\fR in the window. .\" METHOD: sync .TP \fIpathName \fBsync\fR ?\fB\-command \fIcommand\fR? . Controls the synchronization of the view of the text widget. .RS .TP \fIpathName \fBsync\fR . Immediately brings the line metrics up-to-date by forcing computation of any outdated line heights. The command returns immediately if there is no such outdated line heights, otherwise it returns only at the end of the computation. The command returns an empty string. .TP \fIpathName \fBsync \-command \fIcommand\fR . Schedules \fIcommand\fR to be executed (by the event loop) exactly once as soon as all line heights are up-to-date. If there are no pending line metrics calculations, the scheduling is immediate. The command returns the empty string. \fBbgerror\fR is called on \fIcommand\fR failure. .RE .\" METHOD: tag .TP \fIpathName \fBtag \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate tags. The exact behavior of the command depends on the \fIoption\fR argument that follows the \fBtag\fR argument. The following forms of the command are currently supported: .RS .TP \fIpathName \fBtag add \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR? . Associate the tag \fItagName\fR with all of the characters starting with \fIindex1\fR and ending just before \fIindex2\fR (the character at \fIindex2\fR is not tagged). A single command may contain any number of \fIindex1\fR\-\fIindex2\fR pairs. If the last \fIindex2\fR is omitted then the single character at \fIindex1\fR is tagged. If there are no characters in the specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR is less than or equal to \fIindex1\fR) then the command has no effect. .TP \fIpathName \fBtag bind \fItagName\fR ?\fIsequence\fR? ?\fIscript\fR? . This command associates \fIscript\fR with the tag given by \fItagName\fR. Whenever the event sequence given by \fIsequence\fR occurs for a character that has been tagged with \fItagName\fR, the script will be invoked. This widget command is similar to the \fBbind\fR command except that it operates on characters in a text rather than entire widgets. See the \fBbind\fR manual entry for complete details on the syntax of \fIsequence\fR and the substitutions performed on \fIscript\fR before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same \fIsequence\fR and \fItagName\fR (if the first character of \fIscript\fR is .QW + then \fIscript\fR augments an existing binding rather than replacing it). In this case the return value is an empty string. If \fIscript\fR is omitted then the command returns the \fIscript\fR associated with \fItagName\fR and \fIsequence\fR (an error occurs if there is no such binding). If both \fIscript\fR and \fIsequence\fR are omitted then the command returns a list of all the sequences for which bindings have been defined for \fItagName\fR. .RS .PP The only events for which bindings may be specified are those related to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, \fBButton\fR, \fBMotion\fR, and \fBKey\fR) or virtual events. Mouse and keyboard event bindings for a text widget respectively use the \fBcurrent\fR and \fBinsert\fR marks described under \fBMARKS\fR above. An \fBEnter\fR event triggers for a tag when the tag first becomes present on the current character, and a \fBLeave\fR event triggers for a tag when it ceases to be present on the current character. \fBEnter\fR and \fBLeave\fR events can happen either because the \fBcurrent\fR mark moved or because the character at that position changed. Note that these events are different than \fBEnter\fR and \fBLeave\fR events for windows. Mouse events are directed to the current character, while keyboard events are directed to the insert character. If a virtual event is used in a binding, that binding can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event. .PP It is possible for the current character to have multiple tags, and for each of them to have a binding for a particular event sequence. When this occurs, one binding is invoked for each tag, in order from lowest-priority to highest priority. If there are multiple matching bindings for a single tag, then the most specific binding is chosen (see the manual entry for the \fBbind\fR command for details). \fBcontinue\fR and \fBbreak\fR commands within binding scripts are processed in the same way as for bindings created with the \fBbind\fR command. .PP If bindings are created for the widget as a whole using the \fBbind\fR command, then those bindings will supplement the tag bindings. The tag bindings will be invoked first, followed by bindings for the window as a whole. .RE .TP \fIpathName \fBtag cget \fItagName option\fR . This command returns the current value of the option named \fIoption\fR associated with the tag given by \fItagName\fR. \fIOption\fR may have any of the values accepted by the \fIpathName \fBtag configure\fR widget command. .TP \fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? . This command is similar to the \fIpathName \fBconfigure\fR widget command except that it modifies options associated with the tag given by \fItagName\fR instead of modifying options for the overall text widget. If no \fIoption\fR is specified, the command returns a list describing all of the available options for \fItagName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s) in \fItagName\fR; in this case the command returns an empty string. See \fBTAGS\fR above for details on the options available for tags. .TP \fIpathName \fBtag delete \fItagName \fR?\fItagName ...\fR? . Deletes all tag information for each of the \fItagName\fR arguments. The command removes the tags from all characters in the file and also deletes any other information associated with the tags, such as bindings and display information. The command returns an empty string. .TP \fIpathName\fB tag lower \fItagName \fR?\fIbelowThis\fR? . Changes the priority of tag \fItagName\fR so that it is just lower in priority than the tag whose name is \fIbelowThis\fR. If \fIbelowThis\fR is omitted, then \fItagName\fR's priority is changed to make it lowest priority of all tags. .TP \fIpathName \fBtag names \fR?\fIindex\fR? . Returns a list whose elements are the names of all the tags that are active at the character position given by \fIindex\fR. If \fIindex\fR is omitted, then the return value will describe all of the tags that exist for the text (this includes all tags that have been named in a .QW "\fIpathName \fBtag\fR" widget command but have not been deleted by a .QW "\fIpathName \fBtag delete\fR" widget command, even if no characters are currently marked with the tag). The list will be sorted in order from lowest priority to highest priority. .TP \fIpathName \fBtag nextrange \fItagName index1 \fR?\fIindex2\fR? . This command searches the text for a range of characters tagged with \fItagName\fR where the first character of the range is no earlier than the character at \fIindex1\fR and no later than the character just before \fIindex2\fR (a range starting at \fIindex2\fR will not be considered). If several matching ranges exist, the first one is chosen. The command's return value is a list containing two elements, which are the index of the first character of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If \fIindex2\fR is not given then it defaults to the end of the text. .TP \fIpathName \fBtag prevrange \fItagName index1 \fR?\fIindex2\fR? . This command searches the text for a range of characters tagged with \fItagName\fR where the first character of the range is before the character at \fIindex1\fR and no earlier than the character at \fIindex2\fR (a range starting at \fIindex2\fR will be considered). If several matching ranges exist, the one closest to \fIindex1\fR is chosen. The command's return value is a list containing two elements, which are the index of the first character of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If \fIindex2\fR is not given then it defaults to the beginning of the text. .TP \fIpathName \fBtag raise \fItagName \fR?\fIaboveThis\fR? . Changes the priority of tag \fItagName\fR so that it is just higher in priority than the tag whose name is \fIaboveThis\fR. If \fIaboveThis\fR is omitted, then \fItagName\fR's priority is changed to make it highest priority of all tags. .TP \fIpathName \fBtag ranges \fItagName\fR . Returns a list describing all of the ranges of text that have been tagged with \fItagName\fR. The first two elements of the list describe the first tagged range in the text, the next two elements describe the second range, and so on. The first element of each pair contains the index of the first character of the range, and the second element of the pair contains the index of the character just after the last one in the range. If there are no characters tagged with \fItag\fR then an empty string is returned. .TP \fIpathName \fBtag remove \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR? . Remove the tag \fItagName\fR from all of the characters starting at \fIindex1\fR and ending just before \fIindex2\fR (the character at \fIindex2\fR is not affected). A single command may contain any number of \fIindex1\fR\-\fIindex2\fR pairs. If the last \fIindex2\fR is omitted then the tag is removed from the single character at \fIindex1\fR. If there are no characters in the specified range (e.g. \fIindex1\fR is past the end of the file or \fIindex2\fR is less than or equal to \fIindex1\fR) then the command has no effect. This command returns an empty string. .RE .\" METHOD: window .TP \fIpathName \fBwindow \fIoption \fR?\fIarg ...\fR? . This command is used to manipulate embedded windows. The behavior of the command depends on the \fIoption\fR argument that follows the \fBwindow\fR argument. The following forms of the command are currently supported: .RS .TP \fIpathName \fBwindow cget \fIindex option\fR . Returns the value of a configuration option for an embedded window. \fIIndex\fR identifies the embedded window, and \fIoption\fR specifies a particular configuration option, which must be one of the ones listed in the section \fBEMBEDDED WINDOWS\fR. .TP \fIpathName \fBwindow configure \fIindex\fR ?\fIoption value ...\fR? . Query or modify the configuration options for an embedded window. If no \fIoption\fR is specified, returns a list describing all of the available options for the embedded window at \fIindex\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. See \fBEMBEDDED WINDOWS\fR for information on the options that are supported. .TP \fIpathName \fBwindow create \fIindex\fR ?\fIoption value ...\fR? . This command creates a new window annotation, which will appear in the text at the position given by \fIindex\fR. Any number of \fIoption\-value\fR pairs may be specified to configure the annotation. See \fBEMBEDDED WINDOWS\fR for information on the options that are supported. Returns an empty string. .TP \fIpathName \fBwindow names\fR . Returns a list whose elements are the names of all windows currently embedded in \fIwindow\fR. .RE .\" METHOD: xview .TP \fIpathName \fBxview \fIoption args\fR . This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fBxview\fR . Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the portion of the document's horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. The fractions refer only to the lines that are actually visible in the window: if the lines in the window are all very short, so that they are entirely visible, the returned fractions will be 0 and 1, even if there are other lines in the text that are much wider than the window. These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR option. .TP \fIpathName \fBxview moveto\fI fraction\fR . Adjusts the view in the window so that \fIfraction\fR of the horizontal span of the text is off-screen to the left. \fIFraction\fR is a fraction between 0 and 1. .TP \fIpathName \fBxview scroll \fInumber what\fR . This command shifts the view in the window left or right according to \fInumber\fR and \fIwhat\fR. \fIWhat\fR must be \fBpages\fR, \fBpixels\fR, or \fBunits\fR. If \fIwhat\fR is \fBpages\fR or \fBunits\fR then \fInumber\fR must be an integer, otherwise number may be specified in any of the forms acceptable to \fBTk_GetPixels\fR, such as .QW 2.0c or .QW 1i (the result is rounded to the nearest integer value. If no units are given, pixels are assumed). If \fIwhat\fR is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls; if it is \fBpixels\fR then the view adjusts by \fInumber\fR pixels; if it is \fBunits\fR, the view adjusts left or right by \fInumber\fR average-width characters on the display. If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. .RE .\" METHOD: yview .TP \fIpathName \fByview \fR?\fIargs\fR? . This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms: .RS .TP \fIpathName \fByview\fR . Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the first visible pixel of the first character (or image, etc) in the top line in the window, relative to the text as a whole (0.5 means it is halfway through the text, for example). The second element gives the position of the first pixel just after the last visible one in the bottom line of the window, relative to the text as a whole. These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR option. .TP \fIpathName \fByview moveto\fI fraction\fR . Adjusts the view in the window so that the pixel given by \fIfraction\fR appears at the top of the top line of the window. \fIFraction\fR is a fraction between 0 and 1; 0 indicates the first pixel of the first character in the text, 0.33 indicates the pixel that is one-third the way through the text; and so on. Values close to 1 will indicate values close to the last pixel in the text (1 actually refers to one pixel beyond the last pixel), but in such cases the widget will never scroll beyond the last pixel, and so a value of 1 will effectively be rounded back to whatever fraction ensures the last pixel is at the bottom of the window, and some other pixel is at the top. .TP \fIpathName \fByview scroll \fInumber what\fR . This command adjust the view in the window up or down according to \fInumber\fR and \fIwhat\fR. \fIWhat\fR must be \fBpages\fR, \fBpixels\fR, or \fBunits\fR. If \fIwhat\fR is \fBunits\fR or \fBpages\fR then \fInumber\fR must be an integer, otherwise number may be specified in any of the forms acceptable to \fBTk_GetPixels\fR, such as .QW 2.0c or .QW 1i (the result is rounded to the nearest integer value. If no units are given, pixels are assumed). If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by \fInumber\fR lines on the display; if it is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls; if it is \fBpixels\fR then the view adjusts by \fInumber\fR pixels. If \fInumber\fR is negative then earlier positions in the text become visible; if it is positive then later positions in the text become visible. .TP \fIpathName \fByview \fR?\fB\-pickplace\fR? \fIindex\fR . Changes the view in the widget's window to make \fIindex\fR visible. If the \fB\-pickplace\fR option is not specified then \fIindex\fR will appear at the top of the window. If \fB\-pickplace\fR is specified then the widget chooses where \fIindex\fR appears in the window: .RS .IP [1] If \fIindex\fR is already visible somewhere in the window then the command does nothing. .IP [2] If \fIindex\fR is only a few lines off-screen above the window then it will be positioned at the top of the window. .IP [3] If \fIindex\fR is only a few lines off-screen below the window then it will be positioned at the bottom of the window. .IP [4] Otherwise, \fIindex\fR will be centered in the window. .PP The \fB\-pickplace\fR option has been obsoleted by the \fIpathName \fBsee\fR widget command (\fIpathName \fBsee\fR handles both x- and y-motion to make a location visible, whereas the \fB\-pickplace\fR mode only handles motion in y). .RE .TP \fIpathName \fByview \fInumber\fR . This command makes the first character on the line after the one given by \fInumber\fR visible at the top of the window. \fINumber\fR must be an integer. This command used to be used for scrolling, but now it is obsolete. .RE .SH BINDINGS .PP Tk automatically creates class bindings for texts that give them the following default behavior. In the descriptions below, .QW word is dependent on the value of the \fBtcl_wordchars\fR variable. See \fBtclvars\fR(n). .IP [1] Clicking mouse button 1 positions the insertion cursor at the closest edge of the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse. .IP [2] Double-clicking with mouse button 1 selects the word under the mouse and positions the insertion cursor at the start of the word. Dragging after a double click will stroke out a selection consisting of whole words. .IP [3] Triple-clicking with mouse button 1 selects the line under the mouse and positions the insertion cursor at the start of the line. Dragging after a triple click will stroke out a selection consisting of whole lines. .IP [4] The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words; if it is triple-clicked then the selection will be adjusted in units of whole lines. .IP [5] Clicking mouse button 1 with the Control key down will reposition the insertion cursor without affecting the selection. .IP [6] If any normal printing characters are typed, they are inserted at the point of the insertion cursor. .IP [7] The view in the widget can be adjusted by dragging with the middle mouse button (button 2, or button 3 in TkAqua). If the middle mouse button is clicked without moving the mouse, the selection is copied into the text at the position of the mouse cursor. The Insert key also inserts the selection, but at the position of the insertion cursor. .IP [8] If the mouse is dragged out of the widget while button 1 is pressed, the entry will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window). .IP [9] The Left and Right keys move the insertion cursor one character to the left or right; they also clear any selection in the text. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f behave the same as Control-Left and Control-Right, respectively. .IP [10] The Up and Down keys move the insertion cursor one line up or down and clear any selection in the text. If Up or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Up and Control-Down move the insertion cursor by paragraphs (groups of lines separated by blank lines), and Control-Shift-Up and Control-Shift-Down move the insertion cursor by paragraphs and also extend the selection. Control-p and Control-n behave the same as Up and Down, respectively. .IP [11] The Next and Prior keys move the insertion cursor forward or backwards by one screenful and clear any selection in the text. If the Shift key is held down while Next or Prior is typed, then the selection is extended to include the new character. .IP [12] Control-Next and Control-Prior scroll the view right or left by one page without moving the insertion cursor or affecting the selection. .IP [13] Home and Control-a move the insertion cursor to the beginning of its display line and clear any selection in the widget. Shift-Home moves the insertion cursor to the beginning of the display line and also extends the selection to that point. .IP [14] End and Control-e move the insertion cursor to the end of the display line and clear any selection in the widget. Shift-End moves the cursor to the end of the display line and extends the selection to that point. .IP [15] Control-Home and Meta-< move the insertion cursor to the beginning of the text and clear any selection in the widget. Control-Shift-Home moves the insertion cursor to the beginning of the text and also extends the selection to that point. .IP [16] Control-End and Meta-> move the insertion cursor to the end of the text and clear any selection in the widget. Control-Shift-End moves the cursor to the end of the text and extends the selection to that point. .IP [17] The Select key and Control-Space set the selection anchor to the position of the insertion cursor. They do not affect the current selection. Shift-Select and Control-Shift-Space adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was not any selection previously. .IP [18] Control-/ selects the entire contents of the widget. .IP [19] Control-\e clears any selection in the widget. .IP [20] The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection. This action is carried out by the command \fBtk_textCopy\fR. .IP [21] The F20 key (labelled Cut on many Sun workstations) or Control-w copies the selection in the widget to the clipboard and deletes the selection. This action is carried out by the command \fBtk_textCut\fR. If there is no selection in the widget then these keys have no effect. .IP [22] The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the contents of the clipboard at the position of the insertion cursor. This action is carried out by the command \fBtk_textPaste\fR. .IP [23] The Delete key deletes the selection, if there is one in the widget. If there is no selection, it deletes the character to the right of the insertion cursor. .IP [24] Backspace and Control-h delete the selection, if there is one in the widget. If there is no selection, they delete the character to the left of the insertion cursor. .IP [25] Control-d deletes the character to the right of the insertion cursor. .IP [26] Meta-d deletes the word to the right of the insertion cursor. .IP [27] Control-k deletes from the insertion cursor to the end of its line; if the insertion cursor is already at the end of a line, then Control-k deletes the newline character. .IP [28] Control-o opens a new line by inserting a newline character in front of the insertion cursor without moving the insertion cursor. .IP [29] Meta-backspace and Meta-Delete delete the word to the left of the insertion cursor. .IP [30] Control-t reverses the order of the two characters to the right of the insertion cursor. .IP [31] Control-x deletes whatever is selected in the text widget after copying it to the clipboard. .IP [32] Control-z undoes the last edit action if the \fB\-undo\fR option is true. Does nothing otherwise. .IP [33] Control-Z (or Control-y on Windows) reapplies the last undone edit action if the \fB\-undo\fR option is true. Does nothing otherwise. .PP If the widget is disabled using the \fB\-state\fR option, then its view can still be adjusted and text can still be selected, but no insertion cursor will be displayed and no text modifications will take place. .PP The behavior of texts can be changed by defining new bindings for individual widgets or by redefining the class bindings. .SH "KNOWN ISSUES" .SS "ISSUES CONCERNING CHARS AND INDICES" .PP Before Tk 8.5, the widget used the string .QW chars to refer to index positions (which included characters, embedded windows and embedded images). As of Tk 8.5 the text widget deals separately and correctly with .QW chars and .QW indices . For backwards compatibility, however, the index modifiers .QW "+N chars" and .QW "\-N chars" continue to refer to indices. One must use any of the full forms .QW "+N any chars" or .QW "\-N any chars" etc. to refer to actual character indices. This confusion may be fixed in a future release by making the widget correctly interpret .QW "+N chars" as a synonym for .QW "+N any chars" . .SS "PERFORMANCE ISSUES" .PP Text widgets should run efficiently under a variety of conditions. The text widget uses about 2-3 bytes of main memory for each byte of text, so texts containing a megabyte or more should be practical on most workstations. Text is represented internally with a modified B-tree structure that makes operations relatively efficient even with large texts. Tags are included in the B-tree structure in a way that allows tags to span large ranges or have many disjoint smaller ranges without loss of efficiency. Marks are also implemented in a way that allows large numbers of marks. In most cases it is fine to have large numbers of unique tags, or a tag that has many distinct ranges. .PP One performance problem can arise if you have hundreds or thousands of different tags that all have the following characteristics: the first and last ranges of each tag are near the beginning and end of the text, respectively, or a single tag range covers most of the text widget. The cost of adding and deleting tags like this is proportional to the number of other tags with the same properties. In contrast, there is no problem with having thousands of distinct tags if their overall ranges are localized and spread uniformly throughout the text. .PP Very long text lines can be expensive, especially if they have many marks and tags within them. .PP The display line with the insert cursor is redrawn each time the cursor blinks, which causes a steady stream of graphics traffic. Set the \fB\-insertofftime\fR attribute to 0 avoid this. .SS "KNOWN BUGS" .PP The \fIpathName \fBsearch \-regexp\fR sub-command attempts to perform sophisticated regexp matching across multiple lines in an efficient fashion (since Tk 8.5), examining each line individually, and then in small groups of lines, whether searching forwards or backwards. Under certain conditions the search result might differ from that obtained by applying the same regexp to the entire text from the widget in one go. For example, when searching with a greedy regexp, the widget will continue to attempt to add extra lines to the match as long as one of two conditions are true: either Tcl's regexp library returns a code to indicate a longer match is possible (but there are known bugs in Tcl which mean this code is not always correctly returned); or if each extra line added results in at least a partial match with the pattern. This means in the case where the first extra line added results in no match and Tcl's regexp system returns the incorrect code and adding a second extra line would actually match, the text widget will return the wrong result. In practice this is a rare problem, but it can occur, for example: .CS pack [\fBtext\fR .t] \&.t insert 1.0 "aaaa\enbbbb\encccc\enbbbb\enaaaa\en" \&.t search -regexp -- {(a+|b+\enc+\enb+)+\ena+} 1.0 .CE will not find a match when one exists of 19 characters starting from the first .QW b . .PP Whenever one possible match is fully enclosed in another, the search command will attempt to ensure only the larger match is returned. When performing backwards regexp searches it is possible that Tcl will not always achieve this, in the case where a match is preceded by one or more short, non-overlapping matches, all of which are preceded by a large match which actually encompasses all of them. The search algorithm used by the widget does not look back arbitrarily far for a possible match which might cover large portions of the widget. For example: .CS pack [\fBtext\fR .t] \&.t insert 1.0 "aaaa\enbbbb\enbbbb\enbbbb\enbbbb\\n" \&.t search -regexp -backward -- {b+\en|a+\en(b+\en)+} end .CE matches at .QW 5.0 when a true greedy match would match at .QW 1.0 . Similarly if we add \fB\-all\fR to this case, it matches at all of .QW 5.0 , .QW 4.0 , .QW 3.0 and .QW 1.0 , when really it should only match at .QW 1.0 since that match encloses all the others. .SH "SEE ALSO" entry(n), scrollbar(n) .SH KEYWORDS text, widget, tkvars '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/TextLayout.30000644001000000100000000003416015105057705020026 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_ComputeTextLayout 3 8.1 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text. .SH SYNOPSIS .nf \fB#include \fR .sp Tk_TextLayout \fBTk_ComputeTextLayout\fR(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fR) .sp \fBTk_FreeTextLayout\fR(\fIlayout\fR) .sp \fBTk_DrawTextLayout\fR(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fR) .sp \fBTk_UnderlineTextLayout\fR(\fIdisplay, drawable, gc, layout, x, y, underline\fR) .sp int \fBTk_PointToChar\fR(\fIlayout, x, y\fR) .sp int \fBTk_CharBbox\fR(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fR) .sp int \fBTk_DistanceToTextLayout\fR(\fIlayout, x, y\fR) .sp int \fBTk_IntersectTextLayout\fR(\fIlayout, x, y, width, height\fR) .sp \fBTk_TextLayoutToPostscript\fR(\fIinterp, layout\fR) .fi .SH ARGUMENTS .AS Tk_TextLayout "*xPtr, *yPtr" .AP Tk_Font tkfont in Font to use when constructing and displaying a text layout. The \fItkfont\fR must remain valid for the lifetime of the text layout. Must have been returned by a previous call to \fBTk_GetFont\fR. .AP "const char" *string in Potentially multi-line string whose dimensions are to be computed and stored in the text layout. The \fIstring\fR must remain valid for the lifetime of the text layout. .AP int numChars in The number of characters to consider from \fIstring\fR. If \fInumChars\fR is negative, then assumes \fIstring\fR is null terminated and uses \fBTcl_NumUtfChars\fR to determine the length of \fIstring\fR. .AP int wrapLength in Longest permissible line length, in pixels. Lines in \fIstring\fR will automatically be broken at word boundaries and wrapped when they reach this length. If \fIwrapLength\fR is too small for even a single character to fit on a line, it will be expanded to allow one character to fit on each line. If \fIwrapLength\fR is <= 0, there is no automatic wrapping; lines will get as long as they need to be and only wrap if a newline/return character is encountered. .AP Tk_Justify justify in How to justify the lines in a multi-line text layout. Possible values are \fBTK_JUSTIFY_LEFT\fR, \fBTK_JUSTIFY_CENTER\fR, or \fBTK_JUSTIFY_RIGHT\fR. If the text layout only occupies a single line, then \fIjustify\fR is irrelevant. .AP int flags in Various flag bits OR-ed together. \fBTK_IGNORE_TABS\fR means that tab characters should not be expanded to the next tab stop. \fBTK_IGNORE_NEWLINES\fR means that newline/return characters should not cause a line break. If either tabs or newlines/returns are ignored, then they will be treated as regular characters, being measured and displayed in a platform-dependent manner as described in \fBTk_MeasureChars\fR, and will not have any special behaviors. .AP int *widthPtr out If non-NULL, filled with either the width, in pixels, of the widest line in the text layout, or the width, in pixels, of the bounding box for the character specified by \fIindex\fR. .AP int *heightPtr out If non-NULL, filled with either the total height, in pixels, of all the lines in the text layout, or the height, in pixels, of the bounding box for the character specified by \fIindex\fR. .AP Tk_TextLayout layout in A token that represents the cached layout information about the single-font, multi-line, justified piece of text. This token is returned by \fBTk_ComputeTextLayout\fR. .AP Display *display in Display on which to draw. .AP Drawable drawable in Window or pixmap in which to draw. .AP GC gc in Graphics context to use for drawing text layout. The font selected in this GC must correspond to the \fItkfont\fR used when constructing the text layout. .AP int "x, y" in Point, in pixels, at which to place the upper-left hand corner of the text layout when it is being drawn, or the coordinates of a point (with respect to the upper-left hand corner of the text layout) to check against the text layout. .AP Tcl_Size firstChar in The index of the first character to draw from the given text layout. The number 0 means to draw from the beginning. .AP Tcl_Size lastChar in The index of the last character up to which to draw. The character specified by \fIlastChar\fR itself will not be drawn. A number less than 0 means to draw all characters in the text layout. .AP int underline in Index of the single character to underline in the text layout, or a negative number counting backwards from the end of the string. Any out-of-range number (e.g. INT_MIN) means no underline. .AP Tcl_Size index in The index of the character whose bounding box is desired. The bounding box is computed with respect to the upper-left hand corner of the text layout. .AP int "*xPtr, *yPtr" out Filled with the upper-left hand corner, in pixels, of the bounding box for the character specified by \fIindex\fR. Either or both \fIxPtr\fR and \fIyPtr\fR may be NULL, in which case the corresponding value is not calculated. .AP int "width, height" in Specifies the width and height, in pixels, of the rectangular area to compare for intersection against the text layout. .AP Tcl_Interp *interp out Postscript code that will print the text layout is appended to the result of interpreter \fIinterp\fR. .BE .SH DESCRIPTION .PP These routines are for measuring and displaying single-font, multi-line, justified text. To measure and display simple single-font, single-line strings, refer to the documentation for \fBTk_MeasureChars\fR. There is no programming interface in the core of Tk that supports multi-font, multi-line text; support for that behavior must be built on top of simpler layers. Note that unlike the lower level text display routines, the functions described here all operate on character-oriented lengths and indices rather than byte-oriented values. See the description of \fBTcl_UtfAtIndex\fR for more details on converting between character and byte offsets. .PP The routines described here are built on top of the programming interface described in the \fBTk_MeasureChars\fR documentation. Tab characters and newline/return characters may be treated specially by these procedures, but all other characters are passed through to the lower level. .PP \fBTk_ComputeTextLayout\fR computes the layout information needed to display a single-font, multi-line, justified \fIstring\fR of text and returns a Tk_TextLayout token that holds this information. This token is used in subsequent calls to procedures such as \fBTk_DrawTextLayout\fR, \fBTk_DistanceToTextLayout\fR, and \fBTk_FreeTextLayout\fR. The \fIstring\fR and \fItkfont\fR used when computing the layout must remain valid for the lifetime of this token. .PP \fBTk_FreeTextLayout\fR is called to release the storage associated with \fIlayout\fR when it is no longer needed. A \fIlayout\fR should not be used in any other text layout procedures once it has been released. .PP \fBTk_DrawTextLayout\fR uses the information in \fIlayout\fR to display a single-font, multi-line, justified string of text at the specified location. .PP \fBTk_UnderlineTextLayout\fR uses the information in \fIlayout\fR to display an underline below an individual character. This procedure does not draw the text, just the underline. To produce natively underlined text, an underlined font should be constructed and used. All characters, including tabs, newline/return characters, and spaces at the ends of lines, can be underlined using this method. However, the underline will never be drawn outside of the computed width of \fIlayout\fR; the underline will stop at the edge for any character that would extend partially outside of \fIlayout\fR, and the underline will not be visible at all for any character that would be located completely outside of the layout. .PP \fBTk_PointToChar\fR uses the information in \fIlayout\fR to determine the character closest to the given point. The point is specified with respect to the upper-left hand corner of the \fIlayout\fR, which is considered to be located at (0, 0). Any point whose \fIy\fR-value is less that 0 will be considered closest to the first character in the text layout; any point whose \fIy\fR-value is greater than the height of the text layout will be considered closest to the last character in the text layout. Any point whose \fIx\fR-value is negative will be considered closest to the first character on that line; any point whose \fIx\fR-value is greater than the width of the text layout will be considered closest to the last character on that line. The return value is the index of the character that was closest to the point, or one more than the index of any character (to indicate that the point was after the end of the string and that the corresponding caret would be at the end of the string). Given a \fIlayout\fR with no characters, the value 0 will always be returned, referring to a hypothetical zero-width placeholder character. .PP \fBTk_CharBbox\fR uses the information in \fIlayout\fR to return the bounding box for the character specified by \fIindex\fR. The width of the bounding box is the advance width of the character, and does not include any left or right bearing. Any character that extends partially outside of \fIlayout\fR is considered to be truncated at the edge. Any character that would be located completely outside of \fIlayout\fR is considered to be zero-width and pegged against the edge. The height of the bounding box is the line height for this font, extending from the top of the ascent to the bottom of the descent; information about the actual height of individual letters is not available. For measurement purposes, a \fIlayout\fR that contains no characters is considered to contain a single zero-width placeholder character at index 0. If \fIindex\fR was not a valid character index, the return value is 0 and \fI*xPtr\fR, \fI*yPtr\fR, \fI*widthPtr\fR, and \fI*heightPtr\fR are unmodified. Otherwise, if \fIindex\fR did specify a valid, the return value is non-zero, and \fI*xPtr\fR, \fI*yPtr\fR, \fI*widthPtr\fR, and \fI*heightPtr\fR are filled with the bounding box information for the character. If any of \fIxPtr\fR, \fIyPtr\fR, \fIwidthPtr\fR, or \fIheightPtr\fR are NULL, the corresponding value is not calculated or stored. .PP \fBTk_DistanceToTextLayout\fR computes the shortest distance in pixels from the given point (\fIx, y\fR) to the characters in \fIlayout\fR. Newline/return characters and non-displaying space characters that occur at the end of individual lines in the text layout are ignored for hit detection purposes, but tab characters are not. The return value is 0 if the point actually hits the \fIlayout\fR. If the point did not hit the \fIlayout\fR then the return value is the distance in pixels from the point to the \fIlayout\fR. .PP \fBTk_IntersectTextLayout\fR determines whether a \fIlayout\fR lies entirely inside, entirely outside, or overlaps a given rectangle. Newline/return characters and non-displaying space characters that occur at the end of individual lines in the \fIlayout\fR are ignored for intersection calculations. The return value is \-1 if the \fIlayout\fR is entirely outside of the rectangle, 0 if it overlaps, and 1 if it is entirely inside of the rectangle. .PP \fBTk_TextLayoutToPostscript\fR outputs code consisting of a Postscript array of strings that represent the individual lines in \fIlayout\fR. It is the responsibility of the caller to take the Postscript array of strings and add some Postscript function operate on the array to render each of the lines. The code that represents the Postscript array of strings is appended to interpreter \fIinterp\fR's result. .SH "DISPLAY MODEL" .PP When measuring a text layout, space characters that occur at the end of a line are ignored. The space characters still exist and the insertion point can be positioned amongst them, but their additional width is ignored when justifying lines or returning the total width of a text layout. All end-of-line space characters are considered to be attached to the right edge of the line; this behavior is logical for left-justified text and reasonable for center-justified text, but not very useful when editing right-justified text. Spaces are considered variable width characters; the first space that extends past the edge of the text layout is clipped to the edge, and any subsequent spaces on the line are considered zero width and pegged against the edge. Space characters that occur in the middle of a line of text are not suppressed and occupy their normal space width. .PP Tab characters are not ignored for measurement calculations. If wrapping is turned on and there are enough tabs on a line, the next tab will wrap to the beginning of the next line. There are some possible strange interactions between tabs and justification; tab positions are calculated and the line length computed in a left-justified world, and then the whole resulting line is shifted so it is centered or right-justified, causing the tab columns not to align any more. .PP When wrapping is turned on, lines may wrap at word breaks (space or tab characters) or newline/returns. A dash or hyphen character in the middle of a word is not considered a word break. \fBTk_ComputeTextLayout\fR always attempts to place at least one word on each line. If it cannot because the \fIwrapLength\fR is too small, the word will be broken and as much as fits placed on the line and the rest on subsequent line(s). If \fIwrapLength\fR is so small that not even one character can fit on a given line, the \fIwrapLength\fR is ignored for that line and one character will be placed on the line anyhow. When wrapping is turned off, only newline/return characters may cause a line break. .PP When a text layout has been created using an underlined \fItkfont\fR, then any space characters that occur at the end of individual lines, newlines/returns, and tabs will not be displayed underlined when \fBTk_DrawTextLayout\fR is called, because those characters are never actually drawn \- they are merely placeholders maintained in the \fIlayout\fR. .SH KEYWORDS font tk9.0.3/doc/tk.n0000644001000000100000000001524615105057705016421 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk \- Manipulate Tk internal state .SH SYNOPSIS \fBtk\fI option \fR?\fIarg ...\fR? .BE .SH DESCRIPTION .PP The \fBtk\fR command provides access to miscellaneous elements of Tk's internal state. Most of the information manipulated by this command pertains to the application as a whole, or to a screen or display, rather than to a particular window. The command can take any of a number of different forms depending on the \fIoption\fR argument. The legal forms are: .\" METHOD: appname .TP \fBtk appname \fR?\fInewName\fR? . If \fInewName\fR is not specified, this command returns the name of the application (the name that may be used in \fBsend\fR commands to communicate with the application). If \fInewName\fR is specified, then the name of the application is changed to \fInewName\fR. If the given name is already in use, then a suffix of the form .QW "\fB #2\fR" or .QW "\fB #3\fR" is appended in order to make the name unique. The command's result is the name actually chosen. \fInewName\fR should not start with a capital letter. This will interfere with option processing, since names starting with capitals are assumed to be classes; as a result, Tk may not be able to find some options for the application. If sends have been disabled by deleting the \fBsend\fR command, this command will reenable them and recreate the \fBsend\fR command. .\" METHOD: busy .TP \fBtk busy \fIsubcommand\fR ... . This command controls the marking of window hierarchies as .QW busy , rendering them non-interactive while some other operation is proceeding. For more details see the \fBbusy\fR manual page. .\" METHOD: caret .TP \fBtk caret \fIwindow \fR?\fB\-x \fIx\fR? ?\fB\-y \fIy\fR? ?\fB\-height \fIheight\fR? . Sets and queries the caret location for the display of the specified Tk window \fIwindow\fR. The caret is the per-display cursor location used for indicating global focus (e.g. to comply with Microsoft Accessibility guidelines), as well as for location of the over-the-spot XIM (X Input Methods) or Windows IME windows. If no options are specified, the last values used for setting the caret are return in option-value pair format. \fB\-x\fR and \fB\-y\fR represent window-relative coordinates, and \fB\-height\fR is the height of the current cursor location, or the height of the specified \fIwindow\fR if none is given. .\" METHOD: inactive .TP \fBtk inactive \fR?\fB\-displayof \fIwindow\fR? ?\fBreset\fR? . Returns a positive integer, the number of milliseconds since the last time the user interacted with the system. If the \fB\-displayof\fR option is given then the return value refers to the display of \fIwindow\fR; otherwise it refers to the display of the application's main window. .RS .PP \fBtk inactive\fR will return \-1, if querying the user inactive time is not supported by the system, and in safe interpreters. .PP If the literal string \fBreset\fR is given as an additional argument, the timer is reset and an empty string is returned. Resetting the inactivity time is forbidden in safe interpreters and will throw an error if tried. .RE .\" METHOD: fontchooser .TP \fBtk fontchooser \fIsubcommand\fR ... . Controls the Tk font selection dialog. For more details see the \fBfontchooser\fR manual page. .\" METHOD: print .TP \fBtk print \fIwindow\fR . The \fBtk print\fR command posts a dialog that allows users to print output from the \fBcanvas\fR and \fBtext\fR widgets. The printing will be done using platform-native APIs and dialogs where available. For more details see the \fBprint\fR manual page. .\" METHOD: scaling .TP \fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? . Sets and queries the current scaling factor used by Tk to convert between physical units (for example, points, inches, or millimeters) and pixels. The \fInumber\fR argument is a floating point number that specifies the number of pixels per point on \fIwindow\fR's display. If the \fIwindow\fR argument is omitted, it defaults to the main window. If the \fInumber\fR argument is omitted, the current value of the scaling factor is returned. .RS .PP A .QW point is a unit of measurement equal to 1/72 inch. A scaling factor of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard 72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point, which is the setting for a 90 dpi monitor; setting the scaling factor to 1.25 on a 72 dpi monitor would cause everything in the application to be displayed 1.25 times as large as normal. The initial value for the scaling factor is set when the application starts, based on properties of the installed monitor, but it can be changed at any time. Measurements made after the scaling factor is changed will use the new scaling factor, but it is undefined whether existing widgets will resize themselves dynamically to accommodate the new scaling factor. .RE .\" METHOD: sysnotify .TP \fBtk sysnotify \fP \fItitle\fP? \fImessage\fP? . The \fBtk sysnotify\fP command creates a platform-specific system notification alert. Its intent is to provide a brief, unobtrusive notification to the user by popping up a window that briefly appears in a corner of the screen. For more details see the \fBsysnotify\fR manual page. .\" METHOD: systray .TP \fBtk systray create\fP \fIsubcommand...\fP . The \fBtk systray\fP command creates an icon in the platform-specific tray. For more details see the \fBsystray\fR manual page. .\" METHOD: useinputmethods .TP \fBtk useinputmethods \fR?\fB\-displayof \fIwindow\fR? ?\fIboolean\fR? . Sets and queries the state of whether Tk should use XIM (X Input Methods) for filtering events. The resulting state is returned. XIM is used in some locales (i.e., Japanese, Korean), to handle special input devices. This feature is only significant on X. If XIM support is not available, this will always return 0. If the \fIwindow\fR argument is omitted, it defaults to the main window. If the \fIboolean\fR argument is omitted, the current state is returned. This is turned on by default for the main display. .\" METHOD: windowingsystem .TP \fBtk windowingsystem\fR . Returns the current Tk windowing system, one of \fBx11\fR (X11-based), \fBwin32\fR (MS Windows), or \fBaqua\fR (macOS Aqua). .SH "SEE ALSO" busy(n), fontchooser(n), print(n), send(n), sysnotify(n), systray(n), winfo(n) .SH KEYWORDS application name, print, send, sysnotify, systray '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/tkerror.n0000644001000000100000000000272015105057705017464 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tkerror n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tkerror \- Command invoked to process background errors .SH SYNOPSIS \fBtkerror \fImessage\fR .BE .SH DESCRIPTION .PP Note: as of Tk 4.1 the \fBtkerror\fR command has been renamed to \fBbgerror\fR because the event loop (which is what usually invokes it) is now part of Tcl. Using the \fBtkerror\fR name is deprecated. .PP For backward compatibility the \fBbgerror\fR provided by the current Tk version still tries to call \fBtkerror\fR if there is one (or an auto loadable one), so old script defining that error handler should still work, but you should anyhow modify your scripts to use \fBbgerror\fR instead of \fBtkerror\fR because that support for the old name might vanish in the future. If that call fails, \fBbgerror\fR posts a dialog showing the error and offering to see the stack trace to the user. If you want your own error management you should directly override \fBbgerror\fR instead of \fBtkerror\fR. Documentation for \fBbgerror\fR is available as part of Tcl's documentation. .SH KEYWORDS background error, reporting '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/TkInitStubs.30000644001000000100000000000570715105057705020134 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1999 Scriptics Corporation '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_InitStubs 3 8.4 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_InitStubs \- initialize the Tk stubs mechanism .SH SYNOPSIS .nf \fB#include \fR .sp const char * \fBTk_InitStubs\fR(\fIinterp, version, exact\fR) .fi .SH ARGUMENTS .AS Tcl_Interp *interp in .AP Tcl_Interp *interp in Tcl interpreter handle. .AP char *version in A version string consisting of one or more decimal numbers separated by dots. .AP int exact in Non-zero means that only the particular Tk version specified by \fIversion\fR is acceptable. Zero means that versions newer than \fIversion\fR are also acceptable as long as they have the same major version number as \fIversion\fR. .BE .SH INTRODUCTION .PP The Tcl stubs mechanism defines a way to dynamically bind extensions to a particular Tcl implementation at run time. the stubs mechanism requires no changes to applications incorporating Tcl/Tk interpreters. Only developers creating C-based Tcl/Tk extensions need to take steps to use the stubs mechanism with their extensions. See the \fBTcl_InitStubs\fR page for more information. .PP Enabling the stubs mechanism for a Tcl/Tk extension requires the following steps: .IP 1) 5 Call \fBTcl_InitStubs\fR in the extension before calling any other Tcl functions. .IP 2) 5 Call \fBTk_InitStubs\fR if the extension before calling any other Tk functions. .IP 2) 5 Define the \fBUSE_TCL_STUBS\fR and the \fBUSE_TK_STUBS\fR symbols. Typically, you would include the \fB\-DUSE_TCL_STUBS\fR and the \fB\-DUSE_TK_STUBS\fR flags when compiling the extension. .IP 3) 5 Link the extension with the Tcl and Tk stubs libraries instead of the standard Tcl and Tk libraries. On Unix platforms, the library names are \fIlibtclstub8.4.a\fR and \fIlibtkstub8.4.a\fR; on Windows platforms, the library names are \fItclstub84.lib\fR and \fItkstub84.lib\fR. Adjust the library names with appropriate version number but note that the extension may only be used with versions of Tcl/Tk that have that version number or higher. .SH DESCRIPTION .PP \fBTk_InitStubs\fR attempts to initialize the Tk stub table pointers and ensure that the correct version of Tk is loaded. In addition to an interpreter handle, it accepts as arguments a version number and a Boolean flag indicating whether the extension requires an exact version match or not. If \fIexact\fR is 0, then the extension is indicating that newer versions of Tk are acceptable as long as they have the same major version number as \fIversion\fR; non-zero means that only the specified \fIversion\fR is acceptable. \fBTcl_InitStubs\fR returns a string containing the actual version of Tk satisfying the request, or NULL if the Tk version is not acceptable, does not support the stubs mechanism, or any other error condition occurred. .SH "SEE ALSO" \fBTcl_InitStubs\fR .SH KEYWORDS stubs tk9.0.3/doc/tkvars.n0000644001000000100000000001563715105057705017321 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tkvars n 4.1 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME geometry, tk_library, tk_patchLevel, tk::scalingPct, tk_strictMotif, tk::svgFmt, tk_version \- Variables used or set by Tk .BE .SH DESCRIPTION .PP The following Tcl variables are either set or used by Tk at various times in its execution: .\" VARIABLE: tk_library .TP 15 \fBtk_library\fR . This variable holds the file name for a directory containing a library of Tcl scripts related to Tk. These scripts include an initialization file that is normally processed whenever a Tk application starts up, plus other files containing procedures that implement default behaviors for widgets. .RS .PP The initial value of \fBtk_library\fR is set when Tk is added to an interpreter; this is done by searching several different directories until one is found that contains an appropriate Tk startup script. If the \fBTK_LIBRARY\fR environment variable exists, then the directory it names is checked first. If \fBTK_LIBRARY\fR is not set or does not refer to an appropriate directory, then Tk checks several other directories based on a compiled-in default location, the location of the Tcl library directory, the location of the binary containing the application, and the current working directory. .PP The variable can be modified by an application to switch to a different library. .RE .\" VARIABLE: tk_patchLevel .TP \fBtk_patchLevel\fR . Contains a dot-separated sequence of decimal integers giving the current patch level for Tk. The patch level is incremented for each new release or patch, and it uniquely identifies an official version of Tk. .RS .PP This value is normally the same as the result of .QW "\fBpackage require\fR \fBtk\fR" . .RE .\" VARIABLE: scalingPct .TP \fBtk::scalingPct\fR . Tk sets this variable at initialization time to the scaling percentage corresponding to the display's DPI scaling level. This value is at least 100 and is restricted to multiples of 25 (100, 125, 150, 175, 200, 225, ...). The sizes and various attributes of the Tk core and Ttk widgets and their components, as well as the sizes of the images used by Tk are chosen according to the scaling percentage, and this is recommended for applications and library packages, too. .RS .PP Note that any access to this variable is supposed to be strictly read-only! Note also that whenever the scaling factor used to convert between physical units and pixels is changed via \fBtk scaling\fR, the value of the variable \fBtk::scalingPct\fR is automatically updated. .PP On the windowing systems \fBwin32\fR and \fBaqua\fR the scaling percentage is computed by rounding [\fBtk scaling\fR] * 75 to the nearest multiple of 25 that is at least 100. (On \fBaqua\fR the result is always 100, and the desktop engine automatically scales everything as needed.) On \fBx11\fR, deriving the scaling percentage from [\fBtk scaling\fR] is done as fallback method only, because the implementation of display scaling is highly dependent on the desktop environment and it mostly manipulates system resources that are resident outside of Xlib, which Tk is based on. Moreover, for technical reasons, the value assigned to the variable \fBtk::scalingPct\fR can be different from the one selected in the system settings (e.g., 200 rather than 125, 150, or 175 when running GNOME on Xorg or the Cinnamon desktop). On \fBx11\fR the scaling percentage is computed mostly (but not exclusively) from the value of the X resource Xft.dpi, and, as an additional step, Tk synchronizes the scaling factor used to convert between physical units and pixels with the scaling percentage, with the aid of the \fBtk scaling\fR command. .RE .\" VARIABLE: tk_strictMotif .TP \fBtk_strictMotif\fR . This variable is set to zero by default. If an application sets it to one, then Tk attempts to adhere as closely as possible to Motif look-and-feel standards. For example, active elements such as buttons and scrollbar sliders will not change color when the pointer passes over them. Modern applications should not normally set this variable. .\" VARIABLE: svgFmt .TP \fBtk::svgFmt\fR . This variable is set at Tk initialization time to .RS .RS 4 .PP [\fBlist svg \-scale\fR [\fBexpr\fR {$\fBtk::scalingPct\fR / 100.0}]] .RE .PP Typical values are {\fBsvg \-scale\fR 1.0}, {\fBsvg \-scale\fR 1.25}, {\fBsvg \-scale\fR 2.0}, etc. It is recommended to pass the value of this variable to the commands \fBimage create photo\fR, \fIimageName\fB configure\fR, \fIimageName\fB put\fR, and \fIimageName\fB read\fR as the value of their \fB\-format\fR option when creating or manipulating SVG images, to make sure that their sizes will correspond to the display's DPI scaling level. .PP Note that any access to this variable is supposed to be strictly read-only! Note also that whenever the scaling factor used to convert between physical units and pixels is changed via \fBtk scaling\fR, the value of the variable \fBtk::svgFmt\fR is automatically updated. .RE .\" VARIABLE: tk_version .TP \fBtk_version\fR . Tk sets this variable in the interpreter for each application. The variable holds the current version number of the Tk library in the form \fImajor\fR.\fIminor\fR. \fIMajor\fR and \fIminor\fR are integers. The major version number increases in any Tk release that includes changes that are not backward compatible (i.e. whenever existing Tk applications and scripts may have to change to work with the new release). The minor version number increases with each new release of Tk, except that it resets to zero whenever the major version number changes. .SS "INTERNAL AND DEBUGGING VARIABLES" .PP These variables should not normally be set by user code. .\" VARIABLE: Priv .TP \fBtk::Priv\fR . This variable is an array containing several pieces of information that are private to Tk. The elements of \fBtk::Priv\fR are used by Tk library procedures and default bindings. They should not be accessed by any code outside Tk. .\" VARIABLE: tk_textRedraw .\" VARIABLE: tk_textRelayout .TP \fBtk_textRedraw\fR .TP \fBtk_textRelayout\fR . These variables are set by text widgets when they have debugging turned on. The values written to these variables can be used to test or debug text widget operations. These variables are mostly used by Tk's test suite. .SH "OTHER GLOBAL VARIABLES" The following variables are only guaranteed to exist in \fBwish\fR executables; the Tk library does not define them itself but many Tk environments do. .\" VARIABLE: geometry .TP \fBgeometry\fR . If set, contains the user-supplied geometry specification to use for the main Tk window. .SH "SEE ALSO" package(n), tclvars(n), wish(1) .SH KEYWORDS environment, text, variables, version '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/tkwait.n0000644001000000100000000000406015105057705017276 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1992 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tkwait n "" Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tkwait \- Wait for variable to change or window to be destroyed .SH SYNOPSIS .nf \fBtkwait variable \fIname\fR \fBtkwait visibility \fIname\fR \fBtkwait window \fIname\fR .fi .BE .SH DESCRIPTION .PP The \fBtkwait\fR command waits for one of several things to happen, then it returns without taking any other actions. The return value is always an empty string. .\" METHOD: variable If the first argument is \fBvariable\fR (or any abbreviation of it) then the second argument is the name of a global variable and the command waits for that variable to be modified. .\" METHOD: visibility If the first argument is \fBvisibility\fR (or any abbreviation of it) then the second argument is the name of a window and the \fBtkwait\fR command waits for a change in its visibility state (as indicated by the arrival of a VisibilityNotify event). This form is typically used to wait for a newly-created window to appear on the screen before taking some action. .\" METHOD: window If the first argument is \fBwindow\fR (or any abbreviation of it) then the second argument is the name of a window and the \fBtkwait\fR command waits for that window to be destroyed. This form is typically used to wait for a user to finish interacting with a dialog box before using the result of that interaction. .PP While the \fBtkwait\fR command is waiting it processes events in the normal fashion, so the application will continue to respond to user interactions. If an event handler invokes \fBtkwait\fR again, the nested call to \fBtkwait\fR must complete before the outer call can complete. .SH "SEE ALSO" bind(n), vwait(n) .SH KEYWORDS variable, visibility, wait, window '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/Tk_Init.30000644001000000100000000000502415105057705017242 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_Init 3 8.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_Init, Tk_SafeInit \- add Tk to an interpreter and make a new Tk application. .SH SYNOPSIS .nf \fB#include \fR .sp int \fBTk_Init\fR(\fIinterp\fR) .sp int \fBTk_SafeInit\fR(\fIinterp\fR) .SH ARGUMENTS .AP Tcl_Interp *interp in Interpreter in which to load Tk. Tk should not already be loaded in this interpreter. .BE .SH DESCRIPTION .PP \fBTk_Init\fR is the package initialization procedure for Tk. It is normally invoked by the \fBTcl_AppInit\fR procedure for an application or by the \fBload\fR command. \fBTk_Init\fR adds all of Tk's commands to \fIinterp\fR and creates a new Tk application, including its main window. If the initialization is successful \fBTk_Init\fR returns \fBTCL_OK\fR; if there is an error it returns \fBTCL_ERROR\fR. \fBTk_Init\fR also leaves a result or error message in interpreter \fIinterp\fR's result. .PP If there is a variable \fBargv\fR in \fIinterp\fR, \fBTk_Init\fR treats the contents of this variable as a list of options for the new Tk application. The options may have any of the forms documented for the \fBwish\fR application (in fact, \fBwish\fR uses Tk_Init to process its command-line arguments). .PP \fBTk_SafeInit\fR is identical to \fBTk_Init\fR except that it removes all Tk commands that are considered unsafe. Those commands and the reasons for their exclusion are: .TP \fBbell\fR . Continuous ringing of the bell is a nuisance. .TP \fBclipboard\fR . A malicious script could replace the contents of the clipboard with the string .QW "\fBrm \-r *\fR" and lead to surprises when the contents of the clipboard are pasted. .TP \fBgrab\fR . Grab can be used to block the user from using any other applications. .TP \fBmenu\fR . Menus can be used to cover the entire screen and to steal input from the user. .TP \fBselection\fR . See clipboard. .TP \fBsend\fR . Send can be used to cause unsafe interpreters to execute commands. .TP \fBtk\fR . The tk command recreates the send command, which is unsafe. .TP \fBtkwait\fR . Tkwait can block the containing process forever .TP \fBtoplevel\fR . Toplevels can be used to cover the entire screen and to steal input from the user. .TP \fBwm\fR . If toplevels are ever allowed, wm can be used to remove decorations, move windows around, etc. .SH KEYWORDS safe, application, initialization, load, main window tk9.0.3/doc/tk_mac.n0000644001000000100000000002430015105057444017230 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2011 Kevin Walzer. '\" Copyright (c) 2011 Donal K. Fellows. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH tk::mac n 8.6 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tk::mac \- Access Mac-Specific Functionality on macOS from Tk .SH SYNOPSIS .nf \fB::tk::mac::DoScriptFile\fR \fB::tk::mac::DoScriptText\fR \fB::tk::mac::ShowPreferences\fR \fB::tk::mac::OpenApplication\fR \fB::tk::mac::ReopenApplication\fR \fB::tk::mac::OpenDocument \fIfile...\fR \fB::tk::mac::PrintDocument \fIfile...\fR \fB::tk::mac::Quit\fR \fB::tk::mac::OnHide\fR \fB::tk::mac::OnShow\fR \fB::tk::mac::ShowHelp\fR \fB::tk::mac::PerformService\fR \fB::tk::mac::LaunchURL \fIURL...\fR \fB::tk::mac::GetAppPath\fR \fB::tk::mac::standardAboutPanel\fR \fB::tk::mac::useCompatibilityMetrics \fIboolean\fR \fB::tk::mac::CGAntialiasLimit \fIlimit\fR \fB::tk::mac::antialiasedtext \fInumber\fR \fB::tk::mac::useThemedToplevel \fIboolean\fR \fB::tk::mac::iconBitmap \fIname width height \-kind value\fR .fi .BE .SH "EVENT HANDLER CALLBACKS" .PP The Aqua/macOS application environment defines a number of additional events that applications should respond to. These events are mapped by Tk to calls to commands in the \fB::tk::mac\fR namespace; unless otherwise noted, if the command is absent, no action will be taken. .\" COMMAND: DoScriptFile .TP \fB::tk::mac::DoScriptFile\fR . The default Apple Event handler for AEDoScriptHandler. This command executes a Tcl file when an AppleScript sends a .QW "do script" command to Wish with a file path as a parameter. .\" COMMAND: DoScriptText .TP \fB::tk::mac::DoScriptText\fR . The default Apple Event handler for AEDoScriptHandler. This command executes Tcl code when an AppleScript sends a .QW "do script" command to Wish with Tcl code or a Tcl procedure as a parameter. .\" COMMAND: ShowPreferences .TP \fB::tk::mac::ShowPreferences\fR . The default Apple Event handler for kAEShowPreferences, .QW pref . The application menu .QW "Preferences" menu item is only enabled when this proc is defined. Typically this command is used to wrap a specific own preferences command, which pops up a preferences window. Something like: .RS .PP .CS proc ::tk::mac::ShowPreferences {} { setPref } .CE .RE .\" COMMAND: OpenApplication .TP \fB::tk::mac::OpenApplication\fR . If a proc of this name is defined, this proc fill fire when your application is initially opened. It is the default Apple Event handler for kAEOpenApplication, .QW oapp . .\" COMMAND: ReopenApplication .TP \fB::tk::mac::ReopenApplication\fR . If a proc of this name is defined it is the default Apple Event handler for kAEReopenApplication, .QW rapp , the Apple Event sent when your application is opened when it is already running (e.g. by clicking its icon in the Dock). Here is a sample that raises a minimized window when the Dock icon is clicked: .RS .PP .CS proc ::tk::mac::ReopenApplication {} { if {[wm state .] eq "withdrawn"} { wm state . normal } else { wm deiconify . } raise . } .CE .RE .\" COMMAND: OpenDocument .TP \fB::tk::mac::OpenDocument \fIfile...\fR . If a proc of this name is defined it is the default Apple Event handler for kAEOpenDocuments, .QW odoc , the Apple Event sent when your application is asked to open one or more documents (e.g., by drag & drop onto the app or by opening a document of a type associated to the app). The proc should take as arguments paths to the files to be opened, like so: .RS .PP .CS proc ::tk::mac::OpenDocument {args} { foreach f $args {my_open_document $f} } .CE .RE .\" COMMAND: PrintDocument .TP \fB::tk::mac::PrintDocument \fIfile...\fR . If a proc of this name is defined it is the default Apple Event handler for kAEPrintDocuments, .QW pdoc , the Apple Event sent when your application is asked to print a document. It takes a single absolute file path as an argument. .\" COMMAND: Quit .TP \fB::tk::mac::Quit\fR . If a proc of this name is defined it is the default Apple Event handler for kAEQuitApplication, .QW quit , the Apple Event sent when your application is asked to be quit, e.g. via the quit menu item in the application menu, the quit menu item in the Dock menu, or during a logout/restart/shutdown etc. If this is not defined, \fBexit\fR is called instead. .\" COMMAND: OnHide .TP \fB::tk::mac::OnHide\fR . If defined, this is called when your application receives a kEventAppHidden event, e.g. via the hide menu item in the application or Dock menus. .\" COMMAND: OnShow .TP \fB::tk::mac::OnShow\fR . If defined, this is called when your application receives a kEventAppShown event, e.g. via the show all menu item in the application menu, or by clicking the Dock icon of a hidden application. .\" COMMAND: ShowHelp .TP \fB::tk::mac::ShowHelp\fR . Customizes behavior of Apple Help menu; if this procedure is not defined, the platform-specific standard Help menu item .QW "YourApp Help" performs the default Cocoa action of showing the Help Book configured in the application's Info.plist (or displaying an alert if no Help Book is set). .\" COMMAND: PerformService .TP \fB::tk::mac::PerformService\fR . Executes a Tcl procedure called from the macOS .QW Services menu in the Application menu item. The .QW Services menu item allows for inter-application communication; data from one application, such as selected text, can be sent to another application for processing, for example to Safari as a search item for Google, or to TextEdit to be appended to a file. An example of the proc is below, and should be rewritten in an application script for customization: .RS .PP .CS proc ::tk::mac::PerformService {} { set data [clipboard get] $w insert end $data } .CE .RE Note that the mechanism for retrieving the data is from the clipboard; there is no other supported way to obtain the data. If the Services process is not desired, the NSServices keys can be deleted from the application's Info.plist file. The underlying code supporting this command also allows the text, entry and ttk::entry widgets to access services from other applications via the Services menu. The NSPortName key in Wish's Info.plist file is currently set as .QW "Wish" ; if a developer changes the name of the Wish executable to something else, this key should be modified with the same name. .\" COMMAND: LaunchURL .TP \fB::tk::mac::LaunchURL \fIURL...\fR . If defined, launches a URL within Tk. This would be used if a Tk application wants to handle a URL itself, such as displaying data from an RSS feed, rather than launching a default application to handle the URL, although it can defined as such. Wish includes a stub URL scheme of .QW foo:// in the CFBundleURLSchemes key of its Info.plist file; this should be customized for the specific URL scheme the developer wants to support. .TP \fB::tk::mac::GetAppPath\fR . Returns the current applications's file path. .PP .SH "ADDITIONAL DIALOGS" .PP Aqua/macOS defines additional dialogs that applications should support. .\" COMMAND: standardAboutPanel .TP \fB::tk::mac::standardAboutPanel\fR . Brings the standard Cocoa about panel to the front with information filled in from the application bundle files. The panel displays the application icon and the values associated to the info.plist keys named CFBundleName, CFBundleShortVersionString, NSAboutPanelOptionVersion and NSHumanReadableCopyright. If a file named \fICredits.html\fR or \fICredits.rtf\fR exists in the bundle's Resources directory then its contents will be displayed in a scrolling text box at the bottom of the dialog. See the documentation for -[NSApplication orderFrontStandardAboutPanelWithOptions:] for more details. A hook is also provided for a custom About dialog. If a Tcl proc named tkAboutDialog is defined in the main interpreter then that procedure will be called instead of opening the standardAboutPanel. .SH "SYSTEM CONFIGURATION" .PP There are a number of additional global configuration options that control the details of how Tk renders by default. .\" COMMAND: useCompatibilityMetrics .TP \fB::tk::mac::useCompatibilityMetrics \fIboolean\fR . Preserves compatibility with older Tk/Aqua metrics; set to \fBfalse\fR for more native spacing. .\" COMMAND: CGAntialiasLimit .TP \fB::tk::mac::CGAntialiasLimit \fIlimit\fR . Sets the antialiasing limit; lines thinner that \fIlimit\fR pixels will not be antialiased. Integer, set to 0 by default, making all lines be antialiased. .\" COMMAND: antialiasedtext .TP \fB::tk::mac::antialiasedtext \fInumber\fR . Sets anti-aliased text. Controls text antialiasing, possible values for \fInumber\fR are -1 (default, use system default for text AA), 0 (no text AA), 1 (use text AA). .\" COMMAND: useThemedToplevel .TP \fB::tk::mac::useThemedToplevel \fIboolean\fR . Sets toplevel windows to draw with the modern grayish/ pinstripe Mac background. Equivalent to configuring the toplevel with .QW "\fB\-background systemWindowHeaderBackground\fR" , or to using a \fBttk::frame\fR. .SH "SUPPORT COMMANDS" .\" COMMAND: iconBitmap .TP \fB::tk::mac::iconBitmap \fIname width height \-kind value\fR . Renders native icons and bitmaps in Tk applications (including any image file readable by NSImage). A native bitmap name is interpreted as follows (in order): .RS .IP \(bu 3 predefined builtin 32x32 icon name (\fBstop\fR, \fBcaution\fR, \fBdocument\fR, etc.) .IP \(bu 3 \fIname\fR, as defined by \fBtk::mac::iconBitmap\fR .IP \(bu 3 NSImage named image name .IP \(bu 3 NSImage url string .IP \(bu 3 4-char OSType of IconServices icon .PP The \fIwidth\fR and \fIheight\fR arguments to \fBtk::mac::iconBitmap\fR define the dimensions of the image to create, and \fI\-kind\fR must be one of: .\" OPTION: -file .TP \fB\-file\fR . icon of file at given path .\" OPTION: -fileType .TP \fB\-fileType\fR . icon of given file type .\" OPTION: -osType .TP \fB\-osType\fR . icon of given 4-char OSType file type .\" OPTION: -systemType .TP \fB\-systemType\fR . icon for given IconServices 4-char OSType .\" OPTION: -namedImage .TP \fB\-namedImage\fR . named NSImage for given name .\" OPTION: -imageFile .TP \fB\-imageFile\fR . image at given path .RE .SH "SEE ALSO" bind(n), wm(n) .SH KEYWORDS about dialog, antialiasing, Apple event, icon, NSImage '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/Tk_Main.30000644001000000100000000000525315105057705017227 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Tk_Main 3 4.0 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME Tk_Main \- main program for Tk-based applications .SH SYNOPSIS .nf \fB#include \fR .sp \fBTk_Main\fR(\fIargc, argv, appInitProc\fR) .SH ARGUMENTS .AS Tcl_AppInitProc *appInitProc .AP Tcl_Size argc in Number of elements in \fIargv\fR. .AP char *argv[] in Array of strings containing command-line arguments. On Windows, when using -DUNICODE, the parameter type changes to wchar_t *. .AP Tcl_AppInitProc *appInitProc in Address of an application-specific initialization procedure. The value for this argument is usually \fBTcl_AppInit\fR. .BE .SH DESCRIPTION .PP \fBTk_Main\fR acts as the main program for most Tk-based applications. Starting with Tk 4.0 it is not called \fBmain\fR anymore because it is part of the Tk library and having a function \fBmain\fR in a library (particularly a shared library) causes problems on many systems. Having \fBmain\fR in the Tk library would also make it hard to use Tk in C++ programs, since C++ programs must have special C++ \fBmain\fR functions. .PP Normally each application contains a small \fBmain\fR function that does nothing but invoke \fBTk_Main\fR. \fBTk_Main\fR then does all the work of creating and running a \fBwish\fR-like application. .PP When it is has finished its own initialization, but before it processes commands, \fBTk_Main\fR calls the procedure given by the \fIappInitProc\fR argument. This procedure provides a .QW hook for the application to perform its own initialization, such as defining application-specific commands. The procedure must have an interface that matches the type \fBTcl_AppInitProc\fR: .CS typedef int \fBTcl_AppInitProc\fR( Tcl_Interp *\fIinterp\fR); .CE \fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; for more details on this procedure, see the documentation for \fBTcl_AppInit\fR. .PP \fBTk_Main\fR functions much the same as \fBTcl_Main\fR. In particular, \fBTk_Main\fR supports both an interactive mode and a startup script mode, with the file name and encoding of a startup script under the control of the \fBTcl_SetStartupScript\fR and \fBTcl_GetStartupScript\fR routines. However it calls \fBTk_MainLoop\fR after processing any supplied script, and in interactive uses events registered with \fBTcl_CreateFileHandler\fR to process user input. .SH "SEE ALSO" Tcl_DoOneEvent(3) .SH KEYWORDS application-specific initialization, command-line arguments, main program tk9.0.3/doc/toplevel.n0000644001000000100000000001766215105057705017641 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1990-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH toplevel n 8.4 Tk "Tk Built-In Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME toplevel \- Create and manipulate 'toplevel' main and popup window widgets .SH SYNOPSIS \fBtoplevel\fI pathName \fR?\fIoptions\fR? .SO \-borderwidth \-highlightcolor \-pady \-cursor \-highlightthickness \-relief \-highlightbackground \-padx \-takefocus .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-background background Background This option is the same as the standard \fB\-background\fR option except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border. .VS "9.0, TIP262" An empty background will disable drawing the background image. .OP \-backgroundimage backgroundImage BackgroundImage This specifies an image to display on the toplevel's background within the border of the toplevel (i.e., the image will be clipped by the toplevel's highlight ring and border, if either are present) on top of the background; subwidgets of the toplevel will be drawn on top. The image must have been created with the \fBimage create\fR command. If specified as the empty string, no image will be displayed. .VE "9.0, TIP262" .OP \-class class Class Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. Some window managers display the class name for windows in their dock while some others display the window title. The \fB\-class\fR option may not be changed with the \fBconfigure\fR widget command. .OP \-colormap colormap Colormap Specifies a colormap to use for the window. The value may be either \fBnew\fR, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as \fIpathName\fR), in which case the new window will use the colormap from the specified window. If the \fB\-colormap\fR option is not specified, the new window uses the default colormap of its screen. This option may not be changed with the \fBconfigure\fR widget command. .OP \-container container Container The value must be a boolean. If true, it means that this window will be used as a container in which some other application will be embedded (for example, a Tk toplevel can be embedded using the \fB\-use\fR option). The window will support the appropriate window manager protocols for things like geometry requests. The window should not have any children of its own in this application. This option may not be changed with the \fBconfigure\fR widget command. .OP \-height height Height Specifies the desired height for the window in any of the forms acceptable to \fBTk_GetPixels\fR. If this option is negative or zero then the window will not request any size at all. .OP \-menu menu Menu Specifies a menu widget to be used as a menubar. On the Macintosh, the menubar will be displayed across the top of the main monitor. On Microsoft Windows and all UNIX platforms, the menu will appear across the toplevel window as part of the window dressing maintained by the window manager. .OP \-screen "" "" Specifies the screen on which to place the new window. Any valid screen name may be used, even one associated with a different display. Defaults to the same screen as its parent. This option is special in that it may not be specified via the option database, and it may not be modified with the \fBconfigure\fR widget command. .OP \-tile tile Tile .VS "9.0, TIP262" This specifies how to draw the background image (see \fB\-backgroundimage\fR) on the toplevel. If true (according to \fBTcl_GetBoolean\fR), the image will be tiled to fill the whole toplevel, with the origin of the first copy of the image being the top left of the interior of the toplevel. If false (the default), the image will be centered within the toplevel. .VE "9.0, TIP262" .OP \-use use Use This option is used for embedding. If the value is not an empty string, it must be the window identifier of a container window, specified as a hexadecimal string like the ones returned by the \fBwinfo id\fR command. The toplevel widget will be created as a child of the given container instead of the root window for the screen. If the container window is in a Tk application, it must be a frame or toplevel widget for which the \fB\-container\fR option was specified. This option may not be changed with the \fBconfigure\fR widget command. .OP \-visual visual Visual Specifies visual information for the new window in any of the forms accepted by \fBTk_GetVisual\fR. If this option is not specified, the new window will use the default visual for its screen. The \fB\-visual\fR option may not be modified with the \fBconfigure\fR widget command. .OP \-width width Width Specifies the desired width for the window in any of the forms acceptable to \fBTk_GetPixels\fR. If this option is negative or zero then the window will not request any size at all. .BE .SH DESCRIPTION .PP The \fBtoplevel\fR command creates a new toplevel widget (given by the \fIpathName\fR argument). Additional options, described above, may be specified on the command line or in the option database to configure aspects of the toplevel such as its background color and relief. The \fBtoplevel\fR command returns the path name of the new window. .PP A toplevel is similar to a \fBframe\fR except that it is created as a top-level window: its X parent is the root window of a screen rather than the logical parent from its Tk path name. The primary purpose of a toplevel is to serve as a container for dialog boxes and other collections of widgets. The only visible features of a toplevel are its background and an optional 3-D border to make the toplevel appear raised or sunken. .SH "WIDGET COMMAND" .PP The \fBtoplevel\fR command creates a new Tcl command whose name is the same as the path name of the toplevel's window. This command may be used to invoke various operations on the widget. It has the following general form: .PP .CS \fIpathName option \fR?\fIarg ...\fR? .CE .PP \fIPathName\fR is the name of the command, which is the same as the toplevel widget's path name. \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. The following commands are possible for toplevel widgets: .\" METHOD: cget .TP \fIpathName \fBcget \fIoption\fR . Returns the current value of the configuration option given by \fIoption\fR. \fIOption\fR may have any of the values accepted by the \fBtoplevel\fR command. .\" METHOD: configure .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? . Query or modify the configuration options of the widget. If no \fIoption\fR is specified, returns a list describing all of the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the format of this list). If \fIoption\fR is specified with no \fIvalue\fR, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no \fIoption\fR is specified). If one or more \fIoption\-value\fR pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. \fIOption\fR may have any of the values accepted by the \fBtoplevel\fR command. .SH BINDINGS .PP When a new toplevel is created, it has no default event bindings: toplevels are not intended to be interactive. .PP Be aware that bindings on toplevels may receive events from subwidgets. .SH "SEE ALSO" bind(n), bindtags(n), frame(n), wm(n) .SH KEYWORDS toplevel, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_button.n0000644001000000100000000000701015105057705020166 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::button n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::button \- Widget that issues a command when pressed .SH SYNOPSIS \fBttk::button\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION A \fBttk::button\fR widget displays a textual label and/or image, and evaluates a command when pressed. .SO ttk_widget \-class \-compound \-cursor \-image \-justify \-state \-style \-takefocus \-text \-textvariable \-underline \-width .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command A script to evaluate when the widget is invoked. .OP \-default default Default May be set to one of \fBnormal\fR, \fBactive\fR, or \fBdisabled\fR. In a dialog box, one button may be designated the .QW default button (meaning, roughly, .QW "the one that gets invoked when the user presses " ). \fBactive\fR indicates that this is currently the default button; \fBnormal\fR means that it may become the default button, and \fBdisabled\fR means that it is not defaultable. The default is \fBnormal\fR. .RS .PP Depending on the theme, the default button may be displayed with an extra highlight ring, or with a different border color. .RE .\" Not documented -- may go away .\" .OP \-padding padding Padding .\" .OP \-foreground foreground Foreground .\" .OP \-font font Font .\" .OP \-anchor anchor Anchor .\" .OP \-relief relief Relief .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR commands (see \fBttk::widget\fR), button widgets support the following additional commands: .\" METHOD: invoke .TP \fIpathName \fBinvoke\fR . Invokes the command associated with the button. .SH "STANDARD STYLES" .PP \fBTtk::button\fR widgets support the \fBToolbutton\fR style in all standard themes, which is useful for creating widgets for toolbars. .PP In the Aqua theme there are several other styles which can be used to produce replicas of many of the different button types that are discussed in Apple's Human Interface Guidelines. These include \fBDisclosureButton\fR, \fBDisclosureTriangle\fR, \fBHelpButton\fR, \fBImageButton\fR, \fBInlineButton\fR, \fBGradientButton\fR, \fBRoundedRectButton\fR, and \fBRecessedButton\fR. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::button\fP is \fBTButton\fP. .PP Dynamic states: \fBactive\fP, \fBdisabled\fP, \fBpressed\fP, \fBreadonly\fP. .PP \fBTButton\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-anchor\fP \fIanchor\fP .br \fB\-background\fP \fIcolor\fP .br \fB\-bordercolor\fP \fIcolor\fP .br \fB\-compound\fP \fIcompound\fP .br \fB\-darkcolor\fP \fIcolor\fP .br \fB\-foreground\fP \fIcolor\fP .br \fB\-font\fP \fIfont\fP .br \fB\-highlightcolor\fP \fIcolor\fP .br \fB\-highlightthickness\fP \fIamount\fP .br \fB\-lightcolor\fP \fIcolor\fP .br \fB\-padding\fP \fIpadding\fP .br \fB\-relief\fP \fIrelief\fP .br \fB\-shiftrelief\fP \fIamount\fP .RS \fB\-shiftrelief\fP specifies how far the button contents are shifted down and right in the \fIpressed\fP state. This action provides additional skeuomorphic feedback. .RE \fB\-width\fP \fIamount\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), button(n) .SH "KEYWORDS" widget, button, default, command '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_checkbutton.n0000644001000000100000000000662415105057705021176 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::checkbutton n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::checkbutton \- On/off widget .SH SYNOPSIS \fBttk::checkbutton\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION A \fBttk::checkbutton\fR widget is used to show or change a setting. It has two states, selected and deselected. The state of the checkbutton may be linked to a Tcl variable. .SO ttk_widget \-class \-compound \-cursor \-image \-state \-style \-takefocus \-text \-textvariable \-underline \-width .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command A Tcl script to execute whenever the widget is invoked. .OP \-offvalue offValue OffValue The value to store in the associated \fB\-variable\fR when the widget is deselected. Defaults to \fB0\fR. .OP \-onvalue onValue OnValue The value to store in the associated \fB\-variable\fR when the widget is selected. Defaults to \fB1\fR. .OP \-variable variable Variable The name of a global variable whose value is linked to the widget. Defaults to the widget pathname if not specified. .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR commands (see \fBttk::widget\fR), checkbutton widgets support the following additional commands: .\" METHOD: invoke .TP \fIpathname\fB invoke\fR . Toggles between the selected and deselected states and evaluates the associated \fB\-command\fR. If the widget is currently selected, sets the \fB\-variable\fR to the \fB\-offvalue\fR and deselects the widget; otherwise, sets the \fB\-variable\fR to the \fB\-onvalue\fR Returns the result of the \fB\-command\fR. .\" Missing: select, deselect, toggle .\" Are these useful? They don't invoke the -command .\" Missing: flash. This is definitely not useful. .SH "WIDGET STATES" .PP The widget does not respond to user input if the \fBdisabled\fR state is set. The widget sets the \fBselected\fR state whenever the linked \fB\-variable\fR is set to the widget's \fB\-onvalue\fR, and clears it otherwise. The widget sets the \fBalternate\fR state whenever the linked \fB\-variable\fR is unset. (The \fBalternate\fR state may be used to indicate a .QW tri-state or .QW indeterminate selection.) .SH "STANDARD STYLES" .PP \fBTtk::checkbutton\fR widgets support the \fBToolbutton\fR style in all standard themes, which is useful for creating widgets for toolbars. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::checkbutton\fP is \fBTCheckbutton\fP. .PP Dynamic states: \fBactive\fP, \fBalternate\fP, \fBdisabled\fP, \fBpressed\fP, \fBselected\fP, \fBreadonly\fP. .PP \fBTCheckbutton\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-compound\fP \fIcompound\fP .br \fB\-foreground\fP \fIcolor\fP .br \fB\-indicatorbackground\fP \fIcolor\fP .br \fB\-indicatorcolor\fP \fIcolor\fP .br \fB\-indicatormargin\fP \fIpadding\fP .br \fB\-indicatorrelief\fP \fIrelief\fP .br \fB\-padding\fP \fIpadding\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), ttk::radiobutton(n), checkbutton(n) .SH "KEYWORDS" widget, button, toggle, check, option '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_combobox.n0000644001000000100000000001320415105057705020465 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::combobox n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::combobox \- text field with popdown selection list .SH SYNOPSIS \fBttk::combobox\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP A \fBttk::combobox\fR combines a text field with a pop-down list of values; the user may select the value of the text field from among the values in the list. .SO ttk_widget \-class \-cursor \-takefocus \-style \-placeholder \-placeholderforeground .SE .\" ALSO: Other entry widget options .SH "WIDGET-SPECIFIC OPTIONS" .OP \-exportselection exportSelection ExportSelection Boolean value. If set, the widget selection is linked to the X selection. .OP \-justify justify Justify Specifies how the text is aligned within the widget. Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. .OP \-height height Height Specifies the height of the pop-down listbox, in rows. .OP \-postcommand postCommand PostCommand A Tcl script to evaluate immediately before displaying the listbox. The \fB\-postcommand\fR script may specify the \fB\-values\fR to display. .OP \-state state State One of \fBnormal\fR, \fBreadonly\fR, or \fBdisabled\fR. In the \fBreadonly\fR state, the value may not be edited directly, and the user can only select one of the \fB\-values\fR from the dropdown list. In the \fBnormal\fR state, the text field is directly editable. In the \fBdisabled\fR state, no interaction is possible. .OP \-textvariable textVariable TextVariable Specifies the name of a global variable whose value is linked to the widget value. Whenever the variable changes value the widget value is updated, and vice versa. .OP \-values values Values Specifies the list of values to display in the drop-down listbox. .OP \-width width Width Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR commands (see \fBttk::widget\fR), combobox widgets support the following additional commands: .\" METHOD: current .TP \fIpathName \fBcurrent\fR ?\fInewIndex\fR? . If \fInewIndex\fR is supplied, sets the combobox value to the element at position \fInewIndex\fR in the list of \fB\-values\fR (in addition to integers, the \fBend\fR index is supported and indicates the last element of the list, moreover the same simple interpretation as for the command \fBstring index\fR is supported, with simple integer index arithmetic and indexing relative to \fBend\fR). Otherwise, returns the index of the current value in the list of \fB\-values\fR or \fB{}\fR if the current value does not appear in the list. .\" METHOD: get .TP \fIpathName \fBget\fR . Returns the current value of the combobox. .\" METHOD: set .TP \fIpathName \fBset\fI value\fR . Sets the value of the combobox to \fIvalue\fR. .PP The combobox widget also supports the following \fBttk::entry\fR widget commands: .DS .ta 5.5c 11c \fBbbox\fR \fBdelete\fR \fBicursor\fR \fBindex\fR \fBinsert\fR \fBselection\fR \fBxview\fR .DE .SH "VIRTUAL EVENTS" .PP The combobox widget generates a \fB<>\fR virtual event when the user selects an element from the list of values. If the selection action unposts the listbox, this event is delivered after the listbox is unposted. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::combobox\fP is \fBTCombobox\fP. The \fBttk::combobox\fP uses the \fBentry\fP and \fBlistbox\fP widgets internally. The listbox frame has a class name of \fBComboboxPopdownFrame\fP. .PP Dynamic states: \fBdisabled\fP, \fBfocus\fP, \fBpressed\fP, \fBreadonly\fP. .PP \fBTCombobox\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-arrowcolor\fP \fIcolor\fP .br \fB\-arrowsize\fP \fIamount\fP .br \fB\-background\fP \fIcolor\fP .br \fB\-bordercolor\fP \fIcolor\fP .br \fB\-darkcolor\fP \fIcolor\fP .br \fB\-focusfill\fP \fIcolor\fP .br \fB\-foreground\fP \fIcolor\fP .br \fB\-fieldbackground\fP \fIcolor\fP .RS Can only be changed when using non-native and non-graphical themes. .RE \fB\-insertcolor\fP \fIcolor\fP .br \fB\-insertwidth\fP \fIamount\fP .br \fB\-lightcolor\fP \fIcolor\fP .br \fB\-padding\fP \fIpadding\fP .br \fB\-placeholderforeground\fP \fIcolor\fP .br \fB\-postoffset\fP \fIpadding\fP .br \fB\-selectbackground\fP \fIcolor\fP .RS Text entry select background. .RE \fB\-selectforeground\fP \fIcolor\fP .RS Text entry select foreground. .RE .PP The \fBttk::combobox\fP popdown listbox cannot be configured using \fBttk::style\fP nor via the widget \fBconfigure\fP command. The listbox can be configured using the option database. .PP option add *TCombobox*Listbox.background \fIcolor\fP .br option add *TCombobox*Listbox.font \fIfont\fP .br option add *TCombobox*Listbox.foreground \fIcolor\fP .br option add *TCombobox*Listbox.selectBackground \fIcolor\fP .br option add *TCombobox*Listbox.selectForeground \fIcolor\fP .PP To configure a specific listbox (subject to future change): .CS set popdown [ttk::combobox::PopdownWindow .mycombobox] $popdown.f.l configure \-font \fIfont\fP .CE .PP \fBComboboxPopdownFrame\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-borderwidth\fP \fIamount\fP .br \fB\-relief\fP \fIrelief\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), ttk::entry(n) .SH KEYWORDS choice, entry, list box, text box, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_entry.n0000644001000000100000000004274615105057705020033 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::entry n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::entry \- Editable text field widget .SH SYNOPSIS \fBttk::entry\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP An \fBttk::entry\fR widget displays a one-line text string and allows that string to be edited by the user. The value of the string may be linked to a Tcl variable with the \fB\-textvariable\fR option. Entry widgets support horizontal scrolling with the standard \fB\-xscrollcommand\fR option and \fBxview\fR widget command. .SO ttk_widget \-class \-cursor \-font \-foreground \-style \-takefocus \-xscrollcommand \-placeholder \-placeholderforeground .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-exportselection exportSelection ExportSelection A boolean value specifying whether or not a selection in the widget should be linked to the X selection. If the selection is exported, then selecting in the widget deselects the current X selection, selecting outside the widget deselects any widget selection, and the widget will respond to selection retrieval requests when it has a selection. .\" MAYBE: .OP \-insertbackground insertBackground Foreground .\" MAYBE: .OP \-insertwidth insertWidth InsertWidth .OP \-invalidcommand invalidCommand InvalidCommand A script template to evaluate whenever the \fB\-validatecommand\fR returns 0. See \fBVALIDATION\fR below for more information. .OP \-justify justify Justify Specifies how the text is aligned within the entry widget. One of \fBleft\fR, \fBcenter\fR, or \fBright\fR. .\" MAYBE: .OP \-selectbackground selectBackground Foreground .\" MAYBE: .OP \-selectborderwidth selectBorderWidth BorderWidth .\" MAYBE: .OP \-selectforeground selectForeground Background .OP \-show show Show If this option is specified, then the true contents of the entry are not displayed in the window. Instead, each character in the entry's value will be displayed as the first character in the value of this option, such as .QW * or a bullet. This is useful, for example, if the entry is to be used to enter a password. If characters in the entry are selected and copied elsewhere, the information copied will be what is displayed, not the true contents of the entry. .OP \-state state State Compatibility option; see \fIttk::widget(n)\fR for details. Specifies one of three states for the entry, \fBnormal\fR, \fBdisabled\fR, or \fBreadonly\fR. See \fBWIDGET STATES\fR, below. .OP \-textvariable textVariable Variable Specifies the name of a global variable whose value is linked to the entry widget's contents. Whenever the variable changes value, the widget's contents are updated, and vice versa. .OP \-validate validate Validate Specifies the mode in which validation should operate: \fBnone\fR, \fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. Default is \fBnone\fR, meaning that validation is disabled. See \fBVALIDATION\fR below. .OP \-validatecommand validateCommand ValidateCommand A script template to evaluate whenever validation is triggered. If set to the empty string (the default), validation is disabled. The script must return a boolean value. See \fBVALIDATION\fR below. .OP \-width width Width Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. .\" Not in ttk: If the value is negative or zero, the widget picks a .\" Not in ttk: size just large enough to hold its current text. .SH NOTES .PP A portion of the entry may be selected as described below. If an entry is exporting its selection (see the \fB\-exportselection\fR option), then it will observe the standard X11 protocols for handling the selection; entry selections are available as type \fBSTRING\fR. Entries also observe the standard Tk rules for dealing with the input focus. When an entry has the input focus it displays an \fIinsert cursor\fR to indicate where new characters will be inserted. .PP Entries are capable of displaying strings that are too long to fit entirely within the widget's window. In this case, only a portion of the string will be displayed; commands described below may be used to change the view in the window. Entries use the standard \fB\-xscrollcommand\fR mechanism for interacting with scrollbars (see the description of the \fB\-xscrollcommand\fR option for details). .SH "INDICES" .PP Many of the \fBentry\fR widget commands take one or more indices as arguments. An index specifies a particular character in the entry's string, in any of the following ways: .IP \fInumber\fR Specifies the character as a numerical index, where 0 corresponds to the first character in the string. .IP \fB@\fInumber\fR In this form, \fInumber\fR is treated as an x-coordinate in the entry's window; the character spanning that x-coordinate is used. For example, .QW \fB@0\fR indicates the left-most character in the window. .IP \fBend\fR Indicates the character just after the last one in the entry's string. This is equivalent to specifying a numerical index equal to the length of the entry's string. .IP \fBinsert\fR Indicates the character adjacent to and immediately following the insert cursor. .IP \fBsel.first\fR Indicates the first character in the selection. It is an error to use this form if the selection is not in the entry window. .IP \fBsel.last\fR Indicates the character just after the last one in the selection. It is an error to use this form if the selection is not in the entry window. .LP Abbreviations may be used for any of the forms above, e.g.\| .QW \fBe\fR or .QW \fBsel.l\fR . In general, out-of-range indices are automatically rounded to the nearest legal value. Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR, \fBstyle\fR and \fBxview\fR commands (see \fBttk::widget\fR), entry widgets support the following additional commands: .\" METHOD: bbox .TP \fIpathName \fBbbox \fIindex\fR . Returns a list of four numbers describing the bounding box of the character given by \fIindex\fR. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. .\" METHOD: delete .TP \fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? . Delete one or more elements of the entry. \fIFirst\fR is the index of the first character to delete, and \fIlast\fR is the index of the character just after the last one to delete. If \fIlast\fR is not specified it defaults to \fIfirst\fR+1, i.e. a single character is deleted. This command returns the empty string. .\" METHOD: get .TP \fIpathName \fBget\fR . Returns the entry's string. .\" METHOD: icursor .TP \fIpathName \fBicursor \fIindex\fR . Arrange for the insert cursor to be displayed just before the character given by \fIindex\fR. Returns the empty string. .\" METHOD: index .TP \fIpathName \fBindex\fI index\fR . Returns the numerical index corresponding to \fIindex\fR. .\" METHOD: insert .TP \fIpathName \fBinsert \fIindex string\fR . Insert \fIstring\fR just before the character indicated by \fIindex\fR. Returns the empty string. .\" METHOD: selection .TP \fIpathName \fBselection \fIoption arg\fR . This command is used to adjust the selection within an entry. It has several forms, depending on \fIoption\fR: .RS .TP \fIpathName \fBselection clear\fR . Clear the selection if it is currently in this widget. If the selection is not in this widget then the command has no effect. Returns the empty string. .TP \fIpathName \fBselection present\fR . Returns 1 if there is are characters selected in the entry, 0 if nothing is selected. .TP \fIpathName \fBselection range \fIstart end\fR . Sets the selection to include the characters starting with the one indexed by \fIstart\fR and ending with the one just before \fIend\fR. If \fIend\fR refers to the same character as \fIstart\fR or an earlier one, then the entry's selection is cleared. .RE .\" METHOD: validate .TP \fIpathName \fBvalidate\fR . Force revalidation, independent of the conditions specified by the \fB\-validate\fR option. Returns 0 if validation fails, 1 if it succeeds. Sets or clears the \fBinvalid\fR state accordingly. See \fBVALIDATION\fR below for more details. .SH VALIDATION .PP The \fB\-validate\fR, \fB\-validatecommand\fR, and \fB\-invalidcommand\fR options are used to enable entry widget validation. .SS "VALIDATION MODES" .PP There are two main validation modes: \fIprevalidation\fR, in which the \fB\-validatecommand\fR is evaluated prior to each edit and the return value is used to determine whether to accept or reject the change; and \fIrevalidation\fR, in which the \fB\-validatecommand\fR is evaluated to determine whether the current value is valid. .PP The \fB\-validate\fR option determines when validation occurs; it may be set to any of the following values: .RS .IP \fBnone\fR Default. This means validation will only occur when specifically requested by the \fBvalidate\fR widget command. .IP \fBkey\fR The entry will be prevalidated prior to each edit (specifically, whenever the \fBinsert\fR or \fBdelete\fR widget commands are called). If prevalidation fails, the edit is rejected. .IP \fBfocus\fR The entry is revalidated when the entry receives or loses focus. .IP \fBfocusin\fR The entry is revalidated when the entry receives focus. .IP \fBfocusout\fR The entry is revalidated when the entry loses focus. .IP \fBall\fR Validation is performed for all above conditions. .RE .PP The \fB\-invalidcommand\fR is evaluated whenever the \fB\-validatecommand\fR returns a false value. .PP The \fB\-validatecommand\fR and \fB\-invalidcommand\fR may modify the entry widget's value via the widget \fBinsert\fR or \fBdelete\fR commands, or by setting the linked \fB\-textvariable\fR. If either does so during prevalidation, then the edit is rejected regardless of the value returned by the \fB\-validatecommand\fR. .PP If \fB\-validatecommand\fR is empty (the default), validation always succeeds. .SS "VALIDATION SCRIPT SUBSTITUTIONS" .PP It is possible to perform percent substitutions on the \fB\-validatecommand\fR and \fB\-invalidcommand\fR, just as in a \fBbind\fR script. The following substitutions are recognized: .RS .IP \fB%d\fR Type of action: 1 for \fBinsert\fR prevalidation, 0 for \fBdelete\fR prevalidation, or \-1 for revalidation. .IP \fB%i\fR Index of character string to be inserted/deleted, if any, otherwise \-1. .IP \fB%P\fR In prevalidation, the new value of the entry if the edit is accepted. In revalidation, the current value of the entry. .IP \fB%s\fR The current value of entry prior to editing. .IP \fB%S\fR The text string being inserted/deleted, if any, {} otherwise. .IP \fB%v\fR The current value of the \fB\-validate\fR option. .IP \fB%V\fR The validation condition that triggered the callback (\fBkey\fR, \fBfocusin\fR, \fBfocusout\fR, or \fBforced\fR). .IP \fB%W\fR The name of the entry widget. .RE .SS "DIFFERENCES FROM TK ENTRY WIDGET VALIDATION" .PP The standard Tk entry widget automatically disables validation (by setting \fB\-validate\fR to \fBnone\fR) if the \fB\-validatecommand\fR or \fB\-invalidcommand\fR modifies the entry's value. The Tk themed entry widget only disables validation if one of the validation scripts raises an error, or if \fB\-validatecommand\fR does not return a valid boolean value. (Thus, it is not necessary to re-enable validation after modifying the entry value in a validation script). .PP In addition, the standard entry widget invokes validation whenever the linked \fB\-textvariable\fR is modified; the Tk themed entry widget does not. .SH "DEFAULT BINDINGS" .PP The entry widget's default bindings enable the following behavior. In the descriptions below, .QW word refers to a contiguous group of letters, digits, or .QW _ characters, or any single character other than these. .IP \0\(bu 4 Clicking mouse button 1 positions the insert cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 down strokes out a selection between the insert cursor and the character under the mouse. .IP \0\(bu 4 Double-clicking with mouse button 1 selects the word under the mouse and positions the insert cursor at the end of the word. Dragging after a double click strokes out a selection consisting of whole words. .IP \0\(bu 4 Triple-clicking with mouse button 1 selects all of the text in the entry and positions the insert cursor at the end of the line. .IP \0\(bu 4 The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words. .IP \0\(bu 4 Clicking mouse button 1 with the Control key down will position the insert cursor in the entry without affecting the selection. .IP \0\(bu 4 If any normal printing characters are typed in an entry, they are inserted at the point of the insert cursor. .IP \0\(bu 4 The view in the entry can be adjusted by dragging with the middle mouse button (button 2, or button 3 in TkAqua). If the middle mouse button is clicked without moving the mouse, the selection is copied into the entry at the position of the mouse cursor. .IP \0\(bu 4 If the mouse is dragged out of the entry on the left or right sides while button 1 is pressed, the entry will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window). .IP \0\(bu 4 The Left and Right keys move the insert cursor one character to the left or right; they also clear any selection in the entry. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insert cursor by words, and Control-Shift-Left and Control-Shift-Right move the insert cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. .IP \0\(bu 4 The Home key and Control-a move the insert cursor to the beginning of the entry and clear any selection in the entry. Shift-Home moves the insert cursor to the beginning of the entry and extends the selection to that point. .IP \0\(bu 4 The End key and Control-e move the insert cursor to the end of the entry and clear any selection in the entry. Shift-End moves the cursor to the end and extends the selection to that point. .IP \0\(bu 4 Control-/ selects all the text in the entry. .IP \0\(bu 4 Control-\e clears any selection in the entry. .IP \0\(bu 4 The standard Tk <>, <>, <>, and <> virtual events operate on the selection in the expected manner. .IP \0\(bu 4 The Delete key deletes the selection, if there is one in the entry. If there is no selection, it deletes the character to the right of the insert cursor. .IP \0\(bu 4 The BackSpace key and Control-h delete the selection, if there is one in the entry. If there is no selection, it deletes the character to the left of the insert cursor. .IP \0\(bu 4 Control-d deletes the character to the right of the insert cursor. .IP \0\(bu 4 Control-k deletes all the characters to the right of the insertion cursor. .SH "WIDGET STATES" .PP In the \fBdisabled\fR state, the entry cannot be edited and the text cannot be selected. In the \fBreadonly\fR state, no insert cursor is displayed and the entry cannot be edited (specifically: the \fBinsert\fR and \fBdelete\fR commands have no effect). The \fBdisabled\fR state is the same as \fBreadonly\fR, and in addition text cannot be selected. .PP Note that changes to the linked \fB\-textvariable\fR will still be reflected in the entry, even if it is disabled or readonly. .PP Typically, the text is .QW grayed-out in the \fBdisabled\fR state, and a different background is used in the \fBreadonly\fR state. .PP The entry widget sets the \fBinvalid\fR state if revalidation fails, and clears it whenever validation succeeds. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::entry\fP is \fBTEntry\fP. .PP Dynamic states: \fBdisabled\fP, \fBfocus\fP, \fBreadonly\fP. .PP \fBTEntry\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .RS For backwards compatibility, when using the aqua theme (for macOS), this option behaves as an alias for the \fB\-fieldbackground\fP provided that no value is specified for \fB\-fieldbackground\fP. Otherwise it is ignored. .RE \fB\-bordercolor\fP \fIcolor\fP .br \fB\-darkcolor\fP \fIcolor\fP .br \fB\-fieldbackground\fP \fIcolor\fP .RS Some themes use a graphical background and their field background colors cannot be changed. .RE \fB\-foreground\fP \fIcolor\fP .br \fB\-insertcolor\fP \fIcolor\fP .br \fB\-insertwidth\fP \fIamount\fP .br \fB\-lightcolor\fP \fIcolor\fP .br \fB\-padding\fP \fIpadding\fP .br \fB\-placeholderforeground\fP \fIcolor\fP .br \fB\-relief\fP \fIrelief\fP .br \fB\-selectbackground\fP \fIcolor\fP .br \fB\-selectborderwidth\fP \fIamount\fP .br \fB\-selectforeground\fP \fIcolor\fP .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), entry(n) .SH KEYWORDS entry, widget, text field '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_frame.n0000644001000000100000000000424215105057705017751 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2005 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::frame n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::frame \- Simple container widget .SH SYNOPSIS \fBttk::frame\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP A \fBttk::frame\fR widget is a container, used to group other widgets together. .SO ttk_widget \-class \-cursor \-padding \-style \-takefocus .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-borderwidth borderWidth BorderWidth The desired width of the widget border. Defaults to 0. May be ignored depending on the theme used. .OP \-relief relief Relief One of the standard Tk border styles: \fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, \fBsolid\fR, or \fBsunken\fR. Defaults to \fBflat\fR. .OP \-width width Width If specified, the widget's requested width in pixels. .OP \-height height Height If specified, the widget's requested height in pixels. .SH "WIDGET COMMAND" .PP Frame widgets support the standard commands \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR (see \fBttk::widget\fR). .SH "NOTES" .PP Note that if the \fBpack\fR, \fBgrid\fR, or other geometry managers are used to manage the children of the \fBframe\fR, by the GM's requested size will normally take precedence over the \fBframe\fR widget's \fB\-width\fR and \fB\-height\fR options. \fBpack propagate\fR and \fBgrid propagate\fR can be used to change this. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::frame\fP is \fBTFrame\fP. .PP \fBTFrame\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-relief\fP \fIrelief\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH BINDINGS .PP When a new \fBttk::frame\fR is created, it has no default event bindings; \fBttk::frame\fRs are not intended to be interactive. .SH "SEE ALSO" ttk::widget(n), ttk::labelframe(n), frame(n) .SH "KEYWORDS" widget, frame, container '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_Geometry.30000644001000000100000000001756015105057705020366 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" .TH Geometry 3 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME Ttk_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 .SH SYNOPSIS .nf \fB#include \fR Ttk_Box \fBTtk_MakeBox\fR(int \fIx\fR, int \fIy\fR, int \fIwidth\fR, int \fIheight\fR); Ttk_Box \fBTtk_PadBox\fR(Ttk_Box \fIparcel\fR, Ttk_Padding \fIpadding\fR); Ttk_Box \fBTtk_ExpandBox\fR(Ttk_Box \fIparcel\fR, Ttk_Padding \fIpadding\fR); Ttk_Box \fBTtk_PackBox\fR(Ttk_Box *\fIcavity\fR, int \fIwidth\fR, int \fIheight\fR, Ttk_Side \fIside\fR); Ttk_Box \fBTtk_StickBox\fR(Ttk_Box \fIparcel\fR, int \fIwidth\fR, int \fIheight\fR, unsigned \fIsticky\fR); Ttk_Box \fBTtk_PlaceBox\fR(Ttk_Box *\fIcavity\fR, int \fIwidth\fR, int \fIheight\fR, Ttk_Side \fIside\fR, unsigned \fIsticky\fR); Ttk_Box \fBTtk_AnchorBox\fR(Ttk_Box \fIparcel\fR, int \fIwidth\fR, int \fIheight\fR, Tk_Anchor \fIanchor\fR); Ttk_Padding \fBTtk_MakePadding\fR(short \fIleft\fR, short \fItop\fR, short \fIright\fR, short \fIbottom\fR); Ttk_Padding \fBTtk_UniformPadding\fR(short \fIborder\fR); Ttk_Padding \fBTtk_AddPadding\fR(Ttk_Padding \fIpadding1\fR, Ttk_Padding \fIpadding2\fR; Ttk_Padding \fBTtk_RelievePadding\fR(Ttk_Padding \fIpadding\fR, int \fIrelief\fR); int \fBTtk_BoxContains\fR(Ttk_Box \fIbox\fR, int \fIx\fR, int \fIy\fR); int \fBTtk_GetPaddingFromObj\fR(Tcl_Interp *\fIinterp\fR, Tk_Window \fItkwin\fR, Tcl_Obj *\fIobjPtr\fR, Ttk_Padding *\fIpadding_rtn\fR); int \fBTtk_GetBorderFromObj\fR(Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR, Ttk_Padding *\fIpadding_rtn\fR); int \fBTtk_GetStickyFromObj\fR(Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR, int *\fIsticky_rtn\fR); .fi .SH ARGUMENTS .AP Tk_Anchor anchor in One of the symbolic constants \fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR, etc. See \fITk_GetAnchorFromObj(3)\fR. .AP "Ttk_Box *" cavity in/out A rectangular region from which a parcel is allocated. .AP short border in Extra padding (in pixels) to add uniformly to each side of a region. .AP short bottom in Extra padding (in pixels) to add to the bottom of a region. .AP Ttk_Box box in Specifies a rectangular region. .AP "Ttk_Box *" box_rtn out A rectangular region. .AP int height in The height in pixels of a region. .AP "Tcl_Interp *" interp in Used to store error messages. .AP int left in Extra padding (in pixels) to add to the left side of a region. .AP "Tcl_Obj *" objPtr in String value contains a symbolic name to be converted to an enumerated value or bitmask. Internal rep may be be modified to cache corresponding value. .AP Ttk_Padding padding in Extra padding to add on the inside of a region. .AP "Ttk_Padding *" padding_rtn out Padding present in the inside of a region. .AP Ttk_Box parcel in A rectangular region, allocated from a cavity. .AP int relief in One of the standard Tk relief options (\fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, etc.). See \fBTk_GetReliefFromObj\fR. .AP short right in Extra padding (in pixels) to add to the right side of a region. .AP Ttk_Side side in One of \fBTTK_SIDE_LEFT\fR, \fBTTK_SIDE_TOP\fR, \fBTTK_SIDE_RIGHT\fR, or \fBTTK_SIDE_BOTTOM\fR. .AP unsigned sticky in A bitmask containing one or more of the bits \fBTTK_STICK_W\fR (west, or left), \fBTTK_STICK_E\fR (east, or right), \fBTTK_STICK_N\fR (north, or top), and \fBTTK_STICK_S\fR (south, or bottom). \fBTTK_FILL_X\fR is defined as a synonym for (\fBTTK_STICK_W\fR|\fBTTK_STICK_E\fR), \fBTTK_FILL_Y\fR is a synonym for (\fBTTK_STICK_N\fR|\fBTTK_STICK_S\fR), and \fBTTK_FILL_BOTH\fR is a synonym for (\fBTTK_FILL_X\fR|\fBTTK_FILL_Y\fR). See also: \fIgrid(n)\fR. .AP Tk_Window tkwin in Window whose screen geometry determines the conversion between absolute units and pixels. .AP short top in Extra padding at the top of a region. .AP int width in The width in pixels of a region. .AP int x in X coordinate of upper-left corner of region. .AP int y in Y coordinate of upper-left corner of region. .BE .SH "BOXES" .PP The \fBTtk_Box\fR structure represents a rectangular region of a window: .CS typedef struct { int \fIx\fR; int \fIy\fR; int \fIwidth\fR; int \fIheight\fR; } \fBTtk_Box\fR; .CE All coordinates are relative to the window. .PP \fBTtk_MakeBox\fR is a convenience routine that constructs a \fBTtk_Box\fR structure representing a region \fIwidth\fR pixels wide, \fIheight\fR pixels tall, at the specified \fIx, y\fR coordinates. .PP \fBTtk_PadBox\fR returns a new box located inside the specified \fIparcel\fR, shrunken according to the left, top, right, and bottom margins specified by \fIpadding\fR. .PP \fBTtk_ExpandBox\fR is the inverse of \fBTtk_PadBox\fR: it returns a new box surrounding the specified \fIparcel\fR, expanded according to the left, top, right, and bottom margins specified by \fIpadding\fR. .PP \fBTtk_PackBox\fR allocates a parcel \fIwidth\fR by \fIheight\fR pixels wide on the specified \fIside\fR of the \fIcavity\fR, and shrinks the \fIcavity\fR accordingly. .PP \fBTtk_StickBox\fR places a box with the requested \fIwidth\fR and \fIheight\fR inside the \fIparcel\fR according to the \fIsticky\fR bits. .PP \fBTtk_PlaceBox\fR combines \fBTtk_PackBox\fR and \fBTtk_StickBox\fR: it allocates a parcel on the specified \fIside\fR of the \fIcavity\fR, places a box of the requested size inside the parcel according to \fIsticky\fR, and shrinks the \fIcavity\fR. .PP \fBTtk_AnchorBox\fR places a box with the requested \fIwidth\fR and \fIheight\fR inside the \fIparcel\fR according to the specified \fIanchor\fR option. .PP \fBTtk_BoxContains\fR tests if the specified \fIx, y\fR coordinate lies within the rectangular region \fIbox\fR. .SH "PADDDING" .PP The \fBTtk_Padding\fR structure is used to represent borders, internal padding, and external margins: .CS typedef struct { short \fIleft\fR; short \fItop\fR; short \fIright\fR; short \fIbottom\fR; } \fBTtk_Padding\fR; .CE .PP \fBTtk_MakePadding\fR is a convenience routine that constructs a \fBTtk_Padding\fR structure with the specified left, top, right, and bottom components. .PP \fBTtk_UniformPadding\fR constructs a \fBTtk_Padding\fR structure with all components equal to the specified \fIborder\fR. .PP \fBTtk_AddPadding\fR adds two \fBTtk_Padding\fRs together and returns a combined padding containing the sum of the individual padding components. .PP \fBTtk_RelievePadding\fR adds an extra 2 pixels of padding to \fIpadding\fR according to the specified \fIrelief\fR. If \fIrelief\fR is \fBTK_RELIEF_SUNKEN\fR, adds two pixels at the top and left so the inner region is shifted down and to the left. If it is \fBTK_RELIEF_RAISED\fR, adds two pixels at the bottom and right so the inner region is shifted up and to the right. Otherwise, adds 1 pixel on all sides. This is typically used in element geometry procedures to simulate a .QW pressed-in look for pushbuttons. .SH "CONVERSION ROUTINES" .PP \fBTtk_GetPaddingFromObj\fR converts the string in \fIobjPtr\fR to a \fBTtk_Padding\fR structure. The string representation is a list of up to four length specifications .QW "\fIleft top right bottom\fR" . If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, \fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. See \fBTk_GetPixelsFromObj(3)\fR for the syntax of length specifications. .PP \fBTtk_GetBorderFromObj\fR is the same as \fBTtk_GetPaddingFromObj\fR except that the lengths are specified as integers (i.e., resolution-dependent values like \fI3m\fR are not allowed). .PP \fBTtk_GetStickyFromObj\fR converts the string in \fIobjPtr\fR to a \fIsticky\fR bitmask. The string contains zero or more of the characters \fBn\fR, \fBs\fR, \fBe\fR, or \fBw\fR. .SH "SEE ALSO" Tk_GetReliefFromObj(3), Tk_GetPixelsFromObj(3), Tk_GetAnchorFromObj(3) .SH "KEYWORDS" geometry, padding, margins, box, region, sticky, relief tk9.0.3/doc/ttk_image.n0000644001000000100000000000730715105057705017746 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk_image n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk_image \- Define an element based on an image .SH SYNOPSIS \fBttk::style element create \fIname \fBimage\fI imageSpec\fR ?\fIoptions\fR? .BE .SH DESCRIPTION .PP The \fIimage\fR element factory creates a new element in the current theme whose visual appearance is determined by Tk images. \fIimageSpec\fP is a list of one or more elements. The first element is the default image name. The rest of the list is a sequence of \fIstatespec / value\fR pairs specifying other images to use when the element is in a particular state or combination of states. .SH OPTIONS .PP Valid \fIoptions\fR are: .\" OPTION: -border .TP \fB\-border\fI padding\fR . \fIpadding\fR is a list of up to four integers, specifying the left, top, right, and bottom borders, respectively. If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, \fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. In other words, a list of three numbers specify the left, vertical, and right border; a list of two numbers specify the horizontal and the vertical border; a single number specifies the same border all the way around the element. See \fBIMAGE STRETCHING\fR, below. .\" OPTION: -height .TP \fB\-height \fIheight\fR . Specifies a minimum height for the element. If negative, the base image's height is used as a default. .\" OPTION: -padding .TP \fB\-padding\fI padding\fR . Specifies the element's interior padding. The padding is a list of up to four length specifications \fIleft top right bottom\fR. If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, \fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. In other words, a list of three numbers specify the left, vertical, and right padding; a list of two numbers specify the horizontal and the vertical padding; a single number specifies the same padding all the way around the widget. Defaults to \fB\-border\fR if not specified. .\" OPTION: -sticky .TP \fB\-sticky\fI spec\fR . Specifies how the image is placed within the final parcel. \fIspec\fR contains zero or more characters .QW n , .QW s , .QW w , or .QW e . .\" OPTION: -width .TP \fB\-width \fIwidth\fR . Specifies a minimum width for the element. If negative, the base image's width is used as a default. .SH "IMAGE STRETCHING" .PP If the element's allocated parcel is larger than the image, the image will be placed in the parcel based on the \fB\-sticky\fR option. If the image needs to stretch horizontally (i.e., \fB\-sticky ew\fR) or vertically (\fB\-sticky ns\fR), subregions of the image are replicated to fill the parcel based on the \fB\-border\fR option. The \fB\-border\fR divides the image into 9 regions: four fixed corners, top and left edges (which may be tiled horizontally), left and right edges (which may be tiled vertically), and the central area (which may be tiled in both directions). .PP An image element that is not meant to claim any space (for example when used as a background image) should use \fB\-width 0\fR and \fB\-height 0\fR. .SH "EXAMPLE" .PP .CS set img1 [image create photo -file button.png] set img2 [image create photo -file button-pressed.png] set img3 [image create photo -file button-active.png] ttk::style element create Button.button image \e [list $img1 pressed $img2 active $img3] \e -border {2 4} -sticky we .CE .SH "SEE ALSO" ttk::intro(n), ttk::style(n), ttk_vsapi(n), image(n), photo(n) .SH KEYWORDS style, theme, appearance, pixmap theme, image '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_intro.n0000644001000000100000000001452615105057705020020 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::intro n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::intro \- Introduction to the Tk theme engine .BE .SH "OVERVIEW" .PP The Tk themed widget set is based on a revised and enhanced version of TIP #48 (https://tip.tcl-lang.org/48) specified style engine. The main concepts are described below. The basic idea is to separate, to the extent possible, the code implementing a widget's behavior from the code implementing its appearance. Widget class bindings are primarily responsible for maintaining the widget state and invoking callbacks; all aspects of the widget's appearance are controlled by the style of the widget (i.e. the style of the elements of the widget). .SH "THEMES" .PP A \fItheme\fR is a collection of elements and styles that determine the look and feel of the widget set. Themes can be used to: .IP \(bu isolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...) .IP \(bu adapt to display limitations (low-color, grayscale, monochrome, tiny screens) .IP \(bu accessibility (high contrast, large type) .IP \(bu application suite branding .IP \(bu blend in with the rest of the desktop (Gnome, KDE, Java) .IP \(bu and, of course: eye candy. .SH "ELEMENTS" .PP An \fIelement\fR displays an individual part of a widget. For example, a vertical scrollbar widget contains \fBuparrow\fR, \fBdownarrow\fR, \fBtrough\fR and \fBslider\fR elements. .PP Element names use a recursive dotted notation. For example, \fBuparrow\fR identifies a generic arrow element, and \fBScrollbar.uparrow\fR and \fBCombobox.uparrow\fR identify widget-specific elements. When looking for an element, the style engine looks for the specific name first, and if an element of that name is not found it looks for generic elements by stripping off successive leading components of the element name. .PP Like widgets, elements have \fIoptions\fR which specify what to display and how to display it. For example, the \fBtext\fR element (which displays a text string) has \fB\-text\fR, \fB\-font\fR, \fB\-foreground\fR, \fB\-background\fR, \fB\-underline\fR, and \fB\-width\fR options. The value of an element option is taken from (in precedence order): .IP \(bu an option of the same name and type in the widget containing the element; .IP \(bu a dynamic setting specified by \fBstyle map\fR and the current state; .IP \(bu the default setting specified by \fBstyle configure\fR; or .IP \(bu the element's built-in default value for the option. .SH "LAYOUTS" .PP A \fIlayout\fR specifies which elements make up a widget and how they are arranged. The layout engine uses a simplified version of the \fBpack\fR algorithm: starting with an initial cavity equal to the size of the widget, elements are allocated a parcel within the cavity along the side specified by the \fB\-side\fR option, and placed within the parcel according to the \fB\-sticky\fR option. For example, the layout for a horizontal scrollbar is: .PP .CS ttk::\fBstyle layout\fR Horizontal.TScrollbar { Scrollbar.trough -children { Scrollbar.leftarrow -side left -sticky w Scrollbar.rightarrow -side right -sticky e Scrollbar.thumb -sticky ew } } .CE .PP By default, the layout for a widget is the same as its class name. Some widgets may override this (for example, the \fBttk::scrollbar\fR widget chooses different layouts based on the \fB\-orient\fR option). .SH "STATES" .PP In standard Tk, many widgets have a \fB\-state\fR option which (in most cases) is either \fBnormal\fR or \fBdisabled\fR. Some widgets support additional states, such as the \fBentry\fR widget which has a \fBreadonly\fR state and the various flavors of buttons which have \fBactive\fR state. .PP The themed Tk widgets generalizes this idea: every widget has a bitmap of independent state flags. Widget state flags include \fBactive\fR, \fBdisabled\fR, \fBpressed\fR, \fBfocus\fR, etc., (see \fIttk::widget(n)\fR for the full list of state flags). .PP Instead of a \fB\-state\fR option, every widget now has a \fBstate\fR widget command which is used to set or query the state. A \fIstate specification\fR is a list of symbolic state names indicating which bits are set, each optionally prefixed with an exclamation point indicating that the bit is cleared instead. .PP For example, the class bindings for the \fBttk::button\fR widget are: .PP .CS bind TButton { %W state active } bind TButton { %W state !active } bind TButton { %W state pressed } bind TButton { %W state !pressed } bind TButton { %W state pressed } bind TButton \e { %W instate {pressed} { %W state !pressed ; %W invoke } } .CE .PP This specifies that the widget becomes \fBactive\fR when the pointer enters the widget, and inactive when it leaves. Similarly it becomes \fBpressed\fR when the mouse button is pressed, and \fB!pressed\fR on the ButtonRelease event. In addition, the button unpresses if pointer is dragged outside the widget while Button-1 is held down, and represses if it's dragged back in. Finally, when the mouse button is released, the widget's \fB\-command\fR is invoked, but only if the button is currently in the \fBpressed\fR state. (The actual bindings are a little more complicated than the above, but not by much). '\" Note to self: rewrite that paragraph. It's horrible. .SH "STYLES" .PP Each widget is associated with a \fIstyle\fR, which specifies values for element options. Style names use a recursive dotted notation like layouts and elements; by default, widgets use the class name to look up a style in the current theme. For example: .PP .CS ttk::\fBstyle configure\fR TButton \e -background #d9d9d9 \e -foreground black \e -relief raised \e ; .CE .PP Many elements are displayed differently depending on the widget state. For example, buttons have a different background when they are active, a different foreground when disabled, and a different relief when pressed. The \fBstyle map\fR command specifies dynamic option settings for a particular style: .PP .CS ttk::\fBstyle map\fR TButton \e -background [list disabled #d9d9d9 active #ececec] \e -foreground [list disabled #a3a3a3] \e -relief [list {pressed !disabled} sunken] \e ; .CE .SH "SEE ALSO" ttk::widget(n), ttk::style(n) '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_label.n0000644001000000100000000000404615105057705017740 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::label n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::label \- Display a text string and/or image .SH SYNOPSIS \fBttk::label\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP A \fBttk::label\fR widget displays a textual label and/or image. The label may be linked to a Tcl variable to automatically change the displayed text. .SO ttk_widget \-anchor \-class \-compound \-cursor \-font \-foreground \-image \-justify \-padding \-state \-style \-takefocus \-text \-textvariable \-underline \-width \-wraplength .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-background frameColor FrameColor The widget's background color. If unspecified, the theme default is used. .OP \-relief relief Relief .\" Rewrite this: Specifies the 3-D effect desired for the widget border. Valid values are \fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, \fBsolid\fR, and \fBsunken\fR. .OP \-wraplength wrapLength WrapLength Specifies the maximum line length (in pixels). If this option is negative or zero, then automatic wrapping is not performed; otherwise the text is split into lines such that no line is longer than the specified value. .SH "WIDGET COMMAND" .PP Label widgets support the standard commands \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR (see \fBttk::widget\fR). .SH "STYLING OPTIONS" .PP The class name for a \fBttk::label\fP is \fBTLabel\fP. .PP Dynamic states: \fBdisabled\fP, \fBreadonly\fP. .PP \fBTLabel\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-compound\fP \fIcompound\fP .br \fB\-foreground\fP \fIcolor\fP .br \fB\-font\fP \fIfont\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), label(n) '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_labelframe.n0000644001000000100000000000734215105057705020755 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2005 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::labelframe n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::labelframe \- Container widget with optional label .SH SYNOPSIS \fBttk::labelframe\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP A \fBttk::labelframe\fR widget is a container used to group other widgets together. It has an optional label, which may be a plain text string or another widget. .SO ttk_widget \-class \-cursor \-padding \-style \-takefocus .SE .SH "WIDGET-SPECIFIC OPTIONS" .\" XXX: Currently included, but may go away: .\" XXX: .OP -borderwidth borderWidth BorderWidth .\" XXX: The desired width of the widget border. Default is theme-dependent. .\" XXX: .OP -relief relief Relief .\" XXX: One of the standard Tk border styles: .\" XXX: \fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, .\" XXX: \fBsolid\fR, or \fBsunken\fR. .\" XXX: Default is theme-dependent. .OP \-height height Height If specified, the widget's requested height in pixels. (See \fIttk::frame(n)\fR for further notes on \fB\-width\fR and \fB\-height\fR). .OP \-labelanchor labelAnchor LabelAnchor Specifies where to place the label. Allowed values are (clockwise from the top upper left corner): \fBnw\fR, \fBn\fR, \fBne\fR, \fBen\fR, \fBe\fR, \fBes\fR, \fBse\fR, \fBs\fR,\fBsw\fR, \fBws\fR, \fBw\fR and \fBwn\fR. The default value is theme-dependent. .\" Alternate explanation: The first character must be one of n, s, e, or w .\" and specifies which side the label should be placed on; .\" the remaining characters specify how the label is aligned on that side. .\" NOTE: Now allows other values as well; leave this undocumented for now .OP \-labelwidget labelWidget LabelWidget The name of a widget to use for the label. If set, overrides the \fB\-text\fR option. The \fB\-labelwidget\fR must be a child of the \fBlabelframe\fR widget or one of the \fBlabelframe\fR's ancestors, and must belong to the same top-level widget as the \fBlabelframe\fR. .OP \-text text Text Specifies the text of the label. .OP \-underline underline Underline If set, specifies the integer index (0-based) of a character to underline in the text string. The underlined character is used for mnemonic activation. Mnemonic activation for a \fBttk::labelframe\fR sets the keyboard focus to the first child of the \fBttk::labelframe\fR widget. .OP \-width width Width If specified, the widget's requested width in pixels. .SH "WIDGET COMMAND" .PP Labelframe widgets support the standard commands \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR (see \fBttk::widget\fR). .SH "STYLING OPTIONS" .PP The class name for a \fBttk::labelframe\fP is \fBTLabelframe\fP. The text label has a class of \fBTLabelframe.Label\fP. .PP Dynamic states: \fBdisabled\fP, \fBreadonly\fP. .PP \fBTLabelframe\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-bordercolor\fP \fIcolor\fP .br \fB\-borderwidth\fP \fIamount\fP .br \fB\-darkcolor\fP \fIcolor\fP .br \fB\-labelmargins\fP \fIamount\fP .br \fB\-labeloutside\fP \fIboolean\fP .br \fB\-lightcolor\fP \fIcolor\fP .br \fB\-relief\fP \fIrelief\fP .PP \fBTLabelframe.Label\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-font\fP \fIfont\fP .br \fB\-foreground\fP \fIcolor\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), ttk::frame(n), labelframe(n) .SH "KEYWORDS" widget, frame, container, label, groupbox '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_menubutton.n0000644001000000100000000000444615105057705021065 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::menubutton n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::menubutton \- Widget that pops down a menu when pressed .SH SYNOPSIS \fBttk::menubutton\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP A \fBttk::menubutton\fR widget displays a textual label and/or image, and displays a menu when pressed. .SO ttk_widget \-class \-compound \-cursor \-image \-state \-style \-takefocus \-text \-textvariable \-underline \-width .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-direction direction Direction Specifies where the menu is to be popped up relative to the menubutton. One of: \fBabove\fR, \fBbelow\fR, \fBleft\fR, \fBright\fR, or \fBflush\fR. The default is \fBbelow\fR. \fBflush\fR pops the menu up directly over the menubutton. .OP \-menu menu Menu Specifies the path name of the menu associated with the menubutton. To be on the safe side, the menu ought to be a direct child of the menubutton. .\" not documented: may go away: .\" .OP \-anchor anchor Anchor .\" .OP \-padding padding Pad .SH "WIDGET COMMAND" .PP Menubutton widgets support the standard commands \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR (see \fBttk::widget\fR). .SH "STANDARD STYLES" .PP \fBTtk::menubutton\fR widgets support the \fBToolbutton\fR style in all standard themes, which is useful for creating widgets for toolbars. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::menubutton\fP is \fBTMenubutton\fP. .PP Dynamic states: \fBactive\fP, \fBdisabled\fP, \fBreadonly\fP. .PP \fBTMenubutton\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-arrowsize\fP \fIamount\fP .br \fB\-background\fP \fIcolor\fP .br \fB\-compound\fP \fIcompound\fP .br \fB\-foreground\fP \fIcolor\fP .br \fB\-font\fP \fIfont\fP .br \fB\-padding\fP \fIpadding\fP .br \fB\-relief\fP \fIrelief\fP .br \fB\-width\fP \fIamount\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), menu(n), menubutton(n) .SH "KEYWORDS" widget, button, menu '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_notebook.n0000644001000000100000000002516315105057705020504 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::notebook n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::notebook \- Multi-paned container widget .SH SYNOPSIS .nf \fBttk::notebook\fI pathname \fR?\fIoptions...\fR? .br \fIpathname \fBadd\fI window\fR ?\fIoptions...\fR? \fIpathname \fBinsert\fI index window\fR ?\fIoptions...\fR? .fi .BE .SH DESCRIPTION A \fBttk::notebook\fR widget manages a collection of windows and displays a single one at a time. Each content window is associated with a \fItab\fR, which the user may select to change the currently-displayed window. .SO ttk_widget \-class \-cursor \-takefocus \-style .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-height height Height If present and greater than zero, specifies the desired height of the pane area (not including internal padding or tabs). Otherwise, the maximum height of all panes is used. .OP \-padding padding Padding Specifies the amount of extra space to add around the outside of the notebook. The padding is a list of up to four length specifications \fIleft top right bottom\fR. If fewer than four elements are specified, \fIbottom\fR defaults to \fItop\fR, \fIright\fR defaults to \fIleft\fR, and \fItop\fR defaults to \fIleft\fR. In other words, a list of three numbers specify the left, vertical, and right padding; a list of two numbers specify the horizontal and the vertical padding; a single number specifies the same padding all the way around the widget. .OP \-width width Width If present and greater than zero, specifies the desired width of the pane area (not including internal padding). Otherwise, the maximum width of all panes is used. .SH "TAB OPTIONS" The following options may be specified for individual notebook panes: .OP \-state state State Either \fBnormal\fR, \fBdisabled\fR or \fBhidden\fR. If \fBdisabled\fR, then the tab is not selectable. If \fBhidden\fR, then the tab is not shown. .OP \-sticky sticky Sticky Specifies how the content window is positioned within the pane area. Value is a string containing zero or more of the characters \fBn, s, e,\fR or \fBw\fR. Each letter refers to a side (north, south, east, or west) that the content window will .QW stick to, as per the \fBgrid\fR geometry manager. .OP \-padding padding Padding Specifies the amount of extra space to add between the notebook and this pane. Syntax is the same as for the widget \fB\-padding\fR option. .OP \-text text Text Specifies a string to be displayed in the tab. .OP \-image image Image Specifies an image to display in the tab. See \fIttk_widget(n)\fR for details. .OP \-compound compound Compound Specifies how to display the image relative to the text, in the case both \fB\-text\fR and \fB\-image\fR are present. See \fIlabel(n)\fR for legal values. .OP \-underline underline Underline Specifies the integer index (0-based) of a character to underline in the text string. The underlined character is used for mnemonic activation if \fBttk::notebook::enableTraversal\fR is called. .SH "TAB IDENTIFIERS" The \fItabid\fR argument to the following commands may take any of the following forms: .IP \(bu An integer between zero and the number of tabs; .IP \(bu The name of a content window; .IP \(bu A positional specification of the form .QW @\fIx\fR,\fIy\fR , which identifies the tab .IP \(bu The literal string .QW \fBcurrent\fR , which identifies the currently-selected tab; or: .IP \(bu The literal string .QW \fBend\fR , which returns the number of tabs (only valid for .QW "\fIpathname \fBindex\fR" ). .PP Indexes support the same simple interpretation as for the command \fBstring index\fR, with simple integer index arithmetic and indexing relative to \fBend\fR. .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR commands (see \fBttk::widget\fR), notebook widgets support the following additional commands: .\" METHOD: add .TP \fIpathname \fBadd \fIwindow\fR ?\fIoptions...\fR? . Adds a new tab to the notebook. See \fBTAB OPTIONS\fR for the list of available \fIoptions\fR. If \fIwindow\fR is currently managed by the notebook but hidden, it is restored to its previous position. .\" METHOD: forget .TP \fIpathname \fBforget \fItabid\fR . Removes the tab specified by \fItabid\fR, unmaps and unmanages the associated window. .\" METHOD: hide .TP \fIpathname \fBhide \fItabid\fR . Hides the tab specified by \fItabid\fR. The tab will not be displayed, but the associated window remains managed by the notebook and its configuration remembered. Hidden tabs may be restored with the \fBadd\fR command. .\" METHOD: identify .TP \fIpathname \fBidentify\fI component x y\fR . Returns the name of the element under the point given by \fIx\fR and \fIy\fR, or the empty string if no component is present at that location. The following subcommands are supported: .RS .TP \fIpathname \fBidentify element\fI x y\fR . Returns the name of the element at the specified location. .TP \fIpathname \fBidentify tab\fI x y\fR . Returns the index of the tab at the specified location. .RE .\" METHOD: index .TP \fIpathname \fBindex \fItabid\fR . Returns the numeric index of the tab specified by \fItabid\fR, or the total number of tabs if \fItabid\fR is the string .QW \fBend\fR . .\" METHOD: insert .TP \fIpathname \fBinsert \fIpos subwindow options...\fR . Inserts a pane at the specified position. \fIpos\fR is either the string \fBend\fR, an integer index, or the name of a managed subwindow. If \fIsubwindow\fR is already managed by the notebook, moves it to the specified position. See \fBTAB OPTIONS\fR for the list of available options. .\" METHOD: select .TP \fIpathname \fBselect\fR ?\fItabid\fR? . Selects the specified tab. The associated content window will be displayed, and the previously-selected window (if different) is unmapped. If \fItabid\fR is omitted, returns the widget name of the currently selected pane. .\" METHOD: tab .TP \fIpathname \fBtab \fItabid\fR ?\fI\-option \fR?\fIvalue ...\fR . Query or modify the options of the specific tab. If no \fI\-option\fR is specified, returns a dictionary of the tab option values. If one \fI\-option\fR is specified, returns the value of that \fIoption\fR. Otherwise, sets the \fI\-option\fRs to the corresponding \fIvalue\fRs. See \fBTAB OPTIONS\fR for the available options. .\" METHOD: tabs .TP \fIpathname \fBtabs\fR . Returns the list of windows managed by the notebook, in the index order of their associated tabs. .SH "KEYBOARD TRAVERSAL" To enable keyboard traversal for a toplevel window containing a notebook widget \fI$nb\fR, call: .CS ttk::notebook::enableTraversal $nb .CE .PP This will extend the bindings for the toplevel window containing the notebook as follows: .IP \(bu \fBControl-Tab\fR selects the tab following the currently selected one. .IP \(bu \fBControl-Shift-Tab\fR selects the tab preceding the currently selected one. .IP \(bu \fBAlt-\fIK\fR, where \fIK\fR is the mnemonic (underlined) character of any tab, will select that tab. .PP Multiple notebooks in a single toplevel may be enabled for traversal, including nested notebooks. However, notebook traversal only works properly if all panes are direct children of the notebook. .SH "VIRTUAL EVENTS" The notebook widget generates a \fB<>\fR virtual event after a new tab is selected. .SH "EXAMPLE" .CS pack [\fBttk::notebook\fR .nb] \&.nb add [frame .nb.f1] -text "First tab" \&.nb add [frame .nb.f2] -text "Second tab" \&.nb select .nb.f2 ttk::notebook::enableTraversal .nb .CE .SH "STYLING OPTIONS" .PP The class name for a \fBttk::notebook\fP is \fBTNotebook\fP. The tab has a class name of \fBTNotebook.Tab\fP .PP Dynamic states: \fBactive\fP, \fBdisabled\fP, \fBselected\fP. .PP \fBTNotebook\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-bordercolor\fP \fIcolor\fP .br \fB\-darkcolor\fP \fIcolor\fP .br \fB\-foreground\fP \fIcolor\fP .br \fB\-lightcolor\fP \fIcolor\fP .br \fB\-padding\fP \fIpadding\fP .br \fB\-tabmargins\fP \fIpadding\fP .br \fB\-tabposition\fP \fIposition\fP .RS Specifies the position of the tab row or column as a string of length 1 or 2. The first character indicates the side as \fBn\fP, \fBs\fP, \fBw\fP, or \fBe\fP, while the second character (if present) is the sticky bit (specified as \fBw\fP, \fBe\fP, \fBn\fP, or \fBs\fP) within the tab position. The default position is \fBn\fP for the \fBaqua\fP theme and \fBnw\fP for all the other built-in themes. .RE .br .PP \fBTNotebook.Tab\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-bordercolor\fP \fIcolor\fP .br \fB\-compound\fP \fIcompound\fP .br \fB\-expand\fP \fIpadding\fP .RS Defines how much the tab grows in size. Usually used with the \fBselected\fP dynamic state. \fB\-tabmargins\fP should be set appropriately so that there is room for the tab growth. For example, the Ttk library file \fBvistaTheme.tcl\fP contains the lines .CS ttk::style configure TNotebook -tabmargins {2 2 2 0} ttk::style map TNotebook.Tab -expand {selected {2 2 2 2}} .CE which are valid for the default value \fBnw\fP of the \fB\-tabposition\fP style option. For a \fBttk::notebook\fP style \fBnbStyle\fP defined by .CS set nbStyle SW.TNotebook ttk::style configure $nbStyle -tabposition sw .CE you will have to adapt the above settings as follows: .CS ttk::style configure $nbStyle -tabmargins {2 0 2 2} ttk::style map $nbStyle.Tab -expand {selected {2 2 2 2}} .CE The easiest way to do this is to invoke the library procedure \fBttk::configureNotebookStyle\fP with \fB$nbStyle\fP as argument, after setting the style's \fB\-tabposition\fP option. .RE \fB\-font\fP \fIfont\fP .br \fB\-foreground\fP \fIcolor\fP .br \fB\-padding\fP \fIpadding\fP .RS Some themes use a different \fIpadding\fP for the selected tab. For example, the Ttk library file \fBclamTheme.tcl\fP contains the lines .CS ttk::style configure TNotebook.Tab \\ -padding {4.5p 1.5p 4.5p 1.5p} ttk::style map TNotebook.Tab \\ -padding {selected {4.5p 3p 4.5p 1.5p}} .CE which are valid for the default value \fBnw\fP of the \fB\-tabposition\fP style option. For a \fBttk::notebook\fP style having a different tab position you will have to adapt the above settings accordingly. Again, the easiest way to do this is to invoke the library procedure \fBttk::configureNotebookStyle\fP with the style name as argument, after setting the style's \fB\-tabposition\fP option. .RE .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), grid(n) .SH "KEYWORDS" pane, tab '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_panedwindow.n0000644001000000100000000001246415105057705021203 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2005 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::panedwindow n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::panedwindow \- Multi-pane container window .SH SYNOPSIS .nf \fBttk::panedwindow\fI pathname \fR?\fIoptions\fR? .br \fIpathname \fBadd\fI window\fR ?\fIoptions...\fR? \fIpathname \fBinsert\fI index window\fR ?\fIoptions...\fR? .fi .BE .SH DESCRIPTION A \fBttk::panedwindow\fR widget displays a number of subwindows, stacked either vertically or horizontally. The user may adjust the relative sizes of the subwindows by dragging the sash between panes. .SO ttk_widget \-class \-cursor \-takefocus \-style .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-orient orient Orient Specifies the orientation of the window. If \fBvertical\fR, subpanes are stacked top-to-bottom; if \fBhorizontal\fR, subpanes are stacked left-to-right. .OP \-width width Width If present and greater than zero, specifies the desired width of the widget in pixels. Otherwise, the requested width is determined by the width of the managed windows. .OP \-height height Height If present and greater than zero, specifies the desired height of the widget in pixels. Otherwise, the requested height is determined by the height of the managed windows. .SH "PANE OPTIONS" The following options may be specified for each pane: .OP \-weight weight Weight An integer specifying the relative stretchability of the pane. When the paned window is resized, the extra space is added or subtracted to each pane proportionally to its \fB\-weight\fR. .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR commands (see \fBttk::widget\fR), panedwindow widgets support the following additional commands: .\" METHOD: add .TP \fIpathname \fBadd \fIsubwindow options...\fR . Adds a new pane to the window. See \fBPANE OPTIONS\fR for the list of available options. .\" METHOD: forget .TP \fIpathname \fBforget \fIpane\fR . Removes the specified subpane from the widget. \fIpane\fR is either an integer index or the name of a managed subwindow. .\" METHOD: identify .TP \fIpathname \fBidentify \fIcomponent x y\fR . Returns the name of the element under the point given by \fIx\fR and \fIy\fR, or the empty string if no component is present at that location. If \fIcomponent\fR is omitted, it defaults to \fBsash\fR. The following subcommands are supported: .RS .TP \fIpathname \fBidentify element \fIx y\fR . Returns the name of the element at the specified location. .TP \fIpathname \fBidentify sash \fIx y\fR . Returns the index of the sash at the specified location. .RE .\" METHOD: insert .TP \fIpathname \fBinsert \fIpos subwindow options...\fR . Inserts a pane at the specified position. \fIpos\fR is either the string \fBend\fR, an integer index, or the name of a managed subwindow. If \fIsubwindow\fR is already managed by the paned window, moves it to the specified position. See \fBPANE OPTIONS\fR for the list of available options. .\" METHOD: pane .TP \fIpathname \fBpane \fIpane \-option \fR?\fIvalue \fR?\fI\-option value...\fR . Query or modify the options of the specified \fIpane\fR, where \fIpane\fR is either an integer index or the name of a managed subwindow. If no \fI\-option\fR is specified, returns a dictionary of the pane option values. If one \fI\-option\fR is specified, returns the value of that \fIoption\fR. Otherwise, sets the \fI\-option\fRs to the corresponding \fIvalue\fRs. .\" METHOD: panes .TP \fIpathname \fBpanes\fR . Returns the list of all windows managed by the widget, in the index order of their associated panes. .\" METHOD: sashpos .TP \fIpathname \fBsashpos \fIindex\fR ?\fInewpos\fR? . If \fInewpos\fR is specified, sets the position of sash number \fIindex\fR. May adjust the positions of adjacent sashes to ensure that positions are monotonically increasing. Sash positions are further constrained to be between 0 and the total size of the widget. .\" Full story: "total size" is either the -height (resp -width), .\" or the actual window height (resp actual window width), .\" depending on which changed most recently. Returns the new position of sash number \fIindex\fR. .\" Full story: new position may be different than the requested position. .SH "VIRTUAL EVENTS" .PP The panedwindow widget generates an \fB<>\fR virtual event on LeaveNotify/NotifyInferior events. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::panedwindow\fP is \fBTPanedwindow\fP. The sash has a class name of \fBSash\fP. .PP \fBTPanedwindow\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .PP \fBSash\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-bordercolor\fP \fIcolor\fP .br \fB\-gripsize\fP \fIsize\fP (number of screen units) .br \fB\-handlepad\fP \fIamount\fP .br \fB\-handlesize\fP \fIamount\fP .br \fB\-lightcolor\fP \fIcolor\fP .br \fB\-sashpad\fP \fIamount\fP .br \fB\-sashrelief\fP \fIrelief\fP .br \fB\-sashthickness\fP \fIamount\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), ttk::notebook(n), panedwindow(n) '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_progressbar.n0000644001000000100000000001005315105057705021205 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2005 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::progressbar n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::progressbar \- Provide progress feedback .SH SYNOPSIS \fBttk::progressbar\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP A \fBttk::progressbar\fR widget shows the status of a long-running operation. They can operate in two modes: \fIdeterminate\fR mode shows the amount completed relative to the total amount of work to be done, and \fIindeterminate\fR mode provides an animated display to let the user know that something is happening. .PP If the value of \fB\-orient\fR is \fBhorizontal\fR a text string can be displayed inside the progressbar. This string can be configured using the \fB\-anchor\fR, \fB\-font\fR, \fB\-foreground\fR, \fB\-justify\fR, \fB\-text\fR and \fB\-wraplength\fR options. If the value of \fB\-orient\fR is \fBvertical\fR then these options are ignored. .SO ttk_widget \-anchor \-class \-cursor \-font \-foreground \-justify \-style \-takefocus \-text \-wraplength .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-length length Length Specifies the length of the long axis of the progress bar (width if horizontal, height if vertical). The value may have any of the forms acceptable to \fBTk_GetPixels\fR. .OP \-maximum maximum Maximum A floating point number specifying the maximum \fB\-value\fR. Defaults to 100. .OP \-mode mode Mode One of \fBdeterminate\fR or \fBindeterminate\fR. .OP \-orient orient Orient One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the progress bar. .OP \-phase phase Phase Read-only option. The widget periodically increments the value of this option whenever the \fB\-value\fR is greater than 0 and, in \fIdeterminate\fR mode, less than \fB\-maximum\fR. This option may be used by the current theme to provide additional animation effects. .OP \-value value Value The current value of the progress bar. In \fIdeterminate\fR mode, this represents the amount of work completed. In \fIindeterminate\fR mode, it is interpreted modulo \fB\-maximum\fR; that is, the progress bar completes one .QW cycle when the \fB\-value\fR increases by \fB\-maximum\fR. If \fB\-variable\fR is set to an existing variable, specifying \fB\-value\fR has no effect (the variable value takes precedence). .OP \-variable variable Variable The name of a global Tcl variable which is linked to the \fB\-value\fR. If specified to an existing variable, the \fB\-value\fR of the progress bar is automatically set to the value of the variable whenever the latter is modified. .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR commands (see \fBttk::widget\fR), progressbar widgets support the following additional commands: .\" METHOD: start .TP \fIpathName \fBstart\fR ?\fIinterval\fR? . Begin autoincrement mode: schedules a recurring timer event that calls \fBstep\fR every \fIinterval\fR milliseconds. If omitted, \fIinterval\fR defaults to 50 milliseconds (20 steps/second). .\" METHOD: step .TP \fIpathName \fBstep\fR ?\fIamount\fR? . Increments the \fB\-value\fR by \fIamount\fR. \fIamount\fR defaults to 1.0 if omitted. .\" METHOD: stop .TP \fIpathName \fBstop\fR . Stop autoincrement mode: cancels any recurring timer event initiated by \fIpathName \fBstart\fR. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::progressbar\fP is \fBTProgressbar\fP. .PP \fBTProgressbar\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-bordercolor\fP \fIcolor\fP .br \fB\-darkcolor\fP \fIcolor\fP .br \fB\-lightcolor\fP \fIcolor\fP .br \fB\-maxphase\fP .RS For the aqua theme. .RE \fB\-period\fP .RS For the aqua theme. .RE \fB\-troughcolor\fP \fIcolor\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n) '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_radiobutton.n0000644001000000100000000000624215105057705021213 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::radiobutton n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::radiobutton \- Mutually exclusive option widget .SH SYNOPSIS \fBttk::radiobutton\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP \fBttk::radiobutton\fR widgets are used in groups to show or change a set of mutually-exclusive options. Radiobuttons are linked to a Tcl variable, and have an associated value; when a radiobutton is clicked, it sets the variable to its associated value. .SO ttk_widget \-class \-compound \-cursor \-image \-state \-style \-takefocus \-text \-textvariable \-underline \-width .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command A Tcl script to evaluate whenever the widget is invoked. .OP \-value Value Value The value to store in the associated \fB\-variable\fR when the widget is selected. .OP \-variable variable Variable The name of a global variable whose value is linked to the widget. Default value is \fB::selectedButton\fR. .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR commands (see \fBttk::widget\fR), radiobutton widgets support the following additional commands: .\" METHOD: invoke .TP \fIpathname\fB invoke\fR . Sets the \fB\-variable\fR to the \fB\-value\fR, selects the widget, and evaluates the associated \fB\-command\fR. Returns the result of the \fB\-command\fR, or the empty string if no \fB\-command\fR is specified. .\" Missing: select, deselect. Useful? .\" Missing: flash. This is definitely not useful. .SH "WIDGET STATES" .PP The widget does not respond to user input if the \fBdisabled\fR state is set. The widget sets the \fBselected\fR state whenever the linked \fB\-variable\fR is set to the widget's \fB\-value\fR, and clears it otherwise. The widget sets the \fBalternate\fR state whenever the linked \fB\-variable\fR is unset. (The \fBalternate\fR state may be used to indicate a .QW tri-state or .QW indeterminate selection.) .SH "STANDARD STYLES" .PP \fBTtk::radiobutton\fR widgets support the \fBToolbutton\fR style in all standard themes, which is useful for creating widgets for toolbars. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::radiobutton\fP is \fBTRadiobutton\fP. .PP Dynamic states: \fBactive\fP, \fBalternate\fP, \fBdisabled\fP, \fBpressed\fP, \fBreadonly\fP, \fBselected\fP. .PP \fBTRadiobutton\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-compound\fP \fIcompound\fP .br \fB\-foreground\fP \fIcolor\fP .br \fB\-indicatorbackground\fP \fIcolor\fP .br \fB\-indicatorcolor\fP \fIcolor\fP .br \fB\-indicatormargin\fP \fIpadding\fP .br \fB\-indicatorrelief\fP \fIrelief\fP .br \fB\-padding\fP \fIpadding\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), ttk::checkbutton(n), radiobutton(n) .SH "KEYWORDS" widget, button, option '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_scale.n0000644001000000100000000001004115105057705017740 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans.\" .\" Copyright (c) 2008 Donal Fellows .\" .\" See the file "license.terms" for information on usage and redistribution .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. .\" .TH ttk::scale n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::scale \- Create and manipulate a scale widget .SH SYNOPSIS \fBttk::scale \fIpathName \fR?\fIoptions...\fR? .BE .SH DESCRIPTION .PP A \fBttk::scale\fR widget is typically used to control the numeric value of a linked variable that varies uniformly over some range. A scale displays a \fIslider\fR that can be moved along over a \fItrough\fR, with the relative position of the slider over the trough indicating the value of the variable. .SO ttk_widget \-class \-cursor \-style \-takefocus .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command Specifies the prefix of a Tcl command to invoke whenever the scale's value is changed via a widget command. The actual command consists of this option followed by a space and a real number indicating the new value of the scale. .OP \-from from From A real value corresponding to the left or top end of the scale. .OP \-length length Length Specifies the desired long dimension of the scale in screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR). For vertical scales this is the scale's height; for horizontal scales it is the scale's width. .OP \-orient orient Orient Specifies which orientation whether the widget should be laid out horizontally or vertically. Must be either \fBhorizontal\fR or \fBvertical\fR or an abbreviation of one of these. .OP \-to to To Specifies a real value corresponding to the right or bottom end of the scale. This value may be either less than or greater than the \fB\-from\fR option. .OP \-value value Value Specifies the current floating-point value of the variable. If \fB\-variable\fR is set to an existing variable, specifying \fB\-value\fR has no effect (the variable value takes precedence). .OP \-variable variable Variable Specifies the name of a global variable to link to the scale. Whenever the value of the variable changes, the scale will update to reflect this value. Whenever the scale is manipulated interactively, the variable will be modified to reflect the scale's new value. .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR commands (see \fBttk::widget\fR), scale widgets support the following additional commands: .\" METHOD: get .TP \fIpathName \fBget \fR?\fIx y\fR? . Get the current value of the \fB\-value\fR option, or the value corresponding to the coordinates \fIx,y\fR if they are specified. \fIX\fR and \fIy\fR are pixel coordinates relative to the scale widget origin. .\" METHOD: see .TP \fIpathName \fBset \fIvalue\fR . Set the value of the widget (i.e. the \fB\-value\fR option) to \fIvalue\fR. The value will be clipped to the range given by the \fB\-from\fR and \fB\-to\fR options. Note that setting the linked variable (i.e. the variable named in the \fB\-variable\fR option) does not cause such clipping. .SH "INTERNAL COMMANDS" .PP .\" METHOD: coords .TP \fIpathName \fBcoords \fR?\fIvalue\fR? . Get the coordinates corresponding to \fIvalue\fR, or the coordinates corresponding to the current value of the \fB\-value\fR option if \fIvalue\fR is omitted. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::scale\fP is \fBTScale\fP. .PP Dynamic states: \fBactive\fP. .PP \fBTScale\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .br \fB\-borderwidth\fP \fIamount\fP .br \fB\-darkcolor\fP \fIcolor\fP .br \fB\-groovewidth\fP \fIamount\fP .br \fB\-lightcolor\fP \fIcolor\fP .br \fB\-sliderwidth\fP \fIamount\fP .br \fB\-troughcolor\fP \fIcolor\fP .br \fB\-troughrelief\fP \fIrelief\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), scale(n) .SH KEYWORDS scale, slider, trough, widget .\" Local Variables: .\" mode: nroff .\" fill-column: 78 .\" End: tk9.0.3/doc/ttk_scrollbar.n0000644001000000100000000001566615105057705020656 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::scrollbar n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::scrollbar \- Control the viewport of a scrollable widget .SH SYNOPSIS \fBttk::scrollbar\fI pathName \fR?\fIoptions...\fR? .BE .SH DESCRIPTION .PP \fBttk::scrollbar\fR widgets are typically linked to an associated window that displays a document of some sort, such as a file being edited or a drawing. A scrollbar displays a \fIthumb\fR in the middle portion of the scrollbar, whose position and size provides information about the portion of the document visible in the associated window. The thumb may be dragged by the user to control the visible region. Depending on the theme, two or more arrow buttons may also be present; these are used to scroll the visible region in discrete units. .SO ttk_widget \-class \-cursor \-style \-takefocus .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command A Tcl script prefix to evaluate to change the view in the widget associated with the scrollbar. Additional arguments are appended to the value of this option, as described in \fBSCROLLING COMMANDS\fR below, whenever the user requests a view change by manipulating the scrollbar. .RS .PP This option typically consists of a two-element list, containing the name of a scrollable widget followed by either \fBxview\fR (for horizontal scrollbars) or \fByview\fR (for vertical scrollbars). .RE .OP \-orient orient Orient One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the scrollbar. .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR commands (see \fBttk::widget\fR), scrollbar widgets support the following additional commands: .\" METHOD: get .TP \fIpathName \fBget\fR . Returns the scrollbar settings in the form of a list whose elements are the arguments to the most recent \fBset\fR widget command. .\" METHOD: set .TP \fIpathName \fBset \fIfirst last\fR . This command is normally invoked by the scrollbar's associated widget from an \fB\-xscrollcommand\fR or \fB\-yscrollcommand\fR callback. Specifies the visible range to be displayed. \fIfirst\fR and \fIlast\fR are real fractions between 0 and 1. .SH "INTERNAL COMMANDS" .PP The following widget commands are used internally by the \fBTScrollbar\fP widget class bindings. .\" METHOD: delta .TP \fIpathName \fBdelta \fIdeltaX deltaY\fR . Returns a real number indicating the fractional change in the scrollbar setting that corresponds to a given change in thumb position. For example, if the scrollbar is horizontal, the result indicates how much the scrollbar setting must change to move the thumb \fIdeltaX\fR pixels to the right (\fIdeltaY\fR is ignored in this case). If the scrollbar is vertical, the result indicates how much the scrollbar setting must change to move the thumb \fIdeltaY\fR pixels down. The arguments and the result may be zero or negative. .\" METHOD: fraction .TP \fIpathName \fBfraction \fIx y\fR . Returns a real number between 0 and 1 indicating where the point given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar, where 0.0 corresponds to the top or left of the trough and 1.0 corresponds to the bottom or right. \fIX\fR and \fIy\fR are pixel coordinates relative to the scrollbar widget. If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest point in the trough is used. .SH "SCROLLING COMMANDS" .PP When the user interacts with the scrollbar, for example by dragging the thumb, the scrollbar notifies the associated widget that it must change its view. The scrollbar makes the notification by evaluating a Tcl command generated from the scrollbar's \fB\-command\fR option. The command may take any of the following forms. In each case, \fIprefix\fR is the contents of the \fB\-command\fR option, which usually has a form like \fB.t yview\fR .TP \fIprefix \fBmoveto \fIfraction\fR . \fIFraction\fR is a real number between 0 and 1. The widget should adjust its view so that the point given by \fIfraction\fR appears at the beginning of the widget. If \fIfraction\fR is 0 it refers to the beginning of the document. 1.0 refers to the end of the document, 0.333 refers to a point one-third of the way through the document, and so on. .TP \fIprefix \fBscroll \fInumber \fBpages\fR . The widget should adjust its view by \fInumber\fR pages. It is up to the widget to define the meaning of a page; typically it is slightly less than what fits in the window, so that there is a slight overlap between the old and new views. \fINumber\fR is either 1, which means the next page should become visible, or \-1, which means that the previous page should become visible. .TP \fIprefix \fBscroll \fInumber \fBunits\fR . The widget should adjust its view by \fInumber\fR units. The units are defined in whatever way makes sense for the widget, such as characters or lines in a text widget. \fINumber\fR is either 1, which means one unit should scroll off the top or left of the window, or \-1, which means that one unit should scroll off the bottom or right of the window. .SH "WIDGET STATES" .PP The scrollbar automatically sets the \fBdisabled\fR state bit. when the entire range is visible (range is 0.0 to 1.0), and clears it otherwise. It also sets the \fBactive\fR and \fBpressed\fR state flags of individual elements, based on the position and state of the mouse pointer. .SH EXAMPLE .PP .CS set f [frame .f] \fBttk::scrollbar\fR $f.hsb -orient horizontal -command [list $f.t xview] \fBttk::scrollbar\fR $f.vsb -orient vertical -command [list $f.t yview] text $f.t -xscrollcommand [list $f.hsb set] -yscrollcommand [list $f.vsb set] grid $f.t -row 0 -column 0 -sticky nsew grid $f.vsb -row 0 -column 1 -sticky nsew grid $f.hsb -row 1 -column 0 -sticky nsew grid columnconfigure $f 0 -weight 1 grid rowconfigure $f 0 -weight 1 pack $f .CE .SH "STYLING OPTIONS" .PP The class name for a \fBttk::scrollbar\fP is \fBTScrollbar\fP. .PP Dynamic states: \fBactive\fP, \fBdisabled\fP. .PP \fBTScrollbar\fP (or more specifically \fBVertical.TScrollbar\fP and \fBHorizontal.TScrollbar\fP) styling options that are configurable with \fBttk::style\fP are: .PP \fB\-arrowcolor\fP \fIcolor\fP .br \fB\-arrowsize\fP \fIamount\fP .br \fB\-background\fP \fIcolor\fP .br \fB\-bordercolor\fP \fIcolor\fP .br \fB\-darkcolor\fP \fIcolor\fP (color of the dark part of the 3D relief) .br \fB\-foreground\fP \fIcolor\fP .br \fB\-gripsize\fP \fIsize\fP (number of screen units) .br \fB\-lightcolor\fP \fIcolor\fP (color of the light part of the 3D relief) .br \fB\-troughcolor\fP \fIcolor\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), scrollbar(n) .SH KEYWORDS scrollbar, widget '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_separator.n0000644001000000100000000000243415105057705020660 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::separator n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::separator \- Separator bar .SH SYNOPSIS \fBttk::separator\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP A \fBttk::separator\fR widget displays a horizontal or vertical separator bar. .SO ttk_widget \-class \-cursor \-style \-takefocus .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-orient orient Orient One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the separator. .SH "WIDGET COMMAND" .PP Separator widgets support the standard commands \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR (see \fBttk::widget\fR). .PP .SH "STYLING OPTIONS" .PP The class name for a \fBttk::separator\fP is \fBTSeparator\fP. .PP \fBTSeparator\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n) .SH "KEYWORDS" widget, separator '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_sizegrip.n0000644001000000100000000000426715105057705020522 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2006 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::sizegrip n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::sizegrip \- Bottom-right corner resize widget .SH SYNOPSIS \fBttk::sizegrip\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP A \fBttk::sizegrip\fR widget (also known as a \fIgrow box\fR) allows the user to resize the containing toplevel window by pressing and dragging the grip. .SO ttk_widget \-class \-cursor \-style \-takefocus .SE .SH "WIDGET COMMAND" .PP Sizegrip widgets support the standard commands \fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR, \fBstate\fR and \fBstyle\fR (see \fBttk::widget\fR). .SH "PLATFORM-SPECIFIC NOTES" .PP On macOS, toplevel windows automatically include a built-in size grip by default. Adding a \fBttk::sizegrip\fR there is harmless, since the built-in grip will just mask the widget. .SH EXAMPLES .PP Using pack: .CS pack [ttk::frame $top.statusbar] -side bottom -fill x pack [\fBttk::sizegrip\fR $top.statusbar.grip] -side right -anchor se .CE .PP Using grid: .CS grid [\fBttk::sizegrip\fR $top.statusbar.grip] \e -row $lastRow -column $lastColumn -sticky se # ... optional: add vertical scrollbar in $lastColumn, # ... optional: add horizontal scrollbar in $lastRow .CE .SH "BUGS" .PP If the containing toplevel's position was specified relative to the right or bottom of the screen (e.g., .QW "\fBwm geometry ... \fIw\fBx\fIh\fB\-\fIx\fB\-\fIy\fR" instead of .QW "\fBwm geometry ... \fIw\fBx\fIh\fB+\fIx\fB+\fIy\fR" ), the sizegrip widget will not resize the window. .PP \fBttk::sizegrip\fR widgets only support .QW southeast resizing. .SH "STYLING OPTIONS" .PP The class name for a \fBttk::sizegrip\fP is \fBTSizegrip\fP. .PP \fBTSizegrip\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-background\fP \fIcolor\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n) .SH "KEYWORDS" widget, sizegrip, grow box '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_spinbox.n0000644001000000100000000001057615105057705020350 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2008 Pat Thoyts '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::spinbox n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::spinbox \- Selecting text field widget .SH SYNOPSIS \fBttk::spinbox\fI pathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP A \fBttk::spinbox\fR widget is a \fBttk::entry\fR widget with built-in up and down buttons that are used to either modify a numeric value or to select among a set of values. The widget implements all the features of the \fBttk::entry\fR widget including support of the \fB\-textvariable\fR option to link the value displayed by the widget to a Tcl variable. .SO ttk_widget \-class \-cursor \-state \-style \-takefocus \-xscrollcommand \-placeholder \-placeholderforeground .SE .SO ttk_entry \-validate \-validatecommand .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command Specifies a Tcl command to be invoked whenever a spinbutton is invoked. .OP \-format format Format Specifies an alternate format to use when setting the string value when using the \fB\-from\fR and \fB\-to\fR range. This must be a format specifier of the form \fB%.f\fR, as it will format a floating-point number. .OP \-from from From A floating-point value specifying the lowest value for the spinbox. This is used in conjunction with \fB\-to\fR and \fB\-increment\fR to set a numerical range. .OP \-increment increment Increment A floating-point value specifying the change in value to be applied each time one of the widget spin buttons is pressed. The up button applies a positive increment, the down button applies a negative increment. .OP \-to to To A floating-point value specifying the highest permissible value for the widget. See also \fB\-from\fR and \fB\-increment\fR. range. .OP \-values values Values This must be a Tcl list of values. If this option is set then this will override any range set using the \fB\-from\fR, \fB\-to\fR and \fB\-increment\fR options. The widget will instead use the values specified beginning with the first value. .OP \-wrap wrap Wrap Must be a proper boolean value. If on, the spinbox will wrap around the values of data in the widget. .SH "INDICES" .PP See the \fBttk::entry\fR manual for information about indexing characters. .SH "VALIDATION" .PP See the \fBttk::entry\fR manual for information about using the \fB\-validate\fR and \fB\-validatecommand\fR options. .SH "WIDGET COMMAND" .PP The following subcommands are possible for spinbox widgets in addition to the commands described for the \fBttk::entry\fR widget: .\" METHOD: get .TP \fIpathName \fBget\fR . Returns the spinbox's current value. .\" METHOD: set .TP \fIpathName \fBset \fIvalue\fR . Set the spinbox string to \fIvalue\fR. If a \fB\-format\fR option has been configured then this format will be applied. If formatting fails or is not set or the \fB\-values\fR option has been used then the value is set directly. .SH "VIRTUAL EVENTS" .PP The spinbox widget generates a \fB<>\fR virtual event when the user presses , and a \fB<>\fR virtual event when the user presses . .SH "STYLING OPTIONS" .PP The class name for a \fBttk::spinbox\fP is \fBTSpinbox\fP. .PP Dynamic states: \fBactive\fP, \fBdisabled\fP, \fBfocus\fP, \fBreadonly\fP. .PP \fBTSpinbox\fP styling options configurable with \fBttk::style\fP are: .PP \fB\-arrowcolor\fP \fIcolor\fP .br \fB\-arrowsize\fP \fIamount\fP .br \fB\-background\fP \fIcolor\fP .RS For backwards compatibility, when using the aqua theme (for macOS), this option behaves as an alias for the \fB\-fieldbackground\fP provided that no value is specified for \fB\-fieldbackground\fP. Otherwise it is ignored. .RE \fB\-bordercolor\fP \fIcolor\fP .br \fB\-darkcolor\fP \fIcolor\fP .br \fB\-fieldbackground\fP \fIcolor\fP .br \fB\-foreground\fP \fIcolor\fP .br \fB\-insertcolor\fP \fIcolor\fP .br \fB\-insertwidth\fP \fIamount\fP .br \fB\-lightcolor\fP \fIcolor\fP .br \fB\-padding\fP \fIpadding\fP .br \fB\-placeholderforeground\fP \fIcolor\fP .br \fB\-selectbackground\fP \fIcolor\fP .br \fB\-selectforeground\fP \fIcolor\fP .PP Some options are only available for specific themes. .PP See the \fBttk::style\fP manual page for information on how to configure ttk styles. .SH "SEE ALSO" ttk::widget(n), ttk::entry(n), spinbox(n) .SH KEYWORDS entry, spinbox, widget, text field '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_style.n0000644001000000100000000001731515105057705020024 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::style n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::style \- Manipulate style database .SH SYNOPSIS \fBttk::style\fI option\fR ?\fIargs\fR? .BE .SH NOTES .PP See also the Tcl'2004 conference presentation, available at https://tktable.sourceforge.net/tile/tile-tcl2004.pdf .SH DEFINITIONS .PP Each widget is assigned a \fIstyle\fR, which specifies the set of elements making up the widget and how they are arranged, along with dynamic and default settings for element options. By default, the style name is the same as the widget's class; this may be overridden by the \fB\-style\fR option. .PP A \fItheme\fR is a collection of elements and styles which controls the overall look and feel of an application. The .QW . style is the theme root style on which derived styles are based. .SH DESCRIPTION .PP The \fBttk::style\fR command takes the following arguments: .\" METHOD: configure .TP \fBttk::style configure \fIstyle\fR ?\fI\-option\fR ?\fIvalue option value...\fR? ? . Sets the default value of the specified option(s) in \fIstyle\fR. If \fIstyle\fR does not exist, it is created. If only \fIstyle\fR and \fI\-option\fR are specified, get the default value for option \fI\-option\fR of style \fIstyle\fR. If only \fIstyle\fR is specified, get the default value for all options of style \fIstyle\fR. .\" METHOD: element .TP \fBttk::style element\fI args\fR .RS .TP \fBttk::style element create\fI elementName type\fR ?\fIargs...\fR? . Creates a new element in the current theme of type \fItype\fR. The only cross-platform built-in element type is \fIimage\fR (see \fBttk_image\fR(n)) but themes may define other element types (see \fBTtk_RegisterElementFactory\fR). On suitable versions of Windows an element factory is registered to create Windows theme elements (see \fBttk_vsapi\fR(n)). .TP \fBttk::style element names\fR . Returns the list of elements defined in the current theme. .TP \fBttk::style element options \fIelement\fR . Returns the list of \fIelement\fR's options. .RE .\" METHOD: layout .TP \fBttk::style layout \fIstyle\fR ?\fIlayoutSpec\fR? . Define the widget layout for style \fIstyle\fR. See \fBLAYOUTS\fR below for the format of \fIlayoutSpec\fR. If \fIlayoutSpec\fR is omitted, return the layout specification for style \fIstyle\fR. .\" METHOD: lookup .TP \fBttk::style lookup \fIstyle \-option \fR?\fIstate \fR?\fIdefault\fR?? . Returns the value specified for \fI\-option\fR in style \fIstyle\fR in state \fIstate\fR, using the standard lookup rules for element options. \fIstate\fR is a list of state names; if omitted, it defaults to all bits off (the .QW normal state). If the \fIdefault\fR argument is present, it is used as a fallback value in case no specification for \fI\-option\fR is found. .\" Otherwise -- signal error? return empty string? Leave unspecified for now. If \fIstyle\fR does not exist, it is created. .\" METHOD: map .TP \fBttk::style map \fIstyle\fR ?\fI\-option\fB { \fIstatespec value...\fB }\fR? . Sets dynamic (state dependent) values of the specified option(s) in \fIstyle\fR. Each \fIstatespec / value\fR pair is examined in order; the value corresponding to the first matching \fIstatespec\fR is used. If \fIstyle\fR does not exist, it is created. If only \fIstyle\fR and \fI\-option\fR are specified, get the dynamic values for option \fI\-option\fR of style \fIstyle\fR. If only \fIstyle\fR is specified, get the dynamic values for all options of style \fIstyle\fR. .\" METHOD: theme .TP \fBttk::style theme\fI args\fR .RS .TP \fBttk::style theme create\fI themeName\fR ?\fB\-parent \fIbasedon\fR? ?\fB\-settings \fIscript...\fR ? . Creates a new theme. It is an error if \fIthemeName\fR already exists. If \fB\-parent\fR is specified, the new theme will inherit styles, elements, and layouts from the parent theme \fIbasedon\fR. If \fB\-settings\fR is present, \fIscript\fR is evaluated in the context of the new theme as per \fBttk::style theme settings\fR. .TP \fBttk::style theme names\fR . Returns a list of all known themes. .TP \fBttk::style theme settings \fIthemeName script\fR . Temporarily sets the current theme to \fIthemeName\fR, evaluate \fIscript\fR, then restore the previous theme. Typically \fIscript\fR simply defines styles and elements, though arbitrary Tcl code may appear. .TP \fBttk::style theme styles\fR ?\fIthemeName\fR? . Returns a list of all styles in \fIthemeName\fR. If \fIthemeName\fR is omitted, the current theme is used. .TP \fBttk::style theme use\fR ?\fIthemeName\fR? . Without an argument the result is the name of the current theme. Otherwise this command sets the current theme to \fIthemeName\fR, and refreshes all widgets. .RE .SH LAYOUTS .PP A \fIlayout\fR specifies a list of elements, each followed by one or more options specifying how to arrange the element. The layout mechanism uses a simplified version of the \fBpack\fR geometry manager: given an initial cavity, each element is allocated a parcel. Then the parcel actually used by the element is adjusted within the allocated parcel. Valid options are: .\" -border should remain undocumented for now (dubious usefulness) .\" .TP .\" \fB\-border\fI boolean\fR .\" . .\" Specifies whether the element is drawn after its children. Defaults to 0. .\" OPTION: -children .TP \fB\-children { \fIsublayout...\fB }\fR . Specifies a list of elements to place inside the element. .\" OPTION: -expand .TP \fB\-expand\fI boolean\fR . Specifies whether the allocated parcel is the entire cavity. If so, simultaneous specification of \fB\-side\fR is ignored. Defaults to 0. .\" OPTION: -side .TP \fB\-side \fIside\fR . Specifies which side of the cavity to place the element; one of \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. For instance, \fB\-side top\fR allocates the parcel along the top of the cavity having width and height respectively the width of the cavity and the height of the element. If omitted, the allocated parcel is the entire cavity (same effect as \fB\-expand\fR 1). .\" OPTION: -sticky .TP \fB\-sticky\fR \fB[\fInswe\fB]\fR . Specifies the actual parcel position and size inside the allocated parcel. If specified as an empty string then the actual parcel is centered in the allocated parcel. Default is \fBnswe\fR. .\" -unit should remain undocumented for now (dubious usefulness) .\" .TP .\" \fB\-unit\fI boolean\fR .\" . .\" Specifies whether the element propagates its state to its children. .\" Defaults to 0. .PP For example: .CS ttk::style layout Horizontal.TScrollbar { Scrollbar.trough -children { Scrollbar.leftarrow -side left Scrollbar.rightarrow -side right Horizontal.Scrollbar.thumb -side left -sticky ew } } .CE .SH ROOT STYLE .PP The .QW . theme root style can be configured like any other style, providing defaults for its derived styles. In addition to the usual options, .QW . styling options configurable with \fBttk::style\fP are: .PP \fB\-insertofftime\fP \fIamount\fP .RS Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain .QW off in each blink cycle. If this option is zero then the cursor does not blink: it is on all the time. Defaults to 300 ms, unless overriden with a \fBRESOURCE_MANAGER\fR property or \fB.Xdefaults\fR file. .RE .PP \fB\-insertontime\fP \fIamount\fP .RS Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain .QW on in each blink cycle. Defaults to 600 ms, unless overriden with a \fBRESOURCE_MANAGER\fR property or \fB.Xdefaults\fR file. .RE .SH "SEE ALSO" ttk::intro(n), ttk::widget(n), photo(n), ttk_image(n) .SH KEYWORDS style, theme, appearance '\" Local Variables: '\" mode: nroff '\" End: tk9.0.3/doc/ttk_Theme.30000644001000000100000000000174615076161062017633 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2003 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH Ttk_CreateTheme 3 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME Ttk_CreateTheme, Ttk_GetTheme, Ttk_GetDefaultTheme, Ttk_GetCurrentTheme \- create and use Tk themes. .SH SYNOPSIS .nf Ttk_Theme Ttk_CreateTheme(\fIinterp\fR, \fIname\fR, \fIparentTheme\fR); Ttk_Theme Ttk_GetTheme(\fIinterp\fR, \fIname\fR); Ttk_Theme Ttk_GetDefaultTheme(\fIinterp\fR); Ttk_Theme Ttk_GetCurrentTheme(\fIinterp\fR); .fi .SH ARGUMENTS .AP "Tcl_Interp *" interp in The Tcl interpreter in which to register/query available themes. .AP "Ttk_Theme" parentTheme in Fallback or parent theme from which the new theme will inherit elements and layouts. .AP "const char *" name in The name of the theme. .BE .SH DESCRIPTION .\" TODO - Document these functions better! .SH "SEE ALSO" Ttk_RegisterLayout, Ttk_BuildLayout .\" .SH KEYWORDS tk9.0.3/doc/ttk_treeview.n0000644001000000100000000006333615105057705020522 0ustar ICTAD+Jan.NijtmansICTAD+Jan.Nijtmans'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::treeview n 8.5 Tk "Tk Themed Widget" .so man.macros .BS .SH NAME ttk::treeview \- hierarchical multicolumn data display widget .SH SYNOPSIS \fBttk::treeview \fIpathname \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP The \fBttk::treeview\fR widget displays a hierarchical collection of items. Each item has a textual label, an optional image, and an optional list of data values. The data values are displayed in successive columns after the tree label. .PP The order in which data values are displayed may be controlled by setting the \fB\-displaycolumns\fR widget option. The tree widget can also display column headings. Columns may be accessed by number or by symbolic names listed in the \fB\-columns\fR widget option; see \fBCOLUMN IDENTIFIERS\fR. .PP Each item is identified by a unique name. The widget will generate item IDs if they are not supplied by the caller. There is a distinguished root item, named \fB{}\fR. The root item itself is not displayed; its children appear at the top level of the hierarchy. .PP Each item also has a list of \fItags\fR, which can be used to associate event bindings with individual items and control the appearance of the item. .\" .PP .\" @@@HERE: describe selection, focus item .PP Treeview widgets support horizontal and vertical scrolling with the standard \fB\-\fR[\fBxy\fR]\fBscrollcommand\fR options and [\fBxy\fR]\fBview\fR widget commands. .SO ttk_widget \-class \-cursor \-takefocus \-style \-xscrollcommand \-yscrollcommand \-padding .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-columns columns Columns A list of column identifiers, specifying the number of columns and their names. .\"X: This is a read-only option; it may only be set when the widget is created. .OP \-displaycolumns displayColumns DisplayColumns A list of column identifiers (either symbolic names or integer indices) specifying which data columns are displayed and the order in which they appear, or the string \fB#all\fP. If set to \fB#all\fP (the default), all columns are shown in the order given. .OP \-height height Height Specifies the number of rows which should be visible. Note that the requested width is determined from the sum of the column widths. .OP \-selectmode selectMode SelectMode Controls how the built-in class bindings manage the selection. One of \fBextended\fR, \fBbrowse\fR, or \fBnone\fR. .RS .PP If set to \fBextended\fR (the default), multiple items may be selected. If \fBbrowse\fR, only a single item will be selected at a time. If \fBnone\fR, the selection will not be changed. .PP Note that application code and tag bindings can set the selection however they wish, regardless of the value of \fB\-selectmode\fR. .RE .OP \-selecttype selectType SelectType Controls how the built-in class bindings manage the selection. One of \fBitem\fR or \fBcell\fR. .OP \-show show Show A list containing zero or more of the following values, specifying which elements of the tree to display. .RS .IP \fBtree\fR Display tree labels in column #0. .IP \fBheadings\fR Display the heading row. .PP The default is \fBtree headings\fR. .PP \fBNOTE:\fR Column #0 always refers to the tree column, even if \fB\-show tree\fR is not specified. .RE .OP \-striped striped Striped Boolean specifying zebra striped item coloring. Note that striped items uses the \fB\-stripedbackground\fR option if set by the theme or a tag. If not supported by the current theme, it will not show. .OP \-titlecolumns titleColumns TitleColumns Number of display columns at the left that should not be scrolled. The tree column counts, even if \fB\-show tree\fR is not specified. Thus for value N of this option, column #N is the first one that is scrollable. Default is 0. .OP \-titleitems titleItems TitleItems Number of items at the top that should not be vertically scrolled. Default is 0. .SH "WIDGET COMMAND" .PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBinstate\fR, \fBstate\fR, \fBstyle\fR, \fBxview\fR and \fByview\fR commands (see \fBttk::widget\fR), treeview widgets support the following additional commands: .\" METHOD: bbox .TP \fIpathname \fBbbox \fIitem\fR ?\fIcolumn\fR? . Returns the bounding box (relative to the treeview widget's window) of the specified \fIitem\fR in the form \fIx y width height\fR. If the \fIitem\fR is not visible (i.e., if it is a descendant of a closed item or is vertically scrolled offscreen), returns the empty list. If \fIcolumn\fR is specified and is not hidden (by the \fB\-displaycolumns\fR option), returns the bounding box of that cell within \fIitem\fR (even if the cell is horizontally scrolled offscreen). .\" METHOD: cellselection .TP \fIpathname \fBcellselection\fR ?\fIselop arg ...\fR? . Manages cell selection. Cell selection is independent from item selection handled by the \fBselection\fR command. A cell is given by a list of two elements, item and column. For the rectangle versions of commands, the cells must be in displayed columns. Any change to \fB\-columns\fR clears the cell selection. A \fIcellList\fR argument may be a single cell or a list of cells. If \fIselop\fR is not specified, returns the list of selected cells. Otherwise, \fIselop\fR is one of the following: .RS .TP \fIpathname \fBcellselection set \fIcellList\fR . \fIcellList\fR becomes the new cell selection. .TP \fIpathname \fBcellselection set \fIfirstCell lastCell\fR . The rectangle defined becomes the new cell selection. .TP \fIpathname \fBcellselection add \fIcellList\fR . Add \fIcellList\fR to the cell selection. .TP \fIpathname \fBcellselection add \fIfirstCell lastCell\fR . The rectangle defined is added to the cell selection. .TP \fIpathname \fBcellselection remove \fIcellList\fR . Remove \fIcellList\fR from the cell selection. .TP \fIpathname \fBcellselection remove \fIfirstCell lastCell\fR . The rectangle defined is removed from the cell selection. .TP \fIpathname \fBcellselection toggle \fIcellList\fR . Toggle the cell selection state of each cell in \fIcellList\fR. If the element is partially visible, the result gives the full area of the element, including any parts that are not visible. .TP \fIpathname \fBcellselection toggle \fIfirstCell lastCell\fR . Toggle the cell selection state of each cell in the rectangle defined. .RE .\" METHOD: children .TP \fIpathname \fBchildren \fIitem\fR ?\fInewchildren\fR? . If \fInewchildren\fR is not specified, returns the list of children belonging to \fIitem\fR. .RS .PP If \fInewchildren\fR is specified, replaces \fIitem\fR's child list with \fInewchildren\fR. Items in the old child list not present in the new child list are detached from the tree. None of the items in \fInewchildren\fR may be an ancestor of \fIitem\fR. .RE .\" METHOD: column .TP \fIpathname \fBcolumn \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? . Query or modify the options for the specified \fIcolumn\fR. If no \fI\-option\fR is specified, returns a dictionary of option/value pairs. If a single \fI\-option\fR is specified, returns the value of that option. Otherwise, the options are updated with the specified values. The following options may be set on each column: .RS .\" OPTION: -id .TP \fB\-id \fIname\fR . The column name. This is a read-only option. For example, [\fI$pathname \fBcolumn #\fIn \fB\-id\fR] returns the data column associated with display column \fIn\fR. The tree column has \fB\-id #0\fR. .\" OPTION: -anchor .TP \fB\-anchor \fIanchor\fR . Specifies how the text in this column should be aligned with respect to the cell. \fIAnchor\fR is one of \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. .\" OPTION: -minwidth .TP \fB\-minwidth \fIminwidth\fR . The minimum width of the column in pixels. The treeview widget will not make the column any smaller than \fB\-minwidth\fR when the widget is resized or the user drags a heading column separator. Default is 20 pixels. .\" OPTION: -separator .TP \fB\-separator \fIboolean\fR . Specifies whether or not a column separator should be drawn to the right of the column. Default is false. .\" OPTION: -stretch .TP \fB\-stretch \fIboolean\fR . Specifies whether or not the column width should be adjusted when the widget is resized or the user drags a heading column separator. \fIBoolean\fR may have any of the forms accepted by \fBTcl_GetBoolean\fR. By default columns are stretchable. .\" OPTION: -width .TP \fB\-width \fIwidth\fR . The width of the column in pixels. Default is 200 pixels. The specified column width may be changed by Tk in order to honor \fB\-stretch\fR and/or \fB\-minwidth\fR, or when the widget is resized or the user drags a heading column separator. .PP Use \fIpathname fBcolumn #0\fR to configure the tree column. .RE .\" METHOD: delete .TP \fIpathname \fBdelete \fIitemList\fR . Deletes each of the items in \fIitemList\fR and all of their descendants. The root item may not be deleted. See also: \fBdetach\fR. .\" METHOD: detach .TP \fIpathname \fBdetach \fIitemList\fR . Unlinks all of the specified items in \fIitemList\fR from the tree. The items and all of their descendants are still present and may be reinserted at another point in the tree with the \fBmove\fR operation, but will not be displayed until that is done. The root item may not be detached. See also: \fBdelete\fR. .\" METHOD: detached .TP \fIpathname \fBdetached \fR?\fIitem\fR? . If \fIitem\fR is provided, returns a boolean value indicating whether it is the name of a detached item (see \fBdetach\fR). Otherwise, returns a list of all the detached items (in an arbitrary order). The root item is never detached. .\" METHOD: exists .TP \fIpathname \fBexists \fIitem\fR . Returns 1 if the specified \fIitem\fR is present in the tree, 0 otherwise. .\" METHOD: focus .TP \fIpathname \fBfocus \fR?\fIitem\fR? . If \fIitem\fR is specified, sets the focus item to \fIitem\fR. Otherwise, returns the current focus item, or \fB{}\fR if there is none. .\" Need: way to clear the focus item. {} works for this... .\" .\" METHOD: heading .TP \fIpathname \fBheading \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? . Query or modify the heading options for the specified \fIcolumn\fR. Valid options are: .RS .\" OPTION: -text .TP \fB\-text \fItext\fR . The text to display in the column heading. .\" OPTION: -image .TP \fB\-image \fIimageName\fR . Specifies an image to display to the right of the column heading. .\" OPTION: -anchor .TP \fB\-anchor \fIanchor\fR . Specifies how the heading text should be aligned. One of the standard Tk anchor values. .\" OPTION: -command .TP \fB\-command \fIscript\fR . A script to evaluate when the heading label is pressed. .PP Use \fIpathname heading #0\fR to configure the tree column heading. .RE .\" METHOD: identify .TP \fIpathname \fBidentify \fIcomponent x y\fR . Returns a description of the specified \fIcomponent\fR under the point given by \fIx\fR and \fIy\fR, or the empty string if no such \fIcomponent\fR is present at that position. The values \fIx\fR and \fIy\fR may have any of the forms acceptable to \fBTk_GetPixels\fR. The following subcommands are supported: .RS .TP \fIpathname \fBidentify region \fIx y\fR .RS Returns one of: .IP heading Tree heading area; use [\fBpathname identify column \fIx y\fR] to determine the heading number. .IP separator Space between two column headings; [\fBpathname identify column \fIx y\fR] will return the display column identifier of the heading to left of the separator. .IP tree The tree area. .IP cell A data cell. .RE .TP \fIpathname \fBidentify item \fIx y\fR . Returns the item ID of the item at position \fIy\fR. .TP \fIpathname \fBidentify column \fIx y\fR . Returns the display column identifier of the cell at position \fIx\fR. The tree column has ID \fB#0\fR. .TP \fIpathname \fBidentify cell \fIx y\fR . Returns the cell identifier of the cell at position \fIx y\fR. A cell identifier is a list of item ID and column ID. .TP \fIpathname \fBidentify element \fIx y\fR . The element at position \fIx,y\fR. .TP \fIpathname \fBidentify row \fIx y\fR . Obsolescent synonym for \fIpathname \fBidentify item\fR. .PP See \fBCOLUMN IDENTIFIERS\fR for a discussion of display columns and data columns. .RE .\" METHOD: index .TP \fIpathname \fBindex \fIitem\fR . Returns the integer index of \fIitem\fR within its parent's list of children. .\" METHOD: insert .TP \fIpathname \fBinsert \fIparent index\fR ?\fB\-id \fIid\fR? \fIoptions...\fR . Creates a new item. \fIparent\fR is the item ID of the parent item, or the empty string \fB{}\fR to create a new top-level item. \fIindex\fR is an integer, or the value \fBend\fR, specifying where in the list of \fIparent\fR's children to insert the new item. If \fIindex\fR is negative or zero, the new node is inserted at the beginning; if \fIindex\fR is greater than or equal to the current number of children, it is inserted at the end. If \fB\-id\fR is specified, it is used as the item identifier; \fIid\fR must not already exist in the tree. Otherwise, a new unique identifier is generated. .RS .PP \fIpathname \fBinsert\fR returns the item identifier of the newly created item. See \fBITEM OPTIONS\fR for the list of available options. .RE .\" METHOD: item .TP \fIpathname \fBitem \fIitem\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? . Query or modify the options for the specified \fIitem\fR. If no \fI\-option\fR is specified, returns a dictionary of option/value pairs. If a single \fI\-option\fR is specified, returns the value of that option. Otherwise, the item's options are updated with the specified values. See \fBITEM OPTIONS\fR for the list of available options. .\" METHOD: move .TP \fIpathname \fBmove \fIitem parent index\fR . Moves \fIitem\fR to position \fIindex\fR in \fIparent\fR's list of children. It is illegal to move an item under one of its descendants. .RS .PP If \fIindex\fR is negative or zero, \fIitem\fR is moved to the beginning; if greater than or equal to the number of children, it is moved to the end. .RE .\" METHOD: next .TP \fIpathname \fBnext \fIitem\fR . Returns the identifier of \fIitem\fR's next sibling, or \fB{}\fR if \fIitem\fR is the last child of its parent. .\" METHOD: parent .TP \fIpathname \fBparent \fIitem\fR . Returns the ID of the parent of \fIitem\fR, or \fB{}\fR if \fIitem\fR is at the top level of the hierarchy. .\" METHOD: prev .TP \fIpathname \fBprev \fIitem\fR . Returns the identifier of \fIitem\fR's previous sibling, or \fB{}\fR if \fIitem\fR is the first child of its parent. .\" METHOD: see .TP \fIpathname \fBsee \fIitem\fR . Ensure that \fIitem\fR is visible: sets all of \fIitem\fR's ancestors to \fB\-open true\fR, and scrolls the widget if necessary so that \fIitem\fR is within the visible portion of the tree. .\" METHOD: selection .TP \fIpathname \fBselection\fR ?\fIselop itemList\fR? . Manages item selection. Item selection is independent from cell selection handled by the \fBcellselection\fR command. If \fIselop\fR is not specified, returns the list of selected items. Otherwise, \fIselop\fR is one of the following: .RS .TP \fIpathname \fBselection set \fIitemList\fR . \fIitemList\fR becomes the new selection. .TP \fIpathname \fBselection add \fIitemList\fR . Add \fIitemList\fR to the selection. .TP \fIpathname \fBselection remove \fIitemList\fR . Remove \fIitemList\fR from the selection. .TP \fIpathname \fBselection toggle \fIitemList\fR . Toggle the selection state of each item in \fIitemList\fR. .RE .\" METHOD: set .TP \fIpathname \fBset \fIitem\fR ?\fIcolumn\fR? ?\fIvalue\fR? . With one argument, returns a dictionary of column/value pairs for the specified \fIitem\fR. With two arguments, returns the current value of the specified \fIcolumn\fR. With three arguments, sets the value of column \fIcolumn\fR in item \fIitem\fR to the specified \fIvalue\fR. See also \fBCOLUMN IDENTIFIERS\fR. .\" METHOD: tag .TP \fIpathName \fBtag \fIargs...\fR . Manages tags. Tags can be set on items as well as on cells. The set of tags is shared between items and cells. However item tagging is independent from cell tagging (for instance adding a tag on an item does not also add this tag on the cells in that item). Cell tags take precedence over item tags when drawing. The following subcommands are supported: .RS .TP \fIpathName \fBtag add \fItag items\fR . Adds the specified \fItag\fR to each of the listed \fIitems\fR. If \fItag\fR is already present for a particular item, then the \fB\-tags\fR for that item are unchanged. .TP \fIpathName \fBtag bind \fItagName \fR?\fIsequence\fR? ?\fIscript\fR? . Add a Tk binding script for the event sequence \fIsequence\fR to the tag \fItagName\fR. When an X event is delivered to an item, binding scripts for each of the item's \fB\-tags\fR are evaluated in order as per \fIbindtags(n)\fR. If the event can be associated with a cell (i.e. mouse events) any bindings for the cell's \fB\-tags\fR are evaluated as well. .RS .PP \fB\fR, \fB\fR, and virtual events are sent to the focus item. \fB