Tk Source Code

Changes On Branch core-8-branch
Login
EuroTcl/OpenACS 11 - 12 JULY 2024, VIENNA

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Changes In Branch core-8-branch Excluding Merge-Ins

This is equivalent to a diff from 32adda38dc to 7d39f7c239

2024-06-20
16:02
Improvements in the proc ::tk::ScrollByPixels. Leaf check-in: 21b0a3801b user: csaba tags: trunk, main
15:59
Improvements in the proc ::tk::ScrollByPixels. Leaf check-in: 7d39f7c239 user: csaba tags: core-8-branch
2024-06-19
18:56
TTK_STATE_USER1 -> TTK_STATE_FIRST in win/ttkWinXPTheme.c. check-in: f0795d80f4 user: csaba tags: core-8-branch
2024-06-03
06:09
Fix [e64820c1de]: The -justify configure option is duplicated for ttk::label check-in: c57ea83e71 user: fvogel tags: trunk, main
2024-06-02
13:59
Fix [e64820c1de]: The -justify configure option is duplicated for ttk::label Closed-Leaf check-in: ca68e2948e user: fvogel tags: bug-e64820c1de
07:15
Fix [0fb337ea84]: ttk::combobox selection overruns downarrow element. Thanks to Emiliano Gavilan. check-in: 32adda38dc user: fvogel tags: trunk, main
07:15
Fix [0fb337ea84]: ttk::combobox selection overruns downarrow element. Thanks to Emiliano Gavilan. check-in: ceab69adfa user: fvogel tags: core-8-6-branch
2024-05-29
20:16
Merge-mark check-in: 045281bc1e user: jan.nijtmans tags: trunk, main

Changes to .github/workflows/linux-build.yml.

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.6
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV







|







35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.6
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV







|







139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV

Deleted .github/workflows/linux-with-tcl8-build.yml.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
name: Linux (with Tcl 8.7)
on:
  push:
    branches:
    - "main"
    - "core-8-branch"
    - "core-8-6-branch"
    tags:
    - "core-**"
permissions:
  contents: read
defaults:
  run:
    shell: bash
    working-directory: tk/unix
env:
  ERROR_ON_FAILURES: 1
jobs:
  build:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
          - "clang"
        cfgopt:
          - ""
          - "CFLAGS=-DTK_NO_DEPRECATED=1"
          - "--disable-shared"
          - "--disable-xft"
          - "--disable-xss"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
          echo "TOOL_DIR=$(cd tcl/tools;pwd)" >> $GITHUB_ENV
          echo "BUILD_CONFIG_ID=$OPTS" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
          OPTS: ${{ matrix.compiler }}${{ matrix.cfgopt }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure (opts=${{ matrix.cfgopt }})
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Build Test Harness
        run: |
          make tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Test-Drive Installation
        run: |
          make install || {
            echo "::error::Failure during Install"
            exit 1
          }
      - name: Create Distribution Package
        run: |
          make dist || {
            echo "::error::Failure during Distribute"
            exit 1
          }
      - name: Convert Documentation to HTML
        run: |
          make html-tk TOOL_DIR=$TOOL_DIR || {
            echo "::error::Failure during Distribute"
            exit 1
          }
  test:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
        cfgopt:
          - ""
          - "--disable-xft"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure ${{ matrix.cfgopt }}
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Run Tests
        run: |
          xvfb-run --auto-servernum make test-classic | tee out-classic.txt
          xvfb-run --auto-servernum make test-ttk | tee out-ttk.txt
          grep -q "Failed	0" out-classic.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
          grep -q "Failed	0" out-ttk.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
        timeout-minutes: 15
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<




































































































































































































































































































































































Added .github/workflows/linux-with-tcl86-build.yml.



































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
name: Linux (with Tcl 8.6)
on:
  push:
    branches:
    - "main"
    - "core-8-branch"
    - "core-8-6-branch"
    tags:
    - "core-**"
permissions:
  contents: read
defaults:
  run:
    shell: bash
    working-directory: tk/unix
env:
  ERROR_ON_FAILURES: 1
jobs:
  build:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
          - "clang"
        cfgopt:
          - ""
          - "CFLAGS=-DTK_NO_DEPRECATED=1"
          - "--disable-xft"
          - "--disable-xss"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-6-branch
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
          echo "TOOL_DIR=$(cd tcl/tools;pwd)" >> $GITHUB_ENV
          echo "BUILD_CONFIG_ID=$OPTS" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
          OPTS: ${{ matrix.compiler }}${{ matrix.cfgopt }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure (opts=${{ matrix.cfgopt }})
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH --disable-zipfs "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Build Test Harness
        run: |
          make tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Test-Drive Installation
        run: |
          make install || {
            echo "::error::Failure during Install"
            exit 1
          }
      - name: Create Distribution Package
        run: |
          make dist || {
            echo "::error::Failure during Distribute"
            exit 1
          }
      - name: Convert Documentation to HTML
        run: |
          make html-tk TOOL_DIR=$TOOL_DIR || {
            echo "::error::Failure during Distribute"
            exit 1
          }
  test:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
        cfgopt:
          - ""
          - "--disable-xft"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-6-branch
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure ${{ matrix.cfgopt }}
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Run Tests
        run: |
          xvfb-run --auto-servernum make test-classic | tee out-classic.txt
          xvfb-run --auto-servernum make test-ttk | tee out-ttk.txt
          grep -q "Failed	0" out-classic.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
          grep -q "Failed	0" out-ttk.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
        timeout-minutes: 15

Added .github/workflows/linux-with-tcl9-build.yml.



































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
name: Linux (with Tcl 9.0)
on:
  push:
    branches:
    - "main"
    - "core-8-branch"
    - "core-8-6-branch"
    tags:
    - "core-**"
permissions:
  contents: read
defaults:
  run:
    shell: bash
    working-directory: tk/unix
env:
  ERROR_ON_FAILURES: 1
jobs:
  build:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
          - "clang"
        cfgopt:
          - ""
          - "CFLAGS=-DTK_NO_DEPRECATED=1"
          - "--disable-xft"
          - "--disable-xss"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
          echo "TOOL_DIR=$(cd tcl/tools;pwd)" >> $GITHUB_ENV
          echo "BUILD_CONFIG_ID=$OPTS" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
          OPTS: ${{ matrix.compiler }}${{ matrix.cfgopt }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure (opts=${{ matrix.cfgopt }})
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Build Test Harness
        run: |
          make tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Test-Drive Installation
        run: |
          make install || {
            echo "::error::Failure during Install"
            exit 1
          }
      - name: Create Distribution Package
        run: |
          make dist || {
            echo "::error::Failure during Distribute"
            exit 1
          }
      - name: Convert Documentation to HTML
        run: |
          make html-tk TOOL_DIR=$TOOL_DIR || {
            echo "::error::Failure during Distribute"
            exit 1
          }
  test:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
        cfgopt:
          - ""
          - "--disable-xft"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure ${{ matrix.cfgopt }}
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Run Tests
        run: |
          xvfb-run --auto-servernum make test-classic | tee out-classic.txt
          xvfb-run --auto-servernum make test-ttk | tee out-ttk.txt
          grep -q "Failed	0" out-classic.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
          grep -q "Failed	0" out-ttk.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
        timeout-minutes: 15

Deleted .github/workflows/linux-with-tcl91-build.yml.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
name: Linux (with Tcl 9.1)
on:
  push:
    branches:
    - "main"
    - "core-8-branch"
    - "core-8-6-branch"
    tags:
    - "core-**"
permissions:
  contents: read
defaults:
  run:
    shell: bash
    working-directory: tk/unix
env:
  ERROR_ON_FAILURES: 1
jobs:
  build:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
          - "clang"
        cfgopt:
          - ""
          - "CFLAGS=-DTK_NO_DEPRECATED=1"
          - "--disable-shared"
          - "--disable-xft"
          - "--disable-xss"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: tip-626
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
          echo "TOOL_DIR=$(cd tcl/tools;pwd)" >> $GITHUB_ENV
          echo "BUILD_CONFIG_ID=$OPTS" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
          OPTS: ${{ matrix.compiler }}${{ matrix.cfgopt }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure (opts=${{ matrix.cfgopt }})
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Build Test Harness
        run: |
          make tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Test-Drive Installation
        run: |
          make install || {
            echo "::error::Failure during Install"
            exit 1
          }
      - name: Create Distribution Package
        run: |
          make dist || {
            echo "::error::Failure during Distribute"
            exit 1
          }
      - name: Convert Documentation to HTML
        run: |
          make html-tk TOOL_DIR=$TOOL_DIR || {
            echo "::error::Failure during Distribute"
            exit 1
          }
  test:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
        cfgopt:
          - ""
          - "--disable-xft"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: tip-626
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure ${{ matrix.cfgopt }}
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Run Tests
        run: |
          xvfb-run --auto-servernum make test-classic | tee out-classic.txt
          xvfb-run --auto-servernum make test-ttk | tee out-ttk.txt
          grep -q "Failed	0" out-classic.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
          grep -q "Failed	0" out-ttk.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
        timeout-minutes: 15
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<




































































































































































































































































































































































Changes to .github/workflows/mac-build.yml.

19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
        shell: bash
        working-directory: tk/macosx
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Check out Tcl 9.0
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          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







|



|







19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
        shell: bash
        working-directory: tk/macosx
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Prepare checked out repositories
        run: |
          touch tk/generic/tkStubInit.c
          mkdir build
          echo "BUILD_DIR=`cd build && pwd`" >> $GITHUB_ENV
          echo "DESTDIR=`cd build && pwd`" >> $GITHUB_ENV
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
        shell: bash
        working-directory: tk/unix
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Check out Tcl 9.0
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          path: tcl
      - name: Prepare checked out repositories
        env:
          SET_DISPLAY: ${{ contains(matrix.options, '--disable-aqua') }}
        run: |
          touch tkStubInit.c
          mkdir "$HOME/install dir"







|



|







71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
        shell: bash
        working-directory: tk/unix
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Prepare checked out repositories
        env:
          SET_DISPLAY: ${{ contains(matrix.options, '--disable-aqua') }}
        run: |
          touch tkStubInit.c
          mkdir "$HOME/install dir"

Changes to .github/workflows/onefiledist.yml.

20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
      CC: gcc
      CFGOPT: --disable-symbols --disable-shared
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 9.0
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          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







|



|







20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
      CC: gcc
      CFGOPT: --disable-symbols --disable-shared
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.7
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Setup Environment
        run: |
          sudo apt-get install libxss-dev libxft-dev
          touch tcl/generic/tclStubInit.c tcl/generic/tclOOStubInit.c
          touch tk/generic/tkStubInit.c
          echo "INST_DIR=$(cd install;pwd)" >> $GITHUB_ENV
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
      - 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@v4







|







54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
      - name: Build & Install Tk
        run: |
          make binaries libraries install
        working-directory: tk/unix
        # TODO: need the Tk version separately for distro naming below
      - name: Package
        run: |
          cp bin/wish8.7 ${BUILD_NAME}
          chmod +x ${BUILD_NAME}
          tar -cf ${BUILD_NAME}.tar ${BUILD_NAME}
        working-directory: ${{ env.INST_DIR }}
        env:
          BUILD_NAME: wish${{ env.TCL_PATCHLEVEL }}_snapshot
      - name: Upload
        uses: actions/upload-artifact@v4
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
      CC: gcc
      CFGOPT: --disable-symbols --disable-shared
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 9.0
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          path: tcl
      - name: Checkout create-dmg
        uses: actions/checkout@v4
        with:
          repository: create-dmg/create-dmg
          ref: v1.0.8
          path: create-dmg







|



|







84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
      CC: gcc
      CFGOPT: --disable-symbols --disable-shared
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.7
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Checkout create-dmg
        uses: actions/checkout@v4
        with:
          repository: create-dmg/create-dmg
          ref: v1.0.8
          path: create-dmg
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
        with:
          msystem: MINGW64
          install: git mingw-w64-x86_64-toolchain make zip
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 9.0
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          path: tcl
      - name: Setup Environment
        run: |
          mkdir -p install/combined
          touch tcl/generic/tclStubInit.c tcl/generic/tclOOStubInit.c
          touch tk/generic/tkStubInit.c
          echo "INST_DIR=$(cd install;pwd)" >> $GITHUB_ENV







|



|







172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
        with:
          msystem: MINGW64
          install: git mingw-w64-x86_64-toolchain make zip
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.7
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Setup Environment
        run: |
          mkdir -p install/combined
          touch tcl/generic/tclStubInit.c tcl/generic/tclOOStubInit.c
          touch tk/generic/tkStubInit.c
          echo "INST_DIR=$(cd install;pwd)" >> $GITHUB_ENV

Changes to .github/workflows/win-build.yml.

20
21
22
23
24
25
26

27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
        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@v4
        with:
          path: tk
      - name: Checkout Tcl 9.0
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          path: tcl
      - name: Init MSVC
        uses: ilammy/msvc-dev-cmd@v1
      - name: Make Install Location
        working-directory: tcl
        run: |
          echo "TCLDIR=`pwd`" >> $GITHUB_ENV







>






|



|







20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
        working-directory: tk/win
    # Using powershell means we need to explicitly stop on failure
    strategy:
      matrix:
        config:
          - ""
          - "OPTS=symbols"
          - "OPTS=symbols STATS=compdbg,memdbg"
          - "OPTS=static"
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.7
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Init MSVC
        uses: ilammy/msvc-dev-cmd@v1
      - name: Make Install Location
        working-directory: tcl
        run: |
          echo "TCLDIR=`pwd`" >> $GITHUB_ENV
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
      - name: Install MSYS2
        uses: msys2/setup-msys2@v2
        with:
          msystem: MINGW64
          install: git mingw-w64-x86_64-toolchain make zip
      - name: Checkout Tk
        uses: actions/checkout@v4
      - name: Checkout Tcl 9.0
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          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







|



|







117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
      - name: Install MSYS2
        uses: msys2/setup-msys2@v2
        with:
          msystem: MINGW64
          install: git mingw-w64-x86_64-toolchain make zip
      - name: Checkout Tk
        uses: actions/checkout@v4
      - name: Checkout Tcl 8.7
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Prepare
        run: |
          touch tkStubInit.c
          touch "${HOME}/forWinDialog-5.12.7"
          mkdir "${HOME}/install_dir"
          echo "INSTALL_DIR=${HOME}/install_dir" >> $GITHUB_ENV

Changes to .project.

1
2
3
4
5
6
7
8
9
10
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
	<name>tk9.0</name>
	<comment></comment>
	<projects>
	</projects>
	<buildSpec>
	</buildSpec>
	<natures>
	</natures>


|







1
2
3
4
5
6
7
8
9
10
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
	<name>tk8.7</name>
	<comment></comment>
	<projects>
	</projects>
	<buildSpec>
	</buildSpec>
	<natures>
	</natures>

Changes to README.md.

1
2
3
4
5
6
7
8
9
10
# README:  Tk

This is the **Tk 9.0b3** source distribution.

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

8.6 (production release, daily build)
[![Build Status](https://github.com/tcltk/tk/workflows/Linux/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tk/actions?query=workflow%3A%22Linux%22+branch%3Acore-8-6-branch)
[![Build Status](https://github.com/tcltk/tk/workflows/Windows/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tk/actions?query=workflow%3A%22Windows%22+branch%3Acore-8-6-branch)


|







1
2
3
4
5
6
7
8
9
10
# README:  Tk

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

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

8.6 (production release, daily build)
[![Build Status](https://github.com/tcltk/tk/workflows/Linux/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tk/actions?query=workflow%3A%22Linux%22+branch%3Acore-8-6-branch)
[![Build Status](https://github.com/tcltk/tk/workflows/Windows/badge.svg?branch=core-8-6-branch)](https://github.com/tcltk/tk/actions?query=workflow%3A%22Windows%22+branch%3Acore-8-6-branch)
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

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

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

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

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







|







21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

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

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

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

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

Changes to changes.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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.0b3 arises from the check-in with tag core-9-0-b3.

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.10 or later






|

|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

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

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

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

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

Changes to doc/3DBorder.3.

9
10
11
12
13
14
15
16
17
18
19

20
21

22
23
24
25
26

27
28
29
30
31

32
33

34
35

36
37

38
39

40
41

42
43

44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
.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 <tk.h>\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).







|

|

>
|

>
|


|

>
|


|

>
|

>
|

>
|

>
|

>
|

>
|

>
|


|


|


|

|

|
<







9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

68
69
70
71
72
73
74
.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 <tk.h>\fR
.sp
Tk_3DBorder
\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR
.sp
void
\fBTk_ClipDrawableToRect(\fIdisplay, drawable, x, y, width, height\fB)\fR
.sp
void
\fBTk_DrawHighlightBorder(\fItkwin, fgGC, bgGC, highlightWidth, drawable\fB)\fR
.sp
Tk_3DBorder
\fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR
.sp
void
\fBTk_Get3DBorderColors(\fIborder, bgColorPtr, darkColorPtr, lightColorPtr\fB)\fR
.sp
Tk_3DBorder
\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR
.sp
void
\fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
.sp
void
\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
.sp
void
\fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
.sp
void
\fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
.sp
void
\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR
.sp
void
\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR
.sp
void
\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR
.sp
const char *
\fBTk_NameOf3DBorder(\fIborder\fB)\fR
.sp
XColor *
\fBTk_3DBorderColor(\fIborder\fB)\fR
.sp
GC *
\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR
.sp
\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR
.sp
\fBTk_Free3DBorder(\fIborder\fB)\fR

.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).
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
.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.







|
<







96
97
98
99
100
101
102
103

104
105
106
107
108
109
110
.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.
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
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







|
<

|
<







143
144
145
146
147
148
149
150

151
152

153
154
155
156
157
158
159
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
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
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 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







|
<
<
|
|
<

|
|







176
177
178
179
180
181
182
183


184
185

186
187
188
189
190
191
192
193
194
195
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 d to the given rectangle. If width or height are negative, reset to no clipping.


Subsequent drawing into d 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 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
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
\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







|
|







222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
\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
318
319
320
321
322
323
324
325
326
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







|
<
321
322
323
324
325
326
327
328

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

Changes to doc/AddOption.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
\fB#include <tk.h>\fR
.sp
void
\fBTk_AddOption\fR(\fItkwin, name, value, priority\fR)
.sp
Tcl_Obj *
\fBTk_GetSystemDefault\fR(\fItkwin, dbName, className\fR)
.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.







<







12
13
14
15
16
17
18

19
20
21
22
23
24
25
\fB#include <tk.h>\fR
.sp
void
\fBTk_AddOption\fR(\fItkwin, name, value, priority\fR)
.sp
Tcl_Obj *
\fBTk_GetSystemDefault\fR(\fItkwin, dbName, className\fR)

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

Changes to doc/BindTable.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
.SH NAME
Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_BindingTable
\fBTk_CreateBindingTable\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







|

|


|


|


|

|

|

|
<







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

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

.SH ARGUMENTS
.AS Tk_BindingTable bindingTable
.AP Tcl_Interp *interp in
Interpreter to use when invoking bindings in binding table.  Also
used for returning results and errors from binding procedures.
.AP Tk_BindingTable bindingTable in
Token for binding table;  must have been returned by some previous
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
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







|







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

Changes to doc/CanvPsY.3.

25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
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







<

|







25
26
27
28
29
30
31

32
33
34
35
36
37
38
39
40
int
\fBTk_CanvasPsFont\fR(\fIinterp, canvas, tkFont\fR)
.sp
\fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR)
.sp
int
\fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR)

.SH ARGUMENTS
.AS int "numPoints"
.AP Tk_Canvas canvas in
A token that identifies a canvas widget for which Postscript is
being generated.
.AP double canvasY in
Y-coordinate in the space of the canvas.
.AP Tcl_Interp *interp in/out
A Tcl interpreter;  Postscript is appended to its result, or the
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
.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







|







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

Changes to doc/CanvTkwin.3.

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
\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







<







26
27
28
29
30
31
32

33
34
35
36
37
38
39
\fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR)
.sp
\fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR)
.sp
Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR;
.sp
Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR;

.SH ARGUMENTS
.AS Tk_ItemType *drawableXPtr
.AP Tk_Canvas canvas in
A token that identifies a canvas widget.
.AP Tcl_Interp *interp in/out
Interpreter to use for error reporting.
.AP "const char" *string in
146
147
148
149
150
151
152
153
154
155
156
157
158
159
.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







|






145
146
147
148
149
150
151
152
153
154
155
156
157
158
.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

Changes to doc/CanvTxtInfo.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
Tk_CanvasTextInfo \- additional information for managing text items in canvases
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_CanvasTextInfo *
\fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR)
.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;
    int \fIselectFirst\fR;
    int \fIselectLast\fR;
    Tk_Item *\fIanchorItemPtr\fR;







<
















|







11
12
13
14
15
16
17

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
Tk_CanvasTextInfo \- additional information for managing text items in canvases
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_CanvasTextInfo *
\fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR)

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

Changes to doc/Clipboard.3.

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
\fB#include <tk.h>\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







<







15
16
17
18
19
20
21

22
23
24
25
26
27
28
\fB#include <tk.h>\fR
.sp
int
\fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR)
.sp
int
\fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR)

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

Changes to doc/ClrSelect.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.SH NAME
Tk_ClearSelection \- Deselect a selection
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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.







<







11
12
13
14
15
16
17

18
19
20
21
22
23
24
.SH NAME
Tk_ClearSelection \- Deselect a selection
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_ClearSelection\fR(\fItkwin, selection\fR)

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

Changes to doc/ConfigWidg.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
.SH NAME
Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_ConfigureWidget\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.







|


|


|

|
<









|
|
|







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
.SH NAME
Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR
.sp
int
\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
.sp
int
\fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
.sp
\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR

.SH ARGUMENTS
.AS void *widgRec in/out
.AP Tcl_Interp *interp in
Interpreter to use for returning error messages.
.AP Tk_Window tkwin in
Window used to represent widget (needed to set up X resources).
.AP "const Tk_ConfigSpec" *specs in
Pointer to table specifying legal configuration options for this
widget.
.AP int argc in
Number of arguments in \fIargv\fR.
.AP "const char" **argv in
Command-line options for configuring widget.
.AP char *widgRec in/out
Points to widget record structure.  Fields in this structure get
modified by \fBTk_ConfigureWidget\fR to hold configuration information.
.AP int flags in
If non-zero, then it specifies an OR-ed combination of flags that
control the processing of configuration information.
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
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







|
|











|





|
|

|







58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
options.
.AP Display *display in
Display containing widget whose record is being freed;  needed in
order to free up resources.
.BE
.SH DESCRIPTION
.PP
Note: \fBTk_ConfigureWidget\fR should be replaced with the new
\fBTcl_Obj\fR based API \fBTk_SetOptions\fR.  The old interface is
retained for backward compatibility.
.PP
\fBTk_ConfigureWidget\fR is called to configure various aspects of a
widget, such as colors, fonts, border width, etc.
It is intended as a convenience procedure to reduce the amount
of code that must be written in individual widget managers to
handle configuration information.
It is typically
invoked when widgets are created, and again when the \fBconfigure\fR
command is invoked for a widget.
Although intended primarily for widgets, \fBTk_ConfigureWidget\fR
can be used in other situations where \fIargc-argv\fR information
is to be used to fill in a record structure, such as configuring
graphical elements for a canvas widget or entries of a menu.
.PP
\fBTk_ConfigureWidget\fR processes
a table specifying the configuration options that are supported
(\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and
\fIargv\fR) to fill in fields of a record (\fIwidgRec\fR).
It uses the option database and defaults specified in \fIspecs\fR
to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR.
\fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this
case it does not modify \fIinterp\fR.
If an error
occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will
leave an error message in interpreter \fIinterp\fR's result in the standard Tcl
fashion.
In the event of an error return, some of the fields of \fIwidgRec\fR
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
(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







|




|







|






|








|







116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
(e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for
an integer value).  The \fItype\fR field indicates how to use the
value of the option (more on this below).
The \fIargvName\fR field is a string such as
.QW \-font
or
.QW \-bg ,
which is compared with the values in \fIargv\fR (if \fIargvName\fR is
NULL it means this is a grouped entry;  see \fBGROUPED ENTRIES\fR below).  The
\fIdbName\fR and \fIdbClass\fR fields are used to look up a value
for this option in the option database.  The \fIdefValue\fR field
specifies a default value for this configuration option if no
value is specified in either \fIargv\fR or the option database.
\fIOffset\fR indicates where in \fIwidgRec\fR to store information
about this option, and \fIspecFlags\fR contains additional information
to control the processing of this configuration option (see FLAGS
below).
The last field, \fIcustomPtr\fR, is only used if \fItype\fR is
\fBTK_CONFIG_CUSTOM\fR;  see CUSTOM OPTION TYPES below.
.PP
\fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which
(if any) configuration options are specified there.  \fIArgv\fR
must contain an even number of fields;  the first of each pair
of fields must match the \fIargvName\fR of some entry in \fIspecs\fR
(unique abbreviations are acceptable),
and the second field of the pair contains the value for that
configuration option.  If there are entries in \fIspec\fR for which
there were no matching entries in \fIargv\fR,
\fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR
fields of the \fIspecs\fR entry to probe the option database;  if
a value is found, then it is used as the value for the option.
Finally, if no entry is found in the option database, the
\fIdefValue\fR field of the \fIspecs\fR entry is used as the
value for the configuration option.  If the \fIdefValue\fR is
NULL, or if the \fBTK_CONFIG_DONT_SET_DEFAULT\fR bit is set in
\fIflags\fR, then there is no default value and this \fIspecs\fR entry
will be ignored if no value is specified in \fIargv\fR or the
option database.
.PP
Once a string value has been determined for a configuration option,
\fBTk_ConfigureWidget\fR translates the string value into a more useful
form, such as a color if \fItype\fR is \fBTK_CONFIG_COLOR\fR or an integer
if \fItype\fR is \fBTK_CONFIG_INT\fR.  This value is then stored in the
record pointed to by \fIwidgRec\fR.  This record is assumed to
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344

345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
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







<














<






<










<



















<










<








<










<




<






<






<





<










<










<








<







<






<






<






<
>
|








<

|




|
|






<







<







167
168
169
170
171
172
173

174
175
176
177
178
179
180
181
182
183
184
185
186
187

188
189
190
191
192
193

194
195
196
197
198
199
200
201
202
203

204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222

223
224
225
226
227
228
229
230
231
232

233
234
235
236
237
238
239
240

241
242
243
244
245
246
247
248
249
250

251
252
253
254

255
256
257
258
259
260

261
262
263
264
265
266

267
268
269
270
271

272
273
274
275
276
277
278
279
280
281

282
283
284
285
286
287
288
289
290
291

292
293
294
295
296
297
298
299

300
301
302
303
304
305
306

307
308
309
310
311
312

313
314
315
316
317
318

319
320
321
322
323
324

325
326
327
328
329
330
331
332
333
334

335
336
337
338
339
340
341
342
343
344
345
346
347
348

349
350
351
352
353
354
355

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The value must be a window path name.  It is translated to a
\fBTk_Window\fR token and the token is stored in the target.
.SH "GROUPED ENTRIES"
.PP
In some cases it is useful to generate multiple resources from
a single configuration value.  For example, a color name might
be used both to generate the background color for a widget (using
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457








458
459
460
461
462
463
464
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







|
<


|










<





<





<













<










>
>
>
>
>
>
>
>







377
378
379
380
381
382
383
384

385
386
387
388
389
390
391
392
393
394
395
396
397

398
399
400
401
402

403
404
405
406
407

408
409
410
411
412
413
414
415
416
417
418
419
420

421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used
in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR
to provide additional control over the processing of configuration
options.  These values are used in three different ways as
described below.
.PP
First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has
the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0),

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

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

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

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

If this bit is one, it means that the \fIdefValue\fR field of the
entry should only be used for returning the default value in
\fBTk_ConfigureInfo\fR.
In calls to \fBTk_ConfigureWidget\fR no default will be supplied
for entries with this flag set;  it is assumed that the
caller has already supplied a default value in the target location.
This flag provides a performance optimization where it is expensive
to process the default string:  the client can compute the default
once, save the value, and provide it before calling
\fBTk_ConfigureWidget\fR.
.TP
\fBTK_CONFIG_OPTION_SPECIFIED\fR
This bit is
deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR
so that callers could detect what entries were specified in
\fIargv\fR, but it was removed because it was inherently
thread-unsafe. Code that wishes to detect what options were specified
should use \fBTk_SetOptions\fR instead.
.PP
The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically
used to specify different default values for
monochrome and color displays.  This is done by creating two
entries in \fIspecs\fR that are identical except for their
\fIdefValue\fR and \fIspecFlags\fR fields.  One entry should have
the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
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,
        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.







|











|





|







529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
corresponding field of the widget record to null.
.SH "CUSTOM OPTION TYPES"
.PP
Applications can extend the built-in configuration types with additional
configuration types by writing procedures to parse and print options
of the a type and creating a structure pointing to those procedures:
.CS
typedef struct Tk_CustomOption {
    Tk_OptionParseProc *\fIparseProc\fR;
    Tk_OptionPrintProc *\fIprintProc\fR;
    void *\fIclientData\fR;
} \fBTk_CustomOption\fR;

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

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

Changes to doc/ConfigWind.3.

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
\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.







<







35
36
37
38
39
40
41

42
43
44
45
46
47
48
\fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR)
.sp
\fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR)
.sp
\fBTk_DefineCursor\fR(\fItkwin, cursor\fR)
.sp
\fBTk_UndefineCursor\fR(\fItkwin\fR)

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

Changes to doc/CoordToWin.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Tk_CoordsToWindow \- Find window containing a point
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Window
\fBTk_CoordsToWindow\fR(\fIrootX, rootY, tkwin\fR)
.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







<







12
13
14
15
16
17
18

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

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

Changes to doc/CrtCmHdlr.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







<







12
13
14
15
16
17
18

19
20
21
22
23
24
25
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateClientMessageHandler\fR(\fIproc\fR)
.sp
\fBTk_DeleteClientMessageHandler\fR(\fIproc\fR)

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

Changes to doc/CrtConsoleChan.3.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
.SH NAME
Tk_InitConsoleChannels \- Install the console channels as standard channels
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_InitConsoleChannels\fR(\fIinterp\fR)
.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







<







10
11
12
13
14
15
16

17
18
19
20
21
22
23
.SH NAME
Tk_InitConsoleChannels \- Install the console channels as standard channels
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_InitConsoleChannels\fR(\fIinterp\fR)

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

Changes to doc/CrtErrHdlr.3.

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
.nf
\fB#include <tk.h>\fR
.sp
Tk_ErrorHandler
\fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR)
.sp
\fBTk_DeleteErrorHandler\fR(\fIhandler\fR)
.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.







<







14
15
16
17
18
19
20

21
22
23
24
25
26
27
.nf
\fB#include <tk.h>\fR
.sp
Tk_ErrorHandler
\fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR)
.sp
\fBTk_DeleteErrorHandler\fR(\fIhandler\fR)

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

Changes to doc/CrtGenHdlr.3.

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







<







13
14
15
16
17
18
19

20
21
22
23
24
25
26
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateGenericHandler\fR(\fIproc, clientData\fR)
.sp
\fBTk_DeleteGenericHandler\fR(\fIproc, clientData\fR)

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

Changes to doc/CrtImgType.3.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

22
23
24
25
26
27
28
29
30
31
32
33
34
35


36
37
38
39
40
41
42
'\"
'\" 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 <tk.h>\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











|








|
>














>
>







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures"
.so man.macros
.BS
.SH NAME
Tk_CreateImageType, Tk_GetImageModelData, Tk_InitImageArgs \- define new kind of image
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateImageType\fR(\fItypePtr\fR)
.sp
void *
\fBTk_GetImageModelData\fR(\fIinterp, name, typePtrPtr\fR)
.sp
\fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR)
.SH ARGUMENTS
.AS "const Tk_ImageType" *typePtrPtr
.AP "const Tk_ImageType" *typePtr in
Structure that defines the new type of image.
For Tk 8.4 and earlier this must be static: a
pointer to this structure is retained by the image code.
In Tk 8.5, this limitation was relaxed.
.AP Tcl_Interp *interp in
Interpreter in which image was created.
.AP "const char" *name in
Name of existing image.
.AP Tk_ImageType **typePtrPtr out
Points to word in which to store a pointer to type information for
the given image, if it exists.
.AP int argc in
Number of arguments
.AP char ***argvPtr in/out
Pointer to argument list
.BE
.SH DESCRIPTION
.PP
\fBTk_CreateImageType\fR is invoked to define a new kind of image.
An image type corresponds to a particular value of the \fItype\fR
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
\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;







|







54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
\fIimage manager\fR.
It consists of a collection of procedures plus three different
kinds of data structures.
The first data structure is a Tk_ImageType structure, which contains
the name of the image type and pointers to five procedures provided
by the image manager to deal with images of this type:
.CS
typedef struct Tk_ImageType {
    const char *\fIname\fR;
    Tk_ImageCreateProc *\fIcreateProc\fR;
    Tk_ImageGetProc *\fIgetProc\fR;
    Tk_ImageDisplayProc *\fIdisplayProc\fR;
    Tk_ImageFreeProc *\fIfreeProc\fR;
    Tk_ImageDeleteProc *\fIdeleteProc\fR;
} \fBTk_ImageType\fR;
234
235
236
237
238
239
240




































241
242
243
244
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







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




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

Changes to doc/CrtItemType.3.

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
.nf
\fB#include <tk.h>\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







<




<







13
14
15
16
17
18
19

20
21
22
23

24
25
26
27
28
29
30
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateItemType\fR(\fItypePtr\fR)
.sp
Tk_ItemType *
\fBTk_GetItemTypes\fR()

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

.BE
.SH INTRODUCTION
.PP
\fBTk_CreateItemType\fR is invoked to define a new kind of canvas item
described by the \fItypePtr\fR argument.
An item type corresponds to a particular value of the \fItype\fR
argument to the \fBcreate\fR widget command for canvases, and
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
    size_t \fIitemSize\fR;
    Tk_ItemCreateProc *\fIcreateProc\fR;
    const Tk_ConfigSpec *\fIconfigSpecs\fR;
    Tk_ItemConfigureProc *\fIconfigProc\fR;
    Tk_ItemCoordProc *\fIcoordProc\fR;
    Tk_ItemDeleteProc *\fIdeleteProc\fR;
    Tk_ItemDisplayProc *\fIdisplayProc\fR;
    int \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 "8.7, TIP164"
    Tk_ItemRotateProc *\fIrotateProc\fR;
.VE "8.7, TIP164"
} \fBTk_ItemType\fR;
.CE
.PP
The fields of a Tk_ItemType structure are described in more detail







|










|







67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
    size_t \fIitemSize\fR;
    Tk_ItemCreateProc *\fIcreateProc\fR;
    const Tk_ConfigSpec *\fIconfigSpecs\fR;
    Tk_ItemConfigureProc *\fIconfigProc\fR;
    Tk_ItemCoordProc *\fIcoordProc\fR;
    Tk_ItemDeleteProc *\fIdeleteProc\fR;
    Tk_ItemDisplayProc *\fIdisplayProc\fR;
    int \fIalwaysRedraw\fR;
    Tk_ItemPointProc *\fIpointProc\fR;
    Tk_ItemAreaProc *\fIareaProc\fR;
    Tk_ItemPostscriptProc *\fIpostscriptProc\fR;
    Tk_ItemScaleProc *\fIscaleProc\fR;
    Tk_ItemTranslateProc *\fItranslateProc\fR;
    Tk_ItemIndexProc *\fIindexProc\fR;
    Tk_ItemCursorProc *\fIicursorProc\fR;
    Tk_ItemSelectionProc *\fIselectionProc\fR;
    Tk_ItemInsertProc *\fIinsertProc\fR;
    Tk_ItemDCharsProc *\fIdCharsProc\fR;
    Tk_ItemType *\fInextPtr\fR;
.VS "8.7, TIP164"
    Tk_ItemRotateProc *\fIrotateProc\fR;
.VE "8.7, TIP164"
} \fBTk_ItemType\fR;
.CE
.PP
The fields of a Tk_ItemType structure are described in more detail
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
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;







|







109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
defined by Tk via the type Tk_Item; the rest of the item
record is defined by the type manager.
A type manager must define its item records with a Tk_Item as
the first field.
For example, the item record for bitmap items is defined as follows:
.PP
.CS
typedef struct BitmapItem {
    Tk_Item \fIheader\fR;
    double \fIx\fR, \fIy\fR;
    Tk_Anchor \fIanchor\fR;
    Pixmap \fIbitmap\fR;
    XColor *\fIfgColor\fR;
    XColor *\fIbgColor\fR;
    GC \fIgc\fR;
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183








184
185
186
187
188
189
190
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.







|









>
>
>
>
>
>
>
>







165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
Once \fBTk_CreateImageType\fR returns, this name may be used
in \fBcreate\fR widget commands to create items of the new
type.
If there already existed an item type by this name then
the new item type replaces the old one.
.SS "FLAGS (IN ALWAYSREDRAW)"
.PP
The \fItypePtr\->alwaysRedraw\fR field (so named for historic reasons)
contains a collection of flag bits that modify how the canvas core interacts
with the item. The following bits are defined:
.TP
\fBTK_ALWAYS_REDRAW\fR
.
Indicates that the item should always be redrawn when any part of the canvas
is redrawn, rather than only when the bounding box of the item overlaps the
area being redrawn. This is used by window items, for example, which need to
unmap subwindows that are not on the screen.
.TP
\fBTK_CONFIG_OBJS\fR
.
Indicates that operations which would otherwise take a string (or array of
strings) actually take a Tcl_Obj reference (or an array of such references).
The operations to which this applies are the \fIconfigProc\fR, the
\fIcoordProc\fR, the \fIcreateProc\fR, the \fIindexProc\fR and the
\fIinsertProc\fR.
.TP
\fBTK_MOVABLE_POINTS\fR
.VS 8.6
Indicates that the item supports the \fIdCharsProc\fR, \fIindexProc\fR and
\fIinsertProc\fR with the same semantics as Tk's built-in line and polygon
types, and that hence individual coordinate points can be moved. Must not be
set if any of the above methods is NULL.
219
220
221
222
223
224
225



226
227
228
229
230
231
232
\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







>
>
>







225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
\fIitemPtr\fR is a pointer to a newly-allocated item of
size \fItypePtr\->itemSize\fR.
Tk has already initialized the item's header (the first
\fBsizeof(Tk_ItemType)\fR bytes).
The \fIobjc\fR and \fIobjv\fR arguments describe all of the
arguments to the \fBcreate\fR command after the \fItype\fR
argument.
Note that if \fBTK_CONFIG_OBJS\fR is not set in the
\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
contain a pointer to an array of constant strings.
For example, in the widget command:
.PP
.CS
\fB\&.c create rectangle 10 20 50 50 \-fill black\fR
.CE
.PP
\fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
\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.







<
|







257
258
259
260
261
262
263

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

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



280
281
282
283
284
285
286
        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







>
>
>







281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
        int \fIflags\fR);
.CE
.PP
The \fIinterp\fR argument identifies the interpreter in which the
widget command was invoked, \fIcanvas\fR is a handle for the canvas
widget, and \fIitemPtr\fR is a pointer to the item being configured.
\fIobjc\fR and \fIobjv\fR contain the configuration options.
Note that if \fBTK_CONFIG_OBJS\fR is not set in the
\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
contain a pointer to an array of constant strings.
For example, if the following command is invoked:
.PP
.CS
\fB\&.c itemconfigure 2 \-fill red \-outline black\fR
.CE
.PP
\fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR
309
310
311
312
313
314
315



316
317
318
319
320
321
322
        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







>
>
>







320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
        int \fIobjc\fR,
        Tcl_Obj *const \fIobjv\fR[]);
.CE
.PP
The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
all have the standard meanings, and \fIobjc\fR and \fIobjv\fR
describe the coordinate arguments.
Note that if \fBTK_CONFIG_OBJS\fR is not set in the
\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
contain a pointer to an array of constant strings.
For example, if the following widget command is invoked:
.PP
.CS
\fB\&.c coords 2 30 90\fR
.CE
.PP
\fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
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







|

|







397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
will not necessarily be the same as those in the canvas.
\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR
to transform coordinates from those of the canvas to those
of \fIdst\fR.
.PP
Normally an item's \fIdisplayProc\fR is only invoked if the item
overlaps the area being displayed.
However, if bit zero of \fItypePtr\->alwaysRedraw\fR is 1,
(i.e.\|
.QW "\fItypePtr\->alwaysRedraw & 1 == 1\fR" )
then \fIdisplayProc\fR is invoked during every redisplay operation,
even if the item does not overlap the area of redisplay; this is useful for
cases such as window items, where the subwindow needs to be unmapped when it
is off the screen.
.SS POINTPROC
.PP
\fItypePtr\->pointProc\fR is invoked by Tk to find out how close
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
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.







|
|







573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
the item is to be rotated, and \fIangleRad\fR gives the anticlockwise
rotation to be applied in radians.
The item should adjust the coordinates of its control points so that where
they used to have coordinates \fIx\fR and \fIy\fR, they will have new
coordinates \fIx\(fm\fR and \fIy\(fm\fR, where
.PP
.CS
\fIrelX\fR = \fIx\fR - \fIoriginX\fR
\fIrelY\fR = \fIy\fR - \fIoriginY\fR
\fIx\(fm\fR = \fIoriginX\fR + \fIrelX\fR \(mu cos(\fIangleRad\fR) + \fIrelY\fR \(mu sin(\fIangleRad\fR)
\fIy\(fm\fR = \fIoriginY\fR \(mi \fIrelX\fR \(mu sin(\fIangleRad\fR) + \fIrelY\fR \(mu cos(\fIangleRad\fR)
.CE
.PP
The control points for an item are not necessarily the coordinates provided to
the item when it is created (or via the \fItypePtr\->coordProc\fR), but could
instead be derived from them.
598
599
600
601
602
603
604



605
606
607
608
609
610
611
.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







>
>
>







612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
.CE
.PP
The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all
have the usual meaning.
\fIindexObj\fR contains a textual description of an index,
and \fIindexPtr\fR points to an integer value that should be
filled in with a numerical index.
Note that if \fBTK_CONFIG_OBJS\fR is not set in the
\fItypePtr\->alwaysRedraw\fR field, the \fIindexObj\fR parameter will
actually contain a pointer to a constant string.
It is up to the type manager to decide what forms of index
are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR,
\fBend\fR, etc.).
\fIindexProc\fR should return a Tcl completion code and set
the interpreter result in the event of an error.
.SS ICURSORPROC
.PP
681
682
683
684
685
686
687



688
689
690
691
692
693
694
.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







>
>
>







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

Changes to doc/CrtPhImgFmt.3.

54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
An image file format handler consists of a collection of procedures
plus a \fBTk_PhotoImageFormatVersion3\fR structure, which contains the
name of the image file format and pointers to six procedures provided
by the handler to deal with files and strings in this format.  The
Tk_PhotoImageFormatVersion3 structure contains the following fields:
.VS 8.7
.CS
typedef struct {
    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;







|







54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
An image file format handler consists of a collection of procedures
plus a \fBTk_PhotoImageFormatVersion3\fR structure, which contains the
name of the image file format and pointers to six procedures provided
by the handler to deal with files and strings in this format.  The
Tk_PhotoImageFormatVersion3 structure contains the following fields:
.VS 8.7
.CS
typedef struct Tk_PhotoImageFormatVersion3 {
    const char *\fIname\fR;
    Tk_ImageFileMatchProcVersion3 *\fIfileMatchProc\fR;
    Tk_ImageStringMatchProcVersion3 *\fIstringMatchProc\fR;
    Tk_ImageFileReadProcVersion3 *\fIfileReadProc\fR;
    Tk_ImageStringReadProcVersion3 *\fIstringReadProc\fR;
    Tk_ImageFileWriteProcVersion3 *\fIfileWriteProc\fR;
    Tk_ImageStringWriteProcVersion3 *\fIstringWriteProc\fR;
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
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,







|







147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
return 0.
.SS FILEREADPROC
.PP
\fIformatPtr->fileReadProc\fR provides the address of a procedure for
Tk to call to read data from an image file into a photo image.
\fIformatPtr->fileReadProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageFileReadProc\fR(
        Tcl_Interp *\fIinterp\fR,
        Tcl_Channel \fIchan\fR,
        const char *\fIfileName\fR,
        Tcl_Obj *\fIformat\fR,
        Tcl_Obj *\fImetadataIn\fR,
        PhotoHandle \fIimageHandle\fR,
        int \fIdestX\fR, int \fIdestY\fR,
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
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,







|







180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
The return value is a standard Tcl return value.
.SS STRINGREADPROC
.PP
\fIformatPtr->stringReadProc\fR provides the address of a procedure
for Tk to call to read data from a string into a photo image.
\fIformatPtr->stringReadProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageStringReadProc\fR(
        Tcl_Interp *\fIinterp\fR,
        Tcl_Obj *\fIdata\fR,
        Tcl_Obj *\fIformat\fR,
        Tcl_Obj *\fImetadataIn\fR,
        PhotoHandle \fIimageHandle\fR,
        int \fIdestX\fR, int \fIdestY\fR,
        int \fIwidth\fR, int \fIheight\fR,
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
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







|







212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
The return value is a standard Tcl return value.
.SS FILEWRITEPROC
.PP
\fIformatPtr->fileWriteProc\fR provides the address of a procedure for
Tk to call to write data from a photo image to a file.
\fIformatPtr->fileWriteProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageFileWriteProc\fR(
        Tcl_Interp *\fIinterp\fR,
        const char *\fIfileName\fR,
        Tcl_Obj *\fIformat\fR,
        Tcl_Obj *\fImetadataIn\fR,
        Tk_PhotoImageBlock *\fIblockPtr\fR);
.CE
The \fIinterp\fR argument is the interpreter in which the command was
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
.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.







|







241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
.SS STRINGWRITEPROC
.PP
\fIformatPtr->stringWriteProc\fR provides the address of a procedure
for Tk to call to translate image data from a photo image into a
string.
\fIformatPtr->stringWriteProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageStringWriteProc\fR(
        Tcl_Interp *\fIinterp\fR,
        Tcl_Obj *\fIformat\fR,
        Tcl_Obj *\fImetadataIn\fR,
        Tk_PhotoImageBlock *\fIblockPtr\fR);
.CE
The \fIinterp\fR argument is the interpreter in which the command was
invoked to convert the image; it should be used for reporting errors.
271
272
273
274
275
276
277

278
279
280
281
282
283
284
285
286
287
288
289

290
291

292
293

294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
.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.







>









|
|
|
>

|
>


>











|
<
<
<


|


|



|











|
|

|
|
|









|
<
<







271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346


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



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


.CE
.PP
The metadata keys returned by the driver are merged into the present
metadata property of the image or into the metadata dict given by the
\fB\-metadata\fR command line option.
At the script level, the command \fBimage create\fR and the
\fBconfigure\fR method may return metadata from the driver.
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
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;







|







372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
Structure that defines the new file format.
.BE
.SS DESCRIPTION
A driver using the version 2 interface invokes \fBTk_CreatePhotoImageFormat\fR
for driver registration. The Tk_PhotoImageFormat structure
contains the following fields:
.CS
typedef struct Tk_PhotoImageFormat {
    const char *\fIname\fR;
    Tk_ImageFileMatchProc *\fIfileMatchProc\fR;
    Tk_ImageStringMatchProc *\fIstringMatchProc\fR;
    Tk_ImageFileReadProc *\fIfileReadProc\fR;
    Tk_ImageStringReadProc *\fIstringReadProc\fR;
    Tk_ImageFileWriteProc *\fIfileWriteProc\fR;
    Tk_ImageStringWriteProc *\fIstringWriteProc\fR;
454
455
456
457
458
459
460







































461
462
463
464
\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







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
\fIformatPtr->stringWriteProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageStringWriteProc\fR(
        Tcl_Interp *\fIinterp\fR,
        Tcl_Obj *\fIformat\fR,
        Tk_PhotoImageBlock *\fIblockPtr\fR);
.CE
.PP
.SH "LEGACY INTERFACE SUPPORT"
.PP
In Tk 8.2 and earlier, the definition of all the function pointer
types stored in fields of a \fBTk_PhotoImageFormat\fR struct were
incompatibly different.  Legacy programs and libraries dating from
those days may still contain code that defines extended Tk photo image
formats using the old interface.  The Tk header file will still support
this legacy interface if the code is compiled with the
macro \fBUSE_OLD_IMAGE\fR defined.  Alternatively, the legacy interfaces
are used if the first character of \fIformatPtr->name\fR is an
uppercase ASCII character (\fBA\fR-\fBZ\fR), and explicit casts
are used to forgive the type mismatch.  For example,
.CS
static Tk_PhotoImageFormat myFormat = {
    "MyFormat",
    (Tk_ImageFileMatchProc *) FileMatch,
    NULL,
    (Tk_ImageFileReadProc *) FileRead,
    NULL,
    NULL,
    NULL
};
.CE
would define a minimal \fBTk_PhotoImageFormat\fR that operates provide
only file reading capability, where \fBFileMatch\fR and \fBFileRead\fR
are written according to the legacy interfaces of Tk 8.2 or earlier.
.PP
Any stub-enabled extension providing an extended photo image format
via the legacy interface enabled by the \fBUSE_OLD_IMAGE\fR macro
that is compiled against Tk 8.5 headers and linked against the
Tk 8.5 stub library will produce a file that can be loaded only
into interps with Tk 8.5 or later; that is, the normal stub-compatibility
rules.  If a developer needs to generate from such code a file
that is loadable into interps with Tk 8.4 or earlier, they must
use Tk 8.4 headers and stub libraries to do so.
.PP
Any new code written today should not make use of the legacy
interfaces.  Expect their support to go away in Tk 9.
.SH "SEE ALSO"
Tk_FindPhoto, Tk_PhotoPutBlock
.SH KEYWORDS
photo image, image file

Changes to doc/CrtSelHdlr.3.

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR)
.sp
\fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR)
.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.







<







13
14
15
16
17
18
19

20
21
22
23
24
25
26
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR)
.sp
\fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR)

.SH ARGUMENTS
.AS Tk_SelectionProc clientData
.AP Tk_Window tkwin in
Window for which \fIproc\fR will provide selection information.
.AP Atom selection in
The name of the selection for which \fIproc\fR will provide
selection information.
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
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







|

|

|







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

Changes to doc/CrtWindow.3.

22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
.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







<







22
23
24
25
26
27
28

29
30
31
32
33
34
35
.sp
Tk_Window
\fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR)
.sp
\fBTk_DestroyWindow\fR(\fItkwin\fR)
.sp
\fBTk_MakeWindowExist\fR(\fItkwin\fR)

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

Changes to doc/DeleteImg.3.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
.SH NAME
Tk_DeleteImage \- Destroy an image.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







<







10
11
12
13
14
15
16

17
18
19
20
21
22
23
.SH NAME
Tk_DeleteImage \- Destroy an image.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_DeleteImage\fR(\fIinterp, name\fR)

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

Changes to doc/DrawFocHlt.3.

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
.BS
.SH NAME
Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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.







|
<







9
10
11
12
13
14
15
16

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

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

Changes to doc/EventHndlr.3.

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
\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







<







17
18
19
20
21
22
23

24
25
26
27
28
29
30
\fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR)
.sp
\fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR)
.sp
\fBTk_GetButtonMask\fR(\fIbutton\fR)
.sp
\fBTk_SendVirtualEvent\fR(\fItkwin, eventName, detail\fR)

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

Changes to doc/FindPhoto.3.

28
29
30
31
32
33
34

35
36
37
38
39

40
41
42
43
44
45
46
47
48
49
50
51
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.







>





>




<







28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

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

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

Changes to doc/FontId.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for
fonts
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







|

|


|
<







11
12
13
14
15
16
17
18
19
20
21
22
23

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

.SH ARGUMENTS
.AS Tk_FontMetrics *dsPtr
.AP Tk_Font tkfont in
Opaque font token being queried.  Must have been returned by a previous
call to \fBTk_GetFont\fR.
.AP Tk_FontMetrics *fmPtr out
Pointer to structure in which the font metrics for \fItkfont\fR will
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
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







|







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

Added doc/FreeXId.3.





























































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

Changes to doc/GeomReq.3.

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
\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







<















|
<

|
<

|
<

|
<







17
18
19
20
21
22
23

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

40
41

42
43

44
45

46
47
48
49
50
51
52
\fBTk_GeometryRequest\fR(\fItkwin, reqWidth, reqHeight\fR)
.sp
\fBTk_SetMinimumRequestSize\fR(\fItkwin, minWidth, minHeight\fR)
.sp
\fBTk_SetInternalBorder\fR(\fItkwin, width\fR)
.sp
\fBTk_SetInternalBorderEx\fR(\fItkwin, left, right, top, bottom\fR)

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

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

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

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

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

Changes to doc/GetAnchor.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
.SH NAME
Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetAnchorFromObj\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  ,







|


|


|
<







11
12
13
14
15
16
17
18
19
20
21
22
23
24

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

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

Changes to doc/GetBitmap.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
.SH NAME
Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Pixmap
\fBTk_AllocBitmapFromObj\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.







|


|


|


|


|

|

|

|
<







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

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

.SH ARGUMENTS
.AS "unsigned long" *pixelPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting; if NULL then no error message
is left after errors.
.AP Tk_Window tkwin in
Token for window in which the bitmap will be used.
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

94
95
96
97

98
99

100
101

102
103

104
105
106

107
108

109
110
111

112
113

114
115

116
117
118
119
120

121
122

123
124

125
126

127
128

129
130

131
132

133
134

135
136

137
138

139
140

141
142

143
144

145
146

147
148

149
150

151
152
153
154
155
156
157
158
\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







<




<




>
|



>
|

>
|

>
|

>
|


>
|

>
|


>
|

>
|

>
|




>
|

>
|

>
|

>
|

>
|

>
|

>
|

>
|

>
|

>
|

>
|

>
|

>
|

>
|

>
|

>
|







76
77
78
79
80
81
82

83
84
85
86

87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
\fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap
that matches the description in \fIobjPtr\fR and is suitable for use
in \fItkwin\fR.  It re-uses an existing bitmap, if possible, and
creates a new one otherwise.  \fIObjPtr\fR's value must have one
of the following forms:
.TP 20
\fB@\fIfileName\fR

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

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







|







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

Changes to doc/GetCapStyl.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
.SH NAME
Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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 ,







|


|
<







11
12
13
14
15
16
17
18
19
20
21

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

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

Changes to doc/GetClrmap.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
.SH NAME
Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







|

|

|
<







11
12
13
14
15
16
17
18
19
20
21
22

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

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

Changes to doc/GetColor.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
.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 <tk.h>\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







|


|


|


|


|


|

|

|
<







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

38
39
40
41
42
43
44
.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 <tk.h>\fR
.sp
XColor *
\fBTk_AllocColorFromObj(\fIinterp, tkwin, objPtr\fB)\fR
.sp
XColor *
\fBTk_GetColor(\fIinterp, tkwin, name\fB)\fR
.sp
XColor *
\fBTk_GetColorFromObj(\fItkwin, objPtr\fB)\fR
.sp
XColor *
\fBTk_GetColorByValue(\fItkwin, prefPtr\fB)\fR
.sp
const char *
\fBTk_NameOfColor(\fIcolorPtr\fB)\fR
.sp
GC
\fBTk_GCForColor(\fIcolorPtr, drawable\fB)\fR
.sp
\fBTk_FreeColorFromObj(\fItkwin, objPtr\fB)\fR
.sp
\fBTk_FreeColor(\fIcolorPtr\fB)\fR

.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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
.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.







<










<







67
68
69
70
71
72
73

74
75
76
77
78
79
80
81
82
83

84
85
86
87
88
89
90
.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.

Changes to doc/GetCursor.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
.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 <tk.h>\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







|


|


|


|


|

|

|
<







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

35
36
37
38
39
40
41
.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 <tk.h>\fR
.sp
Tk_Cursor
\fBTk_AllocCursorFromObj(\fIinterp, tkwin, objPtr\fB)\fR
.sp
Tk_Cursor
\fBTk_GetCursor(\fIinterp, tkwin, name\fB)\fR
.sp
Tk_Cursor
\fBTk_GetCursorFromObj(\fItkwin, objPtr\fB)\fR
.sp
Tk_Cursor
\fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR
.sp
const char *
\fBTk_NameOfCursor(\fIdisplay, cursor\fB)\fR
.sp
\fBTk_FreeCursorFromObj(\fItkwin, objPtr\fB)\fR
.sp
\fBTk_FreeCursor(\fIdisplay, cursor\fB)\fR

.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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
\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







<







83
84
85
86
87
88
89

90
91
92
93
94
95
96
\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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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







<









<






<







111
112
113
114
115
116
117

118
119
120
121
122
123
124
125
126

127
128
129
130
131
132

133
134
135
136
137
138
139
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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
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







|







192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
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:  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

Changes to doc/GetFont.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

35
36
37
38
39
40
41
42
43
.SH NAME
Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FontGetDescription, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Font
\fBTk_AllocFontFromObj\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.







|


|


|


|


|


|

>
|
<







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

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

.SH ARGUMENTS
.AS "const char" *tkfont
.AP "Tcl_Interp" *interp in
Interpreter to use for error reporting.  If \fBNULL\fR, then no error
messages are left after errors.
.AP Tk_Window tkwin in
Token for window in which font will be used.
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
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







|
<







88
89
90
91
92
93
94
95

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

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

Changes to doc/GetGC.3.

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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.







|
<







13
14
15
16
17
18
19
20

21
22
23
24
25
26
27
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
GC
\fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR)
.sp
\fBTk_FreeGC(\fIdisplay, gc\fR)

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

Changes to doc/GetHINSTANCE.3.

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Tk_GetHINSTANCE \- retrieve the global application instance handle
.SH SYNOPSIS
.nf
\fB#include <tkPlatDecls.h>\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







<







9
10
11
12
13
14
15

16
17
18
19
20
21
22
Tk_GetHINSTANCE \- retrieve the global application instance handle
.SH SYNOPSIS
.nf
\fB#include <tkPlatDecls.h>\fR
.sp
HINSTANCE
\fBTk_GetHINSTANCE\fR()

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

Changes to doc/GetHWND.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
\fB#include <tkPlatDecls.h>\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.







<







12
13
14
15
16
17
18

19
20
21
22
23
24
25
\fB#include <tkPlatDecls.h>\fR
.sp
HWND
\fBTk_GetHWND\fR(\fIwindow\fR)
.sp
Window
\fBTk_AttachHWND\fR(\fItkwin, hwnd\fR)

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

Changes to doc/GetImage.3.

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
\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







<







18
19
20
21
22
23
24

25
26
27
28
29
30
31
\fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR)
.sp
\fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR)
.sp
\fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR)
.sp
\fBTk_FreeImage\fR(\fIimage\fR)

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

Changes to doc/GetJoinStl.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
.SH NAME
Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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 ,







|


|
<







11
12
13
14
15
16
17
18
19
20
21

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

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

Changes to doc/GetJustify.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
.SH NAME
Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetJustifyFromObj\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 ,







|


|


|
<







11
12
13
14
15
16
17
18
19
20
21
22
23
24

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

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

52
53
54

55
56
57

58
59
60
61
62
63
64
65
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,







>
|


>
|


>
|







44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
Justification style (one of the values listed below).
.BE
.SH DESCRIPTION
.PP
\fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value
corresponding to \fIobjPtr\fR's value.
This value will be one of the following:
.TP
\fBTK_JUSTIFY_LEFT\fR
Means that the text on each line should start at the left edge of
the line;  as a result, the right edges of lines may be ragged.
.TP
\fBTK_JUSTIFY_RIGHT\fR
Means that the text on each line should end at the right edge of
the line;  as a result, the left edges of lines may be ragged.
.TP
\fBTK_JUSTIFY_CENTER\fR
Means that the text on each line should be centered;  as a result,
both the left and right edges of lines may be ragged.
.PP
Under normal circumstances the return value is \fBTCL_OK\fR and
\fIinterp\fR is unused.
If \fIobjPtr\fR does not contain a valid justification style
or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned,

Changes to doc/GetOption.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Tk_GetOption \- retrieve an option from the option database
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Uid
\fBTk_GetOption\fR(\fItkwin, name, class\fR)
.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







<







12
13
14
15
16
17
18

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

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

Changes to doc/GetPixels.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
.SH NAME
Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM, Tk_GetDoublePixelsFromObj \- translate between strings and screen units
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetPixelsFromObj\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.







|


|


|


|


|
<







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

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

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

60
61

62
63

64
65

66
67

68
69
70
71
72
73
74
75
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 <none>
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







>
|

>
|

>
|

>
|

>
|







52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
the screen (\fIobjPtr\fR or \fIstring\fR) and compute the
corresponding distance either in integer pixels or floating-point millimeters.
In either case,
\fIobjPtr\fR or \fIstring\fR
specifies a screen distance as a
floating-point number followed by one of the following characters
that indicates units:
.TP
<none>
The number specifies a distance in pixels.
.TP
\fBc\fR
The number specifies a distance in centimeters on the screen.
.TP
\fBi\fR
The number specifies a distance in inches on the screen.
.TP
\fBm\fR
The number specifies a distance in millimeters on the screen.
.TP
\fBp\fR
The number specifies a distance in printer's points (1/72 inch)
on the screen.
.PP
\fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the
nearest even number of pixels and stores that value at \fI*intPtr\fR.
It returns \fBTCL_OK\fR under normal circumstances.
If an error occurs (e.g. \fIobjPtr\fR contains a number followed

Changes to doc/GetPixmap.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
.SH NAME
Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







|

|
<







11
12
13
14
15
16
17
18
19
20

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

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

Changes to doc/GetRelief.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
.SH NAME
Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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 ,







|


|


|
<







11
12
13
14
15
16
17
18
19
20
21
22
23
24

25
26
27
28
29
30
31
.SH NAME
Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetReliefFromObj(\fIinterp, objPtr, reliefPtr\fB)\fR
.sp
int
\fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR
.sp
const char *
\fBTk_NameOfRelief(\fIrelief\fB)\fR

.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 ,

Changes to doc/GetRootCrd.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.SH NAME
Tk_GetRootCoords \- Compute root-window coordinates of window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_GetRootCoords\fR(\fItkwin, xPtr, yPtr\fR)
.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.







<







11
12
13
14
15
16
17

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

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

Changes to doc/GetScroll.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
.SH NAME
Tk_GetScrollInfoObj, Tk_GetScrollInfo \- parse arguments for scrolling commands
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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.







|


|
<




|







11
12
13
14
15
16
17
18
19
20
21

22
23
24
25
26
27
28
29
30
31
32
33
.SH NAME
Tk_GetScrollInfoObj, Tk_GetScrollInfo \- parse arguments for scrolling commands
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetScrollInfoObj(\fIinterp, objc, objv, fractionPtr, stepsPtr\fB)\fR
.sp
int
\fBTk_GetScrollInfo(\fIinterp, argc, argv, fractionPtr, stepsPtr\fB)\fR

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

Changes to doc/GetSelect.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Tk_GetSelection \- retrieve the contents of a selection
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR)
.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).







<







12
13
14
15
16
17
18

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

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

Changes to doc/GetUid.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Tk_GetUid, Tk_Uid \- convert from string to unique identifier
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Uid
\fBTk_GetUid\fR(\fIstring\fR)
.fi
.SH ARGUMENTS
.AP char *string in
String for which the corresponding unique identifier is
desired.
.BE
.SH DESCRIPTION
.PP







<







12
13
14
15
16
17
18

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

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

Changes to doc/GetVRoot.3.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.BS
.SH NAME
Tk_GetVRootGeometry \- Get location and size of virtual root for window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_GetVRootGeometry\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







|
<







10
11
12
13
14
15
16
17

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

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

Changes to doc/GetVisual.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
.SH NAME
Tk_GetVisual \- translate from string to visual
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







|
<







11
12
13
14
15
16
17
18

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

.SH ARGUMENTS
.AS "Tcl_Interp" *colormapPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Token for window in which the visual will be used.
.AP "const char" *string in
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
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







<














<



<





<



<







44
45
46
47
48
49
50

51
52
53
54
55
56
57
58
59
60
61
62
63
64

65
66
67

68
69
70
71
72

73
74
75

76
77
78
79
80
81
82
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

Changes to doc/Grab.3.

10
11
12
13
14
15
16

17
18
19
20
21
22
23
24
25
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







>

<







10
11
12
13
14
15
16
17
18

19
20
21
22
23
24
25
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR)
.sp
void
\fBTk_Ungrab\fR(\fItkwin\fR)

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

Changes to doc/HWNDToWindow.3.

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Tk_HWNDToWindow \- Find Tk's window information for a Windows window
.SH SYNOPSIS
.nf
\fB#include <tkPlatDecls.h>\fR
.sp
Tk_Window
\fBTk_HWNDToWindow\fR(\fIhwnd\fR)
.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







<







9
10
11
12
13
14
15

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

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

Changes to doc/HandleEvent.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.SH NAME
Tk_HandleEvent \- invoke event handlers for window system events
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_HandleEvent\fR(\fIeventPtr\fR)
.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







<







11
12
13
14
15
16
17

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

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

Changes to doc/IdToWindow.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Tk_IdToWindow \- Find Tk's window information for an X window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Window
\fBTk_IdToWindow\fR(\fIdisplay, window\fR)
.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







<







11
12
13
14
15
16
17

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

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

Changes to doc/ImgChanged.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.SH NAME
Tk_ImageChanged \- notify widgets that image needs to be redrawn
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_ImageChanged\fR(\fImodel, x, y, width, height, imageWidth, imageHeight\fR)
.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







<







11
12
13
14
15
16
17

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

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

Changes to doc/Inactive.3.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.SH NAME
Tk_GetUserInactiveTime, Tk_ResetUserInactiveTime \- discover user inactivity time
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







|

|
<







8
9
10
11
12
13
14
15
16
17

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

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

Changes to doc/InternAtom.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
.SH NAME
Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







|


|
<







11
12
13
14
15
16
17
18
19
20
21

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

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

Changes to doc/MainLoop.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.SH NAME
Tk_MainLoop \- loop for events until all windows are deleted
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







<







11
12
13
14
15
16
17

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

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

Changes to doc/MainWin.3.

13
14
15
16
17
18
19

20
21

22
23
24
25
26
27
28
29
30
31
32
33
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







>


>




<







13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

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

.SH ARGUMENTS
.AS Tcl_Interp *pathName
.AP Tcl_Interp *interp in/out
Interpreter associated with the application.
.AP Tk_Window tkwin in
Token for main window.
.AP const char *menuName in
47
48
49
50
51
52
53
54
55
56
57
58
59
60
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







|






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

Changes to doc/MaintGeom.3.

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_MaintainGeometry\fR(\fIwindow, container, x, y, width, height\fR)
.sp
\fBTk_UnmaintainGeometry\fR(\fIwindow, container\fR)
.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







<







13
14
15
16
17
18
19

20
21
22
23
24
25
26
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_MaintainGeometry\fR(\fIwindow, container, x, y, width, height\fR)
.sp
\fBTk_UnmaintainGeometry\fR(\fIwindow, container\fR)

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

Changes to doc/ManageGeom.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.SH NAME
Tk_ManageGeometry \- arrange to handle geometry requests for a window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR)
.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







<







11
12
13
14
15
16
17

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

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

Changes to doc/MapWindow.3.

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
.nf
\fB#include <tk.h>\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







<







14
15
16
17
18
19
20

21
22
23
24
25
26
27
.nf
\fB#include <tk.h>\fR
.sp
Tk_Window
\fBTk_MapWindow\fR(\fItkwin\fR)
.sp
\fBTk_UnmapWindow\fR(\fItkwin\fR)

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

Changes to doc/MeasureChar.3.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
.SH NAME
Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_MeasureChars\fR(\fItkfont, string, numBytes, 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_UnderlineChars\fR(\fIdisplay, drawable, gc, tkfont, string, 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.
.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.







|


|

|

|
|










|














|
|







10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
.SH NAME
Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_MeasureChars(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fB)\fR
.sp
int
\fBTk_TextWidth(\fItkfont, string, numBytes\fB)\fR
.sp
\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fB)\fR
.sp
\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fB)\fR
.sp
.SH ARGUMENTS
.AS "const char" firstChar
.AP Tk_Font tkfont in
Token for font in which text is to be drawn or measured.  Must have been
returned by a previous call to \fBTk_GetFont\fR.
.AP "const char" *string in
Text to be measured or displayed.  Need not be null terminated.  Any
non-printing meta-characters in the string (such as tabs, newlines, and
other control characters) will be measured or displayed in a
platform-dependent manner.
.AP int numBytes in
The maximum number of bytes to consider when measuring or drawing
\fIstring\fR.  Must be greater than or equal to 0.
.AP int maxPixels in
If \fImaxPixels\fR is >= 0, it specifies the longest permissible
line length in pixels.  Characters from \fIstring\fR are processed only
until this many pixels have been covered.  If \fImaxPixels\fR is < 0, then
the line length is unbounded and the \fIflags\fR argument is ignored.
.AP int flags in
Various flag bits OR-ed together: \fBTK_PARTIAL_OK\fR means include a character
as long as any part of it fits in the length given by \fImaxPixels\fR;
otherwise, a character must fit completely to be considered.
\fBTK_WHOLE_WORDS\fR means stop on a word boundary, if possible.  If
\fBTK_AT_LEAST_ONE\fR is set, it means return at least one character even if no
characters could fit in the length given by \fImaxPixels\fR.  If
\fBTK_AT_LEAST_ONE\fR is set and \fBTK_WHOLE_WORDS\fR is also set, it means that if
not even one word fits on the line, return the first few letters of the
word that did fit; if not even one letter of the word fit, then the first
letter will still be returned.
.AP int *lengthPtr out
Filled with the number of pixels occupied by the number of characters
returned as the result of \fBTk_MeasureChars\fR.
.AP Display *display in
Display on which to draw.

Changes to doc/MoveToplev.3.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.BS
.SH NAME
Tk_MoveToplevelWindow \- Adjust the position of a top-level window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







|
<







10
11
12
13
14
15
16
17

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

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

Changes to doc/Name.3.

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
\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.
.AP "const char" *pathName in







<







18
19
20
21
22
23
24

25
26
27
28
29
30
31
\fBTk_Name\fR(\fItkwin\fR)
.sp
char *
\fBTk_PathName\fR(\fItkwin\fR)
.sp
Tk_Window
\fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR)

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

Changes to doc/NameOfImg.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Tk_NameOfImage \- Return name of image.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







<







11
12
13
14
15
16
17

18
19
20
21
22
23
24
Tk_NameOfImage \- Return name of image.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
const char *
\fBTk_NameOfImage\fR(\fIimageModel\fR)

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

Changes to doc/OwnSelect.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.SH NAME
Tk_OwnSelection \- make a window the owner of the primary selection
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_OwnSelection\fR(\fItkwin, selection, proc, clientData\fR)
.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







<







11
12
13
14
15
16
17

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

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

Changes to doc/ParseArgv.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Tk_ParseArgv \- process command-line options
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR)
.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.







<







12
13
14
15
16
17
18

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

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

117
118
119
120

121
122
123
124

125
126
127
128
129
130
131
132
133
134
135

136
137
138
139
140
141
142

143
144
145
146
147

148
149
150
151
152
153
154
155

156
157
158
159
160
161
162

163
164
165
166
167
168
169

170
171
172
173
174
175
176

177
178
179
180
181
182
183
184
185
186
187

188
189
190
191
192
193
194
195
196
197
198
199

200
201
202
203
204
205
206
207
.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)







>
|



>
|



>
|










>
|






>
|




>
|







>
|






>
|






>
|






>
|










>
|











>
|







109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
.QW "the matching argument"
in the descriptions below.  As part of the processing,
\fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR
after the matching argument, which is called
.QW "the following argument" .
The legal values for \fItype\fR, and the processing
that they cause, are as follows:
.TP
\fBTK_ARGV_END\fR
Marks the end of the table.  The last entry in \fIargTable\fR
must have this type;  all of its other fields are ignored and it
will never match any arguments.
.TP
\fBTK_ARGV_CONSTANT\fR
\fISrc\fR is treated as an integer and \fIdst\fR is treated
as a pointer to an integer.  \fISrc\fR is stored at \fI*dst\fR.
The matching argument is discarded.
.TP
\fBTK_ARGV_INT\fR
The following argument must contain an
integer string in the format accepted by \fBstrtol\fR (e.g.
.QW 0
and
.QW 0x
prefixes may be used to specify octal or hexadecimal
numbers, respectively).  \fIDst\fR is treated as a pointer to an
integer;  the following argument is converted to an integer value
and stored at \fI*dst\fR.  \fISrc\fR is ignored.  The matching
and following arguments are discarded from \fIargv\fR.
.TP
\fBTK_ARGV_FLOAT\fR
The following argument must contain a floating-point number in
the format accepted by \fBstrtol\fR.
\fIDst\fR is treated as the address of a double-precision
floating point value;  the following argument is converted to a
double-precision value and stored at \fI*dst\fR.  The matching
and following arguments are discarded from \fIargv\fR.
.TP
\fBTK_ARGV_STRING\fR
In this form, \fIdst\fR is treated as a pointer to a (char *);
\fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following
argument, and discards the matching and following arguments from
\fIargv\fR.  \fISrc\fR is ignored.
.TP
\fBTK_ARGV_UID\fR
This form is similar to \fBTK_ARGV_STRING\fR, except that the argument
is turned into a Tk_Uid by calling \fBTk_GetUid\fR.
\fIDst\fR is treated as a pointer to a
Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid
corresponding to the following
argument, and discards the matching and following arguments from
\fIargv\fR.  \fISrc\fR is ignored.
.TP
\fBTK_ARGV_CONST_OPTION\fR
This form causes a Tk option to be set (as if the \fBoption\fR
command had been invoked).  The \fIsrc\fR field is treated as a
pointer to a string giving the value of an option, and \fIdst\fR
is treated as a pointer to the name of the option.  The matching
argument is discarded.  If \fItkwin\fR is NULL, then argument
specifiers of this type are ignored (as if they did not exist).
.TP
\fBTK_ARGV_OPTION_VALUE\fR
This form is similar to \fBTK_ARGV_CONST_OPTION\fR, except that the
value of the option is taken from the following argument instead
of from \fIsrc\fR.  \fIDst\fR is used as the name of the option.
\fISrc\fR is ignored.  The matching and following arguments
are discarded.  If \fItkwin\fR is NULL, then argument
specifiers of this type are ignored (as if they did not exist).
.TP
\fBTK_ARGV_OPTION_NAME_VALUE\fR
In this case the following argument is taken as the name of a Tk
option and the argument after that is taken as the value for that
option.  Both \fIsrc\fR and \fIdst\fR are ignored.  All three
arguments are discarded from \fIargv\fR.  If \fItkwin\fR is NULL,
then argument
specifiers of this type are ignored (as if they did not exist).
.TP
\fBTK_ARGV_HELP\fR
When this kind of option is encountered, \fBTk_ParseArgv\fR uses the
\fIhelp\fR fields of \fIargTable\fR to format a message describing
all the valid arguments.  The message is placed in interpreter
\fIinterp\fR's result
and \fBTk_ParseArgv\fR returns \fBTCL_ERROR\fR.  When this happens, the
caller normally prints the help message and aborts.  If the \fIkey\fR
field of a \fBTK_ARGV_HELP\fR specifier is NULL, then the specifier will
never match any arguments;  in this case the specifier simply provides
extra documentation, which will be included when some other
\fBTK_ARGV_HELP\fR entry causes help information to be returned.
.TP
\fBTK_ARGV_REST\fR
This option is used by programs or commands that allow the last
several of their options to be the name and/or options for some
other program.  If a \fBTK_ARGV_REST\fR argument is found, then
\fBTk_ParseArgv\fR does not process any
of the remaining arguments;  it returns them all at
the beginning of \fIargv\fR (along with any other unprocessed arguments).
In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an
integer value, and stores at \fI*dst\fR the index of the first of the
\fBTK_ARGV_REST\fR options in the returned \fIargv\fR.  This allows the
program to distinguish the \fBTK_ARGV_REST\fR options from other
unprocessed options that preceded the \fBTK_ARGV_REST\fR.
.TP
\fBTK_ARGV_FUNC\fR
For this kind of argument, \fIsrc\fR is treated as the address of
a procedure, which is invoked to process the following argument.
The procedure should have the following structure:
.RS
.CS
int
\fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR)
217
218
219
220
221
222
223

224
225
226
227
228
229
230
231
(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







>
|







228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
(or NULL if there are not any more arguments left in \fIargv\fR).
If \fIfunc\fR uses \fInextArg\fR (so that
\fBTk_ParseArgv\fR should discard it), then it should return 1.  Otherwise it
should return 0 and \fBTkParseArgv\fR will process the following
argument in the normal fashion.  In either event the matching argument
is discarded.
.RE
.TP
\fBTK_ARGV_GENFUNC\fR
This form provides a more general procedural escape.  It treats
\fIsrc\fR as the address of a procedure, and passes that procedure
all of the remaining arguments.  The procedure should have the following
form:
.RS
.CS
int
250
251
252
253
254
255
256

257
258
259
260
261

262
263
264
265

266
267
268
269
270
271
272

273
274
275
276
277
278
279
280
\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







>
|




>
|



>
|






>
|







262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
\fBTk_ParseArgv\fR will process them.  If \fIgenfunc\fR encounters
an error then it should leave an error message in interpreter
\fIinterp\fR's result,
in the usual Tcl fashion, and return \-1;  when this happens
\fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR.
.RE
.SS "FLAGS"
.TP
\fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR
\fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program
or command name, and returns it to the caller just as if it
had not matched \fIargTable\fR.  If this flag is given, then
\fIargv[0]\fR is not given special treatment.
.TP
\fBTK_ARGV_NO_ABBREV\fR
Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for
\fIkey\fR values in \fIargTable\fR.  If this flag is given then
only exact matches will be acceptable.
.TP
\fBTK_ARGV_NO_LEFTOVERS\fR
Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the
caller.  If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR
will return an error if it encounters any argument that does not
match \fIargTable\fR.  The only exception to this rule is \fIargv[0]\fR,
which will be returned to the caller with no errors as
long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR is not specified.
.TP
\fBTK_ARGV_NO_DEFAULTS\fR
Normally, \fBTk_ParseArgv\fR searches an internal table of
standard argument specifiers in addition to \fIargTable\fR.  If
this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will
use only \fIargTable\fR and not its default table.
.SH EXAMPLE
.PP
Here is an example definition of an \fIargTable\fR and
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310


311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
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







|

|

|







>
>
|



















|
|
|









308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
char *fileName = defaultFileName;
Boolean exec = FALSE;

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

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

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

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

Changes to doc/QWinEvent.3.

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
.nf
\fB#include <tk.h>\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







<







13
14
15
16
17
18
19

20
21
22
23
24
25
26
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_CollapseMotionEvents\fR(\fIdisplay, collapse\fR)
.sp
\fBTk_QueueWindowEvent\fR(\fIeventPtr, position\fR)

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

Changes to doc/Restack.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Tk_RestackWindow \- Change a window's position in the stacking order
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_RestackWindow\fR(\fItkwin, aboveBelow, other\fR)
.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.







<







12
13
14
15
16
17
18

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

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

Changes to doc/RestrictEv.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Tk_RestrictEvents \- filter and selectively delay X events
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_RestrictProc *
\fBTk_RestrictEvents\fR(\fIproc, arg, prevArgPtr\fR)
.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.







<







12
13
14
15
16
17
18

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

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

Changes to doc/SetAppName.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Tk_SetAppName \- Set the name of an application for 'send' commands
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
const char *
\fBTk_SetAppName\fR(\fItkwin, name\fR)
.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.







<







12
13
14
15
16
17
18

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

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

Changes to doc/SetCaret.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Tk_SetCaretPos \- set the display caret location
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_SetCaretPos\fR(\fItkwin, x, y, height\fR)
.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.







<







11
12
13
14
15
16
17

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

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

Changes to doc/SetClass.3.

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
.nf
\fB#include <tk.h>\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







<







14
15
16
17
18
19
20

21
22
23
24
25
26
27
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_SetClass\fR(\fItkwin, class\fR)
.sp
Tk_Uid
\fBTk_Class\fR(\fItkwin\fR)

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

Changes to doc/SetClassProcs.3.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
.SH NAME
Tk_SetClassProcs \- register widget specific procedures
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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 {
    size_t \fIsize\fR;
    Tk_ClassWorldChangedProc *\fIworldChangedProc\fR;
    Tk_ClassCreateProc *\fIcreateProc\fR;
    Tk_ClassModalProc *\fImodalProc\fR;
} \fBTk_ClassProcs\fR;
.CE
The \fIsize\fR field is used to simplify future expansion of the







<


















|







10
11
12
13
14
15
16

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
.SH NAME
Tk_SetClassProcs \- register widget specific procedures
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_SetClassProcs\fR(\fItkwin, procs, instanceData\fR)

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

Changes to doc/SetGrid.3.

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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.







<







13
14
15
16
17
18
19

20
21
22
23
24
25
26
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_SetGrid\fR(\fItkwin, reqWidth, reqHeight, widthInc, heightInc\fR)
.sp
\fBTk_UnsetGrid\fR(\fItkwin\fR)

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

Changes to doc/SetOptions.3.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
.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 <tk.h>\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.







|

|


|


|

|

|


|


|

|
<







10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

38
39
40
41
42
43
44
.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 <tk.h>\fR
.sp
Tk_OptionTable
\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR
.sp
\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR
.sp
int
\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR
.sp
int
\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR
.sp
\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR
.sp
\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR
.sp
Tcl_Obj *
\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
.sp
Tcl_Obj *
\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
.sp
\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR

.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.
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
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.







|







54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
fields of this record are modified by procedures such as \fBTk_SetOptions\fR
and read by procedures such as \fBTk_GetOptionValue\fR.
.AP Tk_Window tkwin in
For options such as \fBTK_OPTION_COLOR\fR, this argument indicates
the window in which the option will be used.  If \fIoptionTable\fR uses
no window-dependent options, then a NULL value may be supplied for
this argument.
.AP int objc in
Number of values in \fIobjv\fR.
.AP Tcl_Obj "*const *objv" in
Command-line arguments for setting configuring options.
.AP Tk_SavedOptions *savePtr out
If not NULL, the structure pointed to by this argument is filled
in with the old values of any options that were modified and old
values are restored automatically if an error occurs in \fBTk_SetOptions\fR.
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
.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







|







94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
.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: 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
298
299
300
301
302
303
304

305
306
307
308
309
310
311
312
313
314
315

316
317
318
319
320
321

322
323
324
325
326
327

328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350

351
352
353
354
355

356
357
358
359
360
361
362

363
364
365
366
367
368

369
370
371
372
373
374

375
376
377
378
379
380
381
382

383
384
385
386

387
388
389
390
391

392
393
394
395
396
397
398
399

400
401
402
403
404
405

406
407
408
409
410
411

412
413
414
415
416
417
418
419
420

421
422
423
424
425
426
427

428
429
430
431
432
433
434
435
436

437
438
439
440
441
442

443
444
445
446

447
448
449
450
451
452
453
454
455

456
457
458
459
460
461

462
463
464
465
466
467
468
469
\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







>
|










>
|





>
|





>
|





<









|
|


|
|
|
>
|




>
|

|
|
|


>
|





>
|





>
|







>
|



>
|




>
|







>
|





>
|


|
|

>
|
|
<

|




>
|


|
<


>
|



|
|



>
|





>
|



>
|








>
|





>
|







297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336

337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426

427
428
429
430
431
432
433
434
435
436
437

438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
\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:
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\fBTK_OPTION_VAR(type)\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

.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.
.TP
\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.
.TP
\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.
.TP
\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: if the
\fIobjOffset\fR field is not used then 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.
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\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: if the \fIobjOffset\fR field is not
used then 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.
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\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.
.TP
\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
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
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.  In most cases it is convenient to use the
\fIinternalOffset\fR field as well, so that the integer value is
immediately available for use in the widget code (alternatively,
\fBTk_GetPixelsFromObj\fR can be used to extract the integer value from
the object whenever it is needed).  Note that 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 {
    char *name;
    Tk_CustomOptionSetProc *\fIsetProc\fR;
    Tk_CustomOptionGetProc *\fIgetProc\fR;
    Tk_CustomOptionRestoreProc *\fIrestoreProc\fR;
    Tk_CustomOptionFreeProc *\fIfreeProc\fR;
    void *\fIclientData\fR;
} \fBTk_ObjCustomOption\fR;







|
|


















|







523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
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.  In most cases it is convenient to use the
\fIinternalOffset\fR field as well, so that the integer value is
immediately available for use in the widget code (alternatively,
\fBTk_GetPixelsFromObj\fR can be used 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 Tk_ObjCustomOption {
    char *name;
    Tk_CustomOptionSetProc *\fIsetProc\fR;
    Tk_CustomOptionGetProc *\fIgetProc\fR;
    Tk_CustomOptionRestoreProc *\fIrestoreProc\fR;
    Tk_CustomOptionFreeProc *\fIfreeProc\fR;
    void *\fIclientData\fR;
} \fBTk_ObjCustomOption\fR;
575
576
577
578
579
580
581

582
583
584

585
586

587
588

589
590
591
592
593
594
595
596
597
598

599
600

601
602
603

604
605
606
607
608
609

610
611
612
613
614
615
616
617
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







>
|


>
|

>
|

>
|









>
|

>
|


>
|





>
|







593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
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
.TP
\fIclientData\fR
A copy of the \fIclientData\fR field in the Tk_ObjCustomOption
structure.
.TP
\fIinterp\fR
A pointer to a Tcl interpreter, used for error reporting.
.TP
\fITkwin\fR
A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR
.TP
\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.
.TP
\fIrecordPtr\fR
A pointer to the start of the widget record to modify.
.TP
\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.
.TP
\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.
.TP
\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

Changes to doc/SetVisual.3.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Tk_SetWindowVisual \- change visual characteristics of window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_SetWindowVisual\fR(\fItkwin, visual, depth, colormap\fR)
.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







<







12
13
14
15
16
17
18

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

.SH ARGUMENTS
.AS "Tk_Window int" colormap
.AP Tk_Window tkwin in
Token for window.
.AP Visual *visual in
New visual type to use for \fItkwin\fR.
.AP "int" depth in
40
41
42
43
44
45
46
47
48
49
50
51
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







|




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

Changes to doc/StrictMotif.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Tk_StrictMotif \- Return value of tk_strictMotif variable
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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







<







11
12
13
14
15
16
17

18
19
20
21
22
23
24
Tk_StrictMotif \- Return value of tk_strictMotif variable
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_StrictMotif\fR(\fItkwin\fR)

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

Changes to doc/TextLayout.3.

10
11
12
13
14
15
16
17
18

19
20

21
22

23
24
25
26
27
28
29
30
31
32
33
34
35
36

37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
.SH NAME
Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_TextLayout
\fBTk_ComputeTextLayout\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 less than 0, 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







|

>
|

>
|

>
|


|


|


|


|

>
|
<












|







10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
.SH NAME
Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_TextLayout
\fBTk_ComputeTextLayout(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fB)\fR
.sp
void
\fBTk_FreeTextLayout(\fIlayout\fB)\fR
.sp
void
\fBTk_DrawTextLayout(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fB)\fR
.sp
void
\fBTk_UnderlineTextLayout(\fIdisplay, drawable, gc, layout, x, y, underline\fB)\fR
.sp
int
\fBTk_PointToChar(\fIlayout, x, y\fB)\fR
.sp
int
\fBTk_CharBbox(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fB)\fR
.sp
int
\fBTk_DistanceToTextLayout(\fIlayout, x, y\fB)\fR
.sp
int
\fBTk_IntersectTextLayout(\fIlayout, x, y, width, height\fB)\fR
.sp
void
\fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR

.SH ARGUMENTS
.AS Tk_TextLayout "*xPtr, *yPtr"
.AP Tk_Font tkfont in
Font to use when constructing and displaying a text layout.  The
\fItkfont\fR must remain valid for the lifetime of the text layout.  Must
have been returned by a previous call to \fBTk_GetFont\fR.
.AP "const char" *string in
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
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
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.







|


|







|







96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
this GC must correspond to the \fItkfont\fR used when constructing the
text layout.
.AP int "x, y" in
Point, in pixels, at which to place the upper-left hand corner of the
text layout when it is being drawn, or the coordinates of a point (with
respect to the upper-left hand corner of the text layout) to check
against the text layout.
.AP int firstChar in
The index of the first character to draw from the given text layout.
The number 0 means to draw from the beginning.
.AP int lastChar in
The index of the last character up to which to draw.  The character
specified by \fIlastChar\fR itself will not be drawn.  A number less
than 0 means to draw all characters in the text layout.
.AP int underline in
Index of the single character to underline in the text layout, or a
negative number counting backwards from the end of the string. Any
out-of-range number (e.g. INT_MIN) means no underline.
.AP int index in
The index of the character whose bounding box is desired.  The bounding
box is computed with respect to the upper-left hand corner of the text layout.
.AP int "*xPtr, *yPtr" out
Filled with the upper-left hand corner, in pixels, of the bounding box
for the character specified by \fIindex\fR.  Either or both \fIxPtr\fR
and \fIyPtr\fR may be NULL, in which case the corresponding value
is not calculated.
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
\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 less than 0 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







|







175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
\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

Changes to doc/TkInitStubs.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Tk_InitStubs \- initialize the Tk stubs mechanism
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
const char *
\fBTk_InitStubs\fR(\fIinterp, version, exact\fR)
.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.







<







11
12
13
14
15
16
17

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

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

Changes to doc/Tk_Init.3.

43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
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







<



<






<



<




<



<



<



<



<




<




43
44
45
46
47
48
49

50
51
52

53
54
55
56
57
58

59
60
61

62
63
64
65

66
67
68

69
70
71

72
73
74

75
76
77

78
79
80
81

82
83
84
85
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

Changes to doc/Tk_Main.3.

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
.SH SYNOPSIS
.nf
\fB#include <tk.h>\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.







|







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

Changes to doc/WinUtil.3.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
.SH NAME
Tk_GetOtherWindow, Tk_MakeContainer, Tk_MakeWindow, Tk_UseWindow \- window utility functions
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Window
\fBTk_GetOtherWindow\fR(\fItkwin\fR)
.sp
\fBTk_MakeContainer\fR(\fItkwin\fR)
.sp
\fBTk_MakeWindow\fR(\fItkwin, parent\fR)
.sp
int
\fBTk_UseWindow\fR(\fIinterp, tkwin, string\fR)
.fi
.SH ARGUMENTS
.AS XSetWindowAttributes borderWidth
.AP Tcl_Interp * interp in
Interpreter associated with the application.
.AP Tk_Window tkwin in
Token for window.
.AP Window parent in







|

|

|


|
<







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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

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

Changes to doc/WindowId.3.

99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
\fBTk_Colormap\fR(\fItkwin\fR)
.sp
Tcl_Interp *
\fBTk_Interp\fR(\fItkwin\fR)
.sp
Tcl_Obj *
\fBTk_NewWindowObj\fR(\fItkwin\fR)
.fi
.SH ARGUMENTS
.AS Tk_Window tkwin
.AP Tk_Window tkwin in
Token for window.
.BE
.SH DESCRIPTION
.PP







<







99
100
101
102
103
104
105

106
107
108
109
110
111
112
\fBTk_Colormap\fR(\fItkwin\fR)
.sp
Tcl_Interp *
\fBTk_Interp\fR(\fItkwin\fR)
.sp
Tcl_Obj *
\fBTk_NewWindowObj\fR(\fItkwin\fR)

.SH ARGUMENTS
.AS Tk_Window tkwin
.AP Tk_Window tkwin in
Token for window.
.BE
.SH DESCRIPTION
.PP
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
The width and height information refers to the interior size
of the window, not including any border.  \fBTk_Changes\fR
returns a pointer to a structure containing all of the above
information plus a few other fields.  \fBTk_Attributes\fR
returns a pointer to an XSetWindowAttributes structure describing
all of the attributes of the \fItkwin\fR's window, such as background
pixmap, event mask, and so on (Tk keeps track of all this information
as it is changed by the application).  Note that it is essential that
applications use Tk procedures like \fBTk_ResizeWindow\fR instead
of X procedures like \fBXResizeWindow\fR, so that Tk can keep its
data structures up-to-date.
.PP
\fBTk_IsContainer\fR returns a non-zero value if \fItkwin\fR
is a container, and that some other application may be embedding
itself inside \fItkwin\fR.







|







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

Changes to doc/bind.n.

145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
times, and also place a time and space requirement on the sequence: for a
sequence of events to match a \fBDouble\fR, \fBTriple\fR or \fBQuadruple\fR
pattern, all of the events must occur close together in time and without
substantial mouse motion in between.  For example, \fB<Double\-Button\-1>\fR
is equivalent to \fB<Button\-1><Button\-1>\fR with the extra time and space
requirement.
.PP
The \fBCommand\fR, \fBOption\fR, \fBNum\fR and \fBFn\fRmodifiers are
equivalents of \fBMod1\fR up to \fBMod4\fR; they correspond to
Macintosh-specific modifier keys.
.PP
The \fBExtended\fR modifier is, at present, specific to Windows.  It
appears on events that are associated with the keys on the
.QW "extended keyboard" .
On a US keyboard, the extended keys include the \fBAlt\fR
and \fBControl\fR keys at the right of the keyboard, the cursor keys
in the cluster to the left of the numeric pad, the \fBNumLock\fR key,







|
<
|







145
146
147
148
149
150
151
152

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

of \fBMod1\fR up to \fBMod4\fR, they correspond to Macintosh-specific modifier keys.
.PP
The \fBExtended\fR modifier is, at present, specific to Windows.  It
appears on events that are associated with the keys on the
.QW "extended keyboard" .
On a US keyboard, the extended keys include the \fBAlt\fR
and \fBControl\fR keys at the right of the keyboard, the cursor keys
in the cluster to the left of the numeric pad, the \fBNumLock\fR key,
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
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:







|

|







645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
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:
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
The \fBbgerror\fR command will be executed at global level
(outside the context of any Tcl procedure).
.SH "EXAMPLES"
.PP
Arrange for a string describing the motion of the mouse to be printed
out when the mouse is double-clicked:
.CS
\fBbind\fR . <Double-1> {
    puts "hi from (%x,%y)"
}
.CE
.PP
A little GUI that displays what the keysym name of the last key
pressed is:
.CS
set keysym "Press any key"
pack [label .l -textvariable keysym -padx 2m -pady 1m]
\fBbind\fR . <Key> {
    set keysym "You pressed %K"
}
.CE
.SH "SEE ALSO"
bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n)
.SH KEYWORDS
binding, event
'\" Local Variables:
'\" mode: nroff
'\" End:







|








|











735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
The \fBbgerror\fR command will be executed at global level
(outside the context of any Tcl procedure).
.SH "EXAMPLES"
.PP
Arrange for a string describing the motion of the mouse to be printed
out when the mouse is double-clicked:
.CS
\fBbind\fR . <Double\-1> {
    puts "hi from (%x,%y)"
}
.CE
.PP
A little GUI that displays what the keysym name of the last key
pressed is:
.CS
set keysym "Press any key"
pack [label .l \-textvariable keysym \-padx 2m \-pady 1m]
\fBbind\fR . <Key> {
    set keysym "You pressed %K"
}
.CE
.SH "SEE ALSO"
bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n)
.SH KEYWORDS
binding, event
'\" Local Variables:
'\" mode: nroff
'\" End:

Changes to doc/bitmap.n.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
'\" 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.







|







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
bitmap \- Images that display two colors
.SH SYNOPSIS
.nf
\fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR?

\fIimageName \fBcget\fR \fIoption\fR
\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
.fi
.BE
.SH DESCRIPTION
.PP
A bitmap is an image whose pixels can display either of two colors
or be transparent.
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
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







<








<








<







<





<








<




















<

|





<







35
36
37
38
39
40
41

42
43
44
45
46
47
48
49

50
51
52
53
54
55
56
57

58
59
60
61
62
63
64

65
66
67
68
69

70
71
72
73
74
75
76
77

78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

98
99
100
101
102
103
104

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

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

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

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

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

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

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

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

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

Changes to doc/busy.n.

26
27
28
29
30
31
32
33
34

35

36

37

38

39

40
41
42
43
44
45
46
47
48
.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.







<
|
>

>
|
>

>
|
>

>

<







26
27
28
29
30
31
32

33
34
35
36
37
38
39
40
41
42
43
44
45

46
47
48
49
50
51
52
.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

\fBtk busy\fR \fIwindow \fR?\fIoptions\fR?
.sp
\fBtk busy busywindow \fIwindow\fR
.sp
\fBtk busy hold\fR \fIwindow \fR?\fIoptions\fR?
.sp
\fBtk busy configure \fIwindow\fR ?\fIoption value\fR?...
.sp
\fBtk busy forget\fR \fIwindow \fR?\fIwindow \fR?...
.sp
\fBtk busy current\fR ?\fIpattern\fR?
.sp
\fBtk busy status \fIwindow\fR

.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.
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
\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







|












<






<

|






<







112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

132
133
134
135
136
137

138
139
140
141
142
143
144
145

146
147
148
149
150
151
152
\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.

.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.

.TP
\fBtk busy cget \fIwindow\fR \fIoption\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.

.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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
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







<






<








<














<







<







165
166
167
168
169
170
171

172
173
174
175
176
177

178
179
180
181
182
183
184
185

186
187
188
189
190
191
192
193
194
195
196
197
198
199

200
201
202
203
204
205
206

207
208
209
210
211
212
213
specified for it by either \fBoption\fR command:
.PP
.CS
option add *frame.busyCursor gumby
option add *Frame.BusyCursor gumby
.CE
.RE

.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.

.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.

.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

.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

.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

Changes to doc/button.n.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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







|







8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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\fR \fIpathName \fR?\fIoptions\fR?
.SO
\-activebackground	\-font	\-relief
\-activeforeground	\-foreground	\-repeatdelay
\-anchor	\-highlightbackground	\-repeatinterval
\-background	\-highlightcolor	\-takefocus
\-bitmap	\-highlightthickness	\-text
\-borderwidth	\-image	\-textvariable
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
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







<

|
<




<


<












<


<





<


<







110
111
112
113
114
115
116

117
118

119
120
121
122

123
124

125
126
127
128
129
130
131
132
133
134
135
136

137
138

139
140
141
142
143

144
145

146
147
148
149
150
151
152
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:

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

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

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

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

.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.

.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
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
.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 . <Key-h> {.b1 flash; .b1 invoke}
bind . <Key-w> {.b2 flash; .b2 invoke}
pack .b1 .b2
.CE
.SH "SEE ALSO"
ttk::button(n)
.SH KEYWORDS
button, widget
'\" Local Variables:
'\" mode: nroff
'\" End:







|






|
|
|
|









184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
.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 . <Key\-h> {.b1 flash; .b1 invoke}
bind . <Key\-w> {.b2 flash; .b2 invoke}
pack .b1 .b2
.CE
.SH "SEE ALSO"
ttk::button(n)
.SH KEYWORDS
button, widget
'\" Local Variables:
'\" mode: nroff
'\" End:

Changes to doc/canvas.n.

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
.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







|







9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
.TH canvas n 8.3 Tk "Tk Built-In Commands"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
canvas \- Create and manipulate 'canvas' hypergraphics drawing surface widgets
.SH SYNOPSIS
\fBcanvas\fR \fIpathName \fR?\fIoptions\fR?
.SO
\-background	\-borderwidth	\-cursor
\-highlightbackground	\-highlightcolor	\-highlightthickness
\-insertbackground	\-insertborderwidth	\-insertofftime
\-insertontime	\-insertwidth	\-relief
\-selectbackground	\-selectborderwidth	\-selectforeground
\-takefocus	\-xscrollcommand	\-yscrollcommand
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
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 less than or equal to 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 less than or equal to 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







|









|







63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
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
252
253
254
255
256
257
258

259

260
261
262
263
264
265
266
267
268
269
270
271

272

273
274
275

276

277
278

279

280
281

282

283
284

285

286
287
288
289
290
291
292
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 number less than 0 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, numbers less than 0 or 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"







>
|
>





|


|



>
|
>



>
|
>


>
|
>


>
|
>


>
|
>







252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
support as many of these forms as practical.
Note that it is possible to refer to the character just after
the last one in the text item; this is necessary for such
tasks as inserting new text at the end of the item.
Lines and Polygons do not support the insertion cursor
and the selection. Their indices are supposed to be even
always, because coordinates always appear in pairs.
.TP 10
\fInumber\fR
.
A decimal number giving the position of the desired character
within the text item.
0 refers to the first character, 1 to the next character, and
so on. If indexes are odd for lines and polygons, they will be
automatically decremented by one.
A negative number  is treated as if it were zero, and a
number greater than the length of the text item is treated
as if it were equal to the length of the text item. For
polygons, negative numbers or numbers greater than the length
of the coordinate list will be adjusted by adding or subtracting
the length until the result is between zero and the length,
inclusive.
.TP 10
\fBend\fR
.
Refers to the character or coordinate just after the last one
in the item (same as the number of characters or coordinates
in the item).
.TP 10
\fBinsert\fR
.
Refers to the character just before which the insertion cursor
is drawn in this item. Not valid for lines and polygons.
.TP 10
\fBsel.first\fR
.
Refers to the first selected character in the item.
If the selection is not in this item then this form is illegal.
.TP 10
\fBsel.last\fR
.
Refers to the last selected character in the item.
If the selection is not in this item then this form is illegal.
.TP 10
\fB@\fIx,y\fR
.
Refers to the character or coordinate at the point given by \fIx\fR and
\fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinate
system of the canvas.
If \fIx\fR and \fIy\fR lie outside the coordinates covered by the
text item, then they refer to the first or last character in the
line that is closest to the given point.
.SH "DASH PATTERNS"
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358

359

360
361
362
363

364

365

366

367
368
369
370

371

372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388

389

390
391
392
393

394

395
396
397
398
399

400

401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
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.







<














>
|
>




>
|
>

>
|
>




>
|
>

















>
|
>




>
|
>





>
|
>


<

















<







349
350
351
352
353
354
355

356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427

428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444

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

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

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

.TP
\fIpathName \fBbind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR?
.
This command associates \fIcommand\fR with all the items given by
\fItagOrId\fR such that whenever the event sequence given by
\fIsequence\fR occurs for one of the items the command will
be invoked.
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
.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







<







<







<

|





<















<

|

|


















<













<












<





<










<









<







499
500
501
502
503
504
505

506
507
508
509
510
511
512

513
514
515
516
517
518
519

520
521
522
523
524
525
526

527
528
529
530
531
532
533
534
535
536
537
538
539
540
541

542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563

564
565
566
567
568
569
570
571
572
573
574
575
576

577
578
579
580
581
582
583
584
585
586
587
588

589
590
591
592
593

594
595
596
597
598
599
600
601
602
603

604
605
606
607
608
609
610
611
612

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

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

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

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

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

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

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

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

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

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

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

.TP
\fIpathName \fBfocus \fR?\fItagOrId\fR?
.
Set the keyboard focus for the canvas widget to the item given by
\fItagOrId\fR.
If \fItagOrId\fR refers to several items, then the focus is set
to the first such item in the display list that supports the
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
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.







<

|







<









<
<
|



<

<
<



|
|
|
<
|
|
<
<
<
|
|
|
|
|
<

<
<








<














<










<
<


<

<
<

|









<







635
636
637
638
639
640
641

642
643
644
645
646
647
648
649
650

651
652
653
654
655
656
657
658
659


660
661
662
663

664


665
666
667
668
669
670

671
672



673
674
675
676
677

678


679
680
681
682
683
684
685
686

687
688
689
690
691
692
693
694
695
696
697
698
699
700

701
702
703
704
705
706
707
708
709
710


711
712

713


714
715
716
717
718
719
720
721
722
723
724

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

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

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


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

This command returns an empty string.


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

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



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

This command returns an empty string.


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

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

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


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

This command returns an empty string.


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

.TP
\fIpathName \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?
.
This command is similar to the \fBconfigure\fR widget command except
that it modifies item-specific options for the items given by
\fItagOrId\fR instead of modifying options for the overall
canvas widget.
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
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.







<










|




<








<












<







740
741
742
743
744
745
746

747
748
749
750
751
752
753
754
755
756
757
758
759
760
761

762
763
764
765
766
767
768
769

770
771
772
773
774
775
776
777
778
779
780
781

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

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

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

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

.TP
\fIpathName \fBpostscript \fR?\fIoption value option value ...\fR?
.
Generate a Postscript representation for part or all of the canvas.
If the \fB\-file\fR option is specified then the Postscript is written
to a file and an empty string is returned; otherwise the Postscript
is returned as the result of the command.
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
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 "8.7, TIP164"
Rotate the coordinates of all of the items given by \fItagOrId\fR in canvas
coordinate space.
\fIXOrigin\fR and \fIyOrigin\fR identify the origin for the rotation
operation and \fIangle\fR identifies the amount to rotate the coordinates







<







<













<
<



<
<







<







<
















<
<



<
<





<






<
<



<
<












<










<








<








<











<





<







<








<













|




<











<







801
802
803
804
805
806
807

808
809
810
811
812
813
814

815
816
817
818
819
820
821
822
823
824
825
826
827


828
829
830


831
832
833
834
835
836
837

838
839
840
841
842
843
844

845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860


861
862
863


864
865
866
867
868

869
870
871
872
873
874


875
876
877


878
879
880
881
882
883
884
885
886
887
888
889

890
891
892
893
894
895
896
897
898
899

900
901
902
903
904
905
906
907

908
909
910
911
912
913
914
915

916
917
918
919
920
921
922
923
924
925
926

927
928
929
930
931

932
933
934
935
936
937
938

939
940
941
942
943
944
945
946

947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964

965
966
967
968
969
970
971
972
973
974
975

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

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

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


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


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

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

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


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


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

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


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


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

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

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

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

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

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

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

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

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

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

.TP
\fIpathName \fBrotate \fItagOrId xOrigin yOrigin angle\fR
.VS "8.7, TIP164"
Rotate the coordinates of all of the items given by \fItagOrId\fR in canvas
coordinate space.
\fIXOrigin\fR and \fIyOrigin\fR identify the origin for the rotation
operation and \fIangle\fR identifies the amount to rotate the coordinates
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
points, and the \fBarc\fR, \fBoval\fR and \fBrectangle\fR types rotate about a
computed center point instead of moving the bounding box coordinates directly.
.PP
Some items (currently \fBarc\fR and\fB text\fR) have angles in their options;
this command \fIdoes not\fR affect those options.
.RE
.VE "8.7, TIP164"
.\" 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







<







990
991
992
993
994
995
996

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

.TP
\fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR
.
Rescale the coordinates of all of the items given by \fItagOrId\fR in canvas
coordinate space.
\fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling
operation and \fIxScale\fR and \fIyScale\fR identify the scale
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
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
.







<

|







1011
1012
1013
1014
1015
1016
1017

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

.TP
\fIpathName \fBscan\fR \fIoption args\fR
.
This command is used to implement scanning on canvases. It has
two forms, depending on \fIoption\fR:
.RS
.TP
\fIpathName \fBscan mark \fIx y\fR
.
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
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







<







1038
1039
1040
1041
1042
1043
1044

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

.TP
\fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR?
.
Manipulates the selection in one of several ways, depending on
\fIoption\fR.
The command may take any of the forms described below.
In all of the descriptions below, \fItagOrId\fR must refer to
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
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







<









<







1104
1105
1106
1107
1108
1109
1110

1111
1112
1113
1114
1115
1116
1117
1118
1119

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

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

.TP
\fIpathName \fBxview \fR?\fIargs\fR?
.
This command is used to query and change the horizontal position of the
information displayed in the canvas's window.
It can take any of the following forms:
.RS
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
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







<







1156
1157
1158
1159
1160
1161
1162

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

.TP
\fIpathName \fByview ?\fIargs\fR?
.
This command is used to query and change the vertical position of the
information displayed in the canvas's window.
It can take any of the following forms:
.RS
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
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







<










<


<


<



|




<







<


<


<



|







<


<


<



|




<














<


<


<



|










<






<


<


<



|










<






<






<


<


<



|












|
|
<







1216
1217
1218
1219
1220
1221
1222

1223
1224
1225
1226
1227
1228
1229
1230
1231
1232

1233
1234

1235
1236

1237
1238
1239
1240
1241
1242
1243
1244

1245
1246
1247
1248
1249
1250
1251

1252
1253

1254
1255

1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266

1267
1268

1269
1270

1271
1272
1273
1274
1275
1276
1277
1278

1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292

1293
1294

1295
1296

1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310

1311
1312
1313
1314
1315
1316

1317
1318

1319
1320

1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334

1335
1336
1337
1338
1339
1340

1341
1342
1343
1344
1345
1346

1347
1348

1349
1350

1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368

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

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

.TP
\fB\-dash \fIpattern\fR

.TP
\fB\-activedash \fIpattern\fR

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

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

.TP
\fB\-fill \fIcolor\fR

.TP
\fB\-activefill \fIcolor\fR

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

.TP
\fB\-outline \fIcolor\fR

.TP
\fB\-activeoutline \fIcolor\fR

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

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

.TP
\fB\-outlinestipple \fIbitmap\fR

.TP
\fB\-activeoutlinestipple \fIbitmap\fR

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

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

.TP
\fB\-stipple \fIbitmap\fR

.TP
\fB\-activestipple \fIbitmap\fR

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

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

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

.TP
\fB\-width \fIoutlineWidth\fR

.TP
\fB\-activewidth \fIoutlineWidth\fR

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

Arcs are created with widget commands of the following form:
.CS
\fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR?
\fIpathName \fBcreate arc \fIcoordList\fR ?\fIoption value ...\fR?
.CE
The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give
the coordinates of two diagonally opposite corners of a
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
\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







<


<






<


<




<


<



|







1397
1398
1399
1400
1401
1402
1403

1404
1405

1406
1407
1408
1409
1410
1411

1412
1413

1414
1415
1416
1417

1418
1419

1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
\fB\-disabledoutlinestipple\fR	\fB\-stipple\fR
\fB\-activestipple\fR	\fB\-disabledstipple\fR
\fB\-state\fR	\fB\-tags\fR
\fB\-width\fR	\fB\-activewidth\fR
\fB\-disabledwidth\fR
.DE
The following extra options are supported for arcs:

.TP
\fB\-extent \fIdegrees\fR

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

.TP
\fB\-start \fIdegrees\fR

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

.TP
\fB\-height \fIdistance\fR

Provides a shortcut for creating a circular arc segment by defining the
distance of the mid-point of the arc from its chord. When this option
is used the coordinates are interpreted as the start and end coordinates
of the chord, and the options \fB\-start\fR and \fB-extent\fR are ignored.
The value of \fIdistance\fR has the following meaning:
.RS
.PP
.RS
\fIdistance\fR > 0 creates a clockwise arc
.br
\fIdistance\fR < 0 creates an counter-clockwise arc
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
.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.







<


<







1439
1440
1441
1442
1443
1444
1445

1446
1447

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

.TP
\fB\-style \fItype\fR

Specifies how to draw the arc. If \fItype\fR is \fBpieslice\fR
(the default) then the arc's region is defined by a section
of the oval's perimeter plus two line segments, one between the center
of the oval and each end of the perimeter section.
If \fItype\fR is \fBchord\fR then the arc's region is defined
by a section of the oval's perimeter plus a single line segment
connecting the two end points of the perimeter section.
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
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.







<


<


<


<







<


<


<


<
|
|

<


<


<


<
|







1478
1479
1480
1481
1482
1483
1484

1485
1486

1487
1488

1489
1490

1491
1492
1493
1494
1495
1496
1497

1498
1499

1500
1501

1502
1503

1504
1505
1506

1507
1508

1509
1510

1511
1512

1513
1514
1515
1516
1517
1518
1519
1520
The following standard options are supported by bitmaps:
.DS
.ta 3i
\fB\-anchor\fR	\fB\-state\fR
\fB\-tags\fR
.DE
The following extra options are supported for bitmaps:

.TP
\fB\-background \fIcolor\fR

.TP
\fB\-activebackground \fIcolor\fR

.TP
\fB\-disabledbackground \fIcolor\fR

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

.TP
\fB\-bitmap \fIbitmap\fR

.TP
\fB\-activebitmap \fIbitmap\fR

.TP
\fB\-disabledbitmap \fIbitmap\fR

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

.TP
\fB\-foreground \fIcolor\fR

.TP
\fB\-activeforeground \fIcolor\fR

.TP
\fB\-disabledforeground \fIcolor\fR

Specifies the color to use for each of the bitmap's
.QW 1
valued pixels in its normal, active and disabled states.
\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
.SS "IMAGE ITEMS"
.PP
Items of type \fBimage\fR are used to display images on a
canvas.
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
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







<


<


<


<







1536
1537
1538
1539
1540
1541
1542

1543
1544

1545
1546

1547
1548

1549
1550
1551
1552
1553
1554
1555
The following standard options are supported by images:
.DS
.ta 3i
\fB\-anchor\fR	\fB\-state\fR
\fB\-tags\fR
.DE
The following extra options are supported for images:

.TP
\fB\-image \fIname\fR

.TP
\fB\-activeimage \fIname\fR

.TP
\fB\-disabledimage \fIname\fR

Specifies the name of the images to display in the item in is normal,
active and disabled states.
This image must have been created previously with the
\fBimage create\fR command.
.SS "LINE ITEMS"
.PP
Items of type \fBline\fR appear on the display as one or more connected
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
\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







<


<













<


<













<


<






<


<







<


<



|
<
















<


<







1581
1582
1583
1584
1585
1586
1587

1588
1589

1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602

1603
1604

1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617

1618
1619

1620
1621
1622
1623
1624
1625

1626
1627

1628
1629
1630
1631
1632
1633
1634

1635
1636

1637
1638
1639
1640

1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656

1657
1658

1659
1660
1661
1662
1663
1664
1665
\fB\-disabledfill\fR	\fB\-stipple\fR
\fB\-activestipple\fR	\fB\-disabledstipple\fR
\fB\-state\fR	\fB\-tags\fR
\fB\-width\fR	\fB\-activewidth\fR
\fB\-disabledwidth\fR
.DE
The following extra options are supported for lines:

.TP
\fB\-arrow \fIwhere\fR

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

.TP
\fB\-arrowshape \fIshape\fR

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

.TP
\fB\-capstyle \fIstyle\fR

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

.TP
\fB\-joinstyle \fIstyle\fR

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

.TP
\fB\-smooth \fIsmoothMethod\fR

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

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

.TP
\fB\-splinesteps \fInumber\fR

Specifies the degree of smoothness desired for curves: each spline
will be approximated with \fInumber\fR line segments. This
option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR.
.SS "OVAL ITEMS"
.PP
Items of type \fBoval\fR appear as circular or oval regions on
the display. Each oval may have an outline, a fill, or
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
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







|
|







1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
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
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
\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







<


<





<


<


|
<

















<


<







1738
1739
1740
1741
1742
1743
1744

1745
1746

1747
1748
1749
1750
1751

1752
1753

1754
1755
1756

1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773

1774
1775

1776
1777
1778
1779
1780
1781
1782
\fB\-disabledoutlinestipple\fR	\fB\-stipple\fR
\fB\-activestipple\fR	\fB\-disabledstipple\fR
\fB\-state\fR	\fB\-tags\fR
\fB\-width\fR	\fB\-activewidth\fR
\fB\-disabledwidth\fR
.DE
The following extra options are supported for polygons:

.TP
\fB\-joinstyle \fIstyle\fR

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

.TP
\fB\-smooth \fIboolean\fR

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

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

.TP
\fB\-splinesteps \fInumber\fR

Specifies the degree of smoothness desired for curves: each spline
will be approximated with \fInumber\fR line segments. This
option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR.
.PP
Polygon items are different from other items such as rectangles, ovals
and arcs in that interior points are considered to be
.QW inside
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
\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







<








<


<




<


<






<


<





<

|
<





<


<







1859
1860
1861
1862
1863
1864
1865

1866
1867
1868
1869
1870
1871
1872
1873

1874
1875

1876
1877
1878
1879

1880
1881

1882
1883
1884
1885
1886
1887

1888
1889

1890
1891
1892
1893
1894

1895
1896

1897
1898
1899
1900
1901

1902
1903

1904
1905
1906
1907
1908
1909
1910
\fB\-anchor\fR	\fB\-fill\fR
\fB\-activefill\fR	\fB\-disabledfill\fR
\fB\-stipple\fR	\fB\-activestipple\fR
\fB\-disabledstipple\fR	\fB\-state\fR
\fB\-tags\fR
.DE
The following extra options are supported for text items:

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

.TP
\fB\-font \fIfontName\fR

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

.TP
\fB\-justify \fIhow\fR

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

.TP
\fB\-text \fIstring\fR

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

.TP
\fB\-underline \fI\fR

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

.TP
\fB\-width \fIlineLength\fR

Specifies a maximum line length for the text, in any of the forms
described in the \fBCOORDINATES\fR section above.
If this option is zero (the default) the text is broken into
lines only at newline characters.
However, if this option is non-zero then any line that would
be longer than \fIlineLength\fR is broken just before a space
character to make the line shorter than \fIlineLength\fR; the
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
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.







<








<








<








|







1935
1936
1937
1938
1939
1940
1941

1942
1943
1944
1945
1946
1947
1948
1949

1950
1951
1952
1953
1954
1955
1956
1957

1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
The following standard options are supported by window items:
.DS
.ta 3i
\fB\-anchor\fR	\fB\-state\fR
\fB\-tags\fR
.DE
The following extra options are supported for window items:

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

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

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

Changes to doc/checkbutton.n.

193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
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]







<

|
<




<


<












<


<



<


<





<


<






<


<



<


<







193
194
195
196
197
198
199

200
201

202
203
204
205

206
207

208
209
210
211
212
213
214
215
216
217
218
219

220
221

222
223
224

225
226

227
228
229
230
231

232
233

234
235
236
237
238
239

240
241

242
243
244

245
246

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

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

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

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

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

.TP
\fIpathName \fBdeselect\fR

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

.TP
\fIpathName \fBflash\fR

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

.TP
\fIpathName \fBinvoke\fR

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

.TP
\fIpathName \fBselect\fR

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

.TP
\fIpathName \fBtoggle\fR

Toggles the selection state of the button, redisplaying it and
modifying its associated variable to reflect the new state.
.SH BINDINGS
.PP
Tk automatically creates class bindings for checkbuttons that give them
the following default behavior:
.IP [1]
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
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:







|
|
|
|
|









273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
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:

Changes to doc/chooseColor.n.

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
\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:







<

|
<



<

|
<


<

|
<










|






14
15
16
17
18
19
20

21
22

23
24
25

26
27

28
29

30
31

32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
\fBtk_chooseColor \fR?\fIoption value ...\fR?
.BE
.SH DESCRIPTION
.PP
The procedure \fBtk_chooseColor\fR pops up a dialog box for the
user to select a color. The following \fIoption\-value\fR pairs are
possible as command line arguments:

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

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

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

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

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

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

Changes to doc/chooseDirectory.n.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
\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 Mac OS X.
.\" 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 Mac OS X.
.\" 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 Mac OS X, 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:







<

|
<





<

|
<








<

|
<


<

|
<



<

|
<



<

|
<






|

|

|







12
13
14
15
16
17
18

19
20

21
22
23
24
25

26
27

28
29
30
31
32
33
34
35

36
37

38
39

40
41

42
43
44

45
46

47
48
49

50
51

52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
\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:

.TP
\fB\-command\fR \fIstring\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 Mac OS X.

.TP
\fB\-initialdir\fR \fIdirname\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.

.TP
\fB\-message\fR \fIstring\fR

Specifies a message to include in the client area of the dialog.
This is only available on Mac OS X.

.TP
\fB\-mustexist\fR \fIboolean\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.

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

Makes \fIwindow\fR the logical parent of the dialog. The dialog
is displayed on top of its parent window. On Mac OS X, this
turns the file dialog into a sheet attached to the parent window.

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

Specifies a string to display as the title of the dialog box. If this
option is not specified, then a default title will be displayed.
.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:

Changes to doc/clipboard.n.

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
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







<

|







23
24
25
26
27
28
29

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

.TP
\fBclipboard append\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-format\fR \fIformat\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-\|\-\fR? \fIdata\fR
.
Appends \fIdata\fR to the clipboard on \fIwindow\fR's
display in the form given by \fItype\fR with the representation given
by \fIformat\fR and claims ownership of the clipboard on \fIwindow\fR's
display.
.RS
.PP
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
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







<

|





<

|







67
68
69
70
71
72
73

74
75
76
77
78
79
80

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

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

.TP
\fBclipboard get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-type\fR \fItype\fR?
.
Retrieve data from the clipboard on \fIwindow\fR's display.
\fIWindow\fR defaults to
.QW . .
\fIType\fR specifies the form in which
the data is to be returned and should be an atom name such as \fBSTRING\fR
or \fBFILE_NAME\fR.  \fIType\fR defaults to \fBSTRING\fR.  This command is
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
# it produces a script that recreates the item(s) when executed
proc getItemConfig {canvas tag} {
   set script {}
   foreach item [$canvas find withtag $tag] {
      append script {$canvas create } [$canvas type $item]
      append script { } [$canvas coords $item] { }
      foreach config [$canvas itemconf $item] {
         lassign $config name - - - value
         append script [list $name $value] { }
      }
      append script \en
   }
   return [string trim $script]
}

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







|










|


|







|










118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
# it produces a script that recreates the item(s) when executed
proc getItemConfig {canvas tag} {
   set script {}
   foreach item [$canvas find withtag $tag] {
      append script {$canvas create } [$canvas type $item]
      append script { } [$canvas coords $item] { }
      foreach config [$canvas itemconf $item] {
         lassign $config name \- \- \- value
         append script [list $name $value] { }
      }
      append script \en
   }
   return [string trim $script]
}

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

Changes to doc/colors.n.

892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913

914
915
916
917
918
919
920
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







|














>







892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
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 constrasts
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

Changes to doc/console.n.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
'\"
'\" 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.













|











|






|
<

<


<



<


<


<


<


<


<











<


<


<


<







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

34

35
36

37
38
39

40
41

42
43

44
45

46
47

48
49

50
51
52
53
54
55
56
57
58
59
60

61
62

63
64

65
66

67
68
69
70
71
72
73
'\"
'\" Copyright (c) 2001 Donal K. Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH console n 8.4 Tk "Tk Built-In Commands"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
console \- Control the console on systems without a real console
.SH SYNOPSIS
\fBconsole\fR \fIsubcommand\fR ?\fIarg ...\fR?
.BE
.SH DESCRIPTION
.PP
The console window is a replacement for a real console to allow input
and output on the standard I/O channels on platforms that do not have
a real console.  It is implemented as a separate interpreter with the
Tk toolkit loaded, and control over this interpreter is given through
the \fBconsole\fR command.  The behaviour of the console window is
defined mainly through the contents of the \fIconsole.tcl\fR file in
the Tk library. Except for TkAqua, this command is not available when
Tk is loaded into a tclsh interpreter with
.QW "\fBpackage require tk\fR" ,
as a conventional terminal is expected to be present in that case.
In TkAqua, this command is disabled when there is a startup script
and stdin is \fB/dev/null\fR (as is the case e.g. when a bundled application
embedding Tk is started by the macOS Launcher).  To enable the command
in that case, define the environment variable \fBTK_CONSOLE\fR.  This can be
done by modifying the Info.plist file by adding the LSEnvironment key
to the main dict and setting its value to be a dict with the key \fBTK_CONSOLE\fR.

.PP

.TP
\fBconsole eval \fIscript\fR

Evaluate the \fIscript\fR argument as a Tcl script in the console
interpreter.  The normal interpreter is accessed through the
\fBconsoleinterp\fR command in the console interpreter.

.TP
\fBconsole hide\fR

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

.TP
\fBconsole show\fR

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

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

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

.TP
\fBconsoleinterp eval \fIscript\fR

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

.TP
\fBconsoleinterp record \fIscript\fR

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

Changes to doc/cursors.n.

97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
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







<







97
98
99
100
101
102
103

104
105
106
107
108
109
110
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
size_we
uparrow
wait
.CE
.RE
.TP
\fBMac OS X\fR
.
On Mac OS X systems, the following cursors are mapped to native cursors:
.RS
.CS
arrow
top_left_arrow
left_ptr
cross







<







127
128
129
130
131
132
133

134
135
136
137
138
139
140
size_we
uparrow
wait
.CE
.RE
.TP
\fBMac OS X\fR

On Mac OS X systems, the following cursors are mapped to native cursors:
.RS
.CS
arrow
top_left_arrow
left_ptr
cross

Changes to doc/dialog.n.

15
16
17
18
19
20
21

22
23
24

25
26

27
28

29
30
31
32
33

34
35
36
37
38
39

40
41
42
43
44
45
46
47
\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 less than zero 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).







>
|


>
|

>
|

>
|




>
|



|

>
|







15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
\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:
.TP
\fIwindow\fR
Name of top-level window to use for dialog.  Any existing window
by this name is destroyed.
.TP
\fItitle\fR
Text to appear in the window manager's title bar for the dialog.
.TP
\fItext\fR
Message to appear in the top portion of the dialog box.
.TP
\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.
.TP
\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.
.TP
\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).

Changes to doc/entry.n.

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
.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







|







9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
.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\fR \fIpathName \fR?\fIoptions\fR?
.SO
\-background	\-highlightthickness	\-selectbackground
\-borderwidth	\-insertbackground	\-selectborderwidth
\-cursor	\-insertborderwidth	\-selectforeground
\-exportselection	\-insertofftime	\-takefocus
\-font	\-insertontime	\-textvariable
\-foreground	\-insertwidth	\-xscrollcommand
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
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 less than or equal to 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







|







73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
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
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
\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







|

|







172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
\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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
.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.







<




<




<





<




<




<





<


















<


<








<

|
<




<


<












<


<







<


<

<


<


<


<

<


<


<

|
<





<






<








<


<





<











<





<





<



|
<







<













<


<




<


<






<









|
<




<





<







197
198
199
200
201
202
203

204
205
206
207

208
209
210
211

212
213
214
215
216

217
218
219
220

221
222
223
224

225
226
227
228
229

230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247

248
249

250
251
252
253
254
255
256
257

258
259

260
261
262
263

264
265

266
267
268
269
270
271
272
273
274
275
276
277

278
279

280
281
282
283
284
285
286

287
288

289

290
291

292
293

294
295

296

297
298

299
300

301
302

303
304
305
306
307

308
309
310
311
312
313

314
315
316
317
318
319
320
321

322
323

324
325
326
327
328

329
330
331
332
333
334
335
336
337
338
339

340
341
342
343
344

345
346
347
348
349

350
351
352
353

354
355
356
357
358
359
360

361
362
363
364
365
366
367
368
369
370
371
372
373

374
375

376
377
378
379

380
381

382
383
384
385
386
387

388
389
390
391
392
393
394
395
396
397

398
399
400
401

402
403
404
405
406

407
408
409
410
411
412
413
.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:

.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.

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

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

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

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

.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.

.TP
\fIpathName \fBget\fR

Returns the entry's string.

.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.

.TP
\fIpathName \fBindex\fI index\fR

Returns the numerical index corresponding to \fIindex\fR.

.TP
\fIpathName \fBinsert \fIindex string\fR

Insert the characters of \fIstring\fR just before the character
indicated by \fIindex\fR.  Returns an empty string.

.TP
\fIpathName \fBscan\fR \fIoption 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

.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\fR \fIend\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

.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.

.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\fR \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.

Changes to doc/event.n.

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
.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<Shift-Button-2>\fR or \fB<<Paste>>\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<<AltUnderlined>>\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<<Invoke>>\fR
.
This can be sent to some widgets (e.g. button, listbox, menu) as an
alternative to <space>.
.TP
\fB<<ListboxSelect>>\fR
.
This is sent to a listbox when the set of selected item(s) in the
listbox is updated.
.TP
\fB<<MenuSelect>>\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<<Modified>>\fR
.
This is sent to a text widget when the contents of the widget are
changed.
.TP
\fB<<Selection>>\fR
.
This is sent to a text widget when the selection in the widget is
changed.
.TP
\fB<<ThemeChanged>>\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<<TkWorldChanged>>\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<<TraverseIn>>\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<<TraverseOut>>\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<<UndoStack>>\fR
.
This is sent to a text widget when its undo stack or redo stack becomes
empty or unempty.
.TP
\fB<<WidgetViewSync>>\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<<Clear>>\fR
.
Delete the currently selected widget contents.
.TP
\fB<<Copy>>\fR
.
Copy the currently selected widget contents to the clipboard.
.TP
\fB<<Cut>>\fR
.
Move the currently selected widget contents to the clipboard.
.TP
\fB<<LineEnd>>\fR
.
Move to the end of the line in the current widget while deselecting any
selected contents.
.TP







<


<









<

|
<










<


<




















<


<


















<


<




<


<




<


<




<


<



<


<



<


<









<


<














<


<




<


<



<


<




<


<






<


<






<


<




<


<




<


<






<


<





<


<






<


<



<


<



<


<









<


<





<


<

|





<


<





<


<




<


<


















<


<










<


<




















<







<




<




<




<




<




<














<






<






<




<










<



<



<







16
17
18
19
20
21
22

23
24

25
26
27
28
29
30
31
32
33

34
35

36
37
38
39
40
41
42
43
44
45

46
47

48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

68
69

70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

88
89

90
91
92
93

94
95

96
97
98
99

100
101

102
103
104
105

106
107

108
109
110

111
112

113
114
115

116
117

118
119
120
121
122
123
124
125
126

127
128

129
130
131
132
133
134
135
136
137
138
139
140
141
142

143
144

145
146
147
148

149
150

151
152
153

154
155

156
157
158
159

160
161

162
163
164
165
166
167

168
169

170
171
172
173
174
175

176
177

178
179
180
181

182
183

184
185
186
187

188
189

190
191
192
193
194
195

196
197

198
199
200
201
202

203
204

205
206
207
208
209
210

211
212

213
214
215

216
217

218
219
220

221
222

223
224
225
226
227
228
229
230
231

232
233

234
235
236
237
238

239
240

241
242
243
244
245
246
247

248
249

250
251
252
253
254

255
256

257
258
259
260

261
262

263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280

281
282

283
284
285
286
287
288
289
290
291
292

293
294

295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314

315
316
317
318
319
320
321

322
323
324
325

326
327
328
329

330
331
332
333

334
335
336
337

338
339
340
341

342
343
344
345
346
347
348
349
350
351
352
353
354
355

356
357
358
359
360
361

362
363
364
365
366
367

368
369
370
371

372
373
374
375
376
377
378
379
380
381

382
383
384

385
386
387

388
389
390
391
392
393
394
.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:

.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.

.TP
\fBevent delete <<\fIvirtual\fB>> \fR?\fIsequence\fR \fIsequence ...\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.

.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<Shift-Button-2>\fR or \fB<<Paste>>\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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.TP
\fB\-time\fI integer\fR

\fIInteger\fR must be an integer value;  it specifies the \fItime\fR field
for the event. Additonally 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.

.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.

.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.

.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

.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.

.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<<AltUnderlined>>\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<<Invoke>>\fR

This can be sent to some widgets (e.g. button, listbox, menu) as an
alternative to <space>.
.TP
\fB<<ListboxSelect>>\fR

This is sent to a listbox when the set of selected item(s) in the
listbox is updated.
.TP
\fB<<MenuSelect>>\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<<Modified>>\fR

This is sent to a text widget when the contents of the widget are
changed.
.TP
\fB<<Selection>>\fR

This is sent to a text widget when the selection in the widget is
changed.
.TP
\fB<<ThemeChanged>>\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<<TkWorldChanged>>\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<<TraverseIn>>\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<<TraverseOut>>\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<<UndoStack>>\fR

This is sent to a text widget when its undo stack or redo stack becomes
empty or unempty.
.TP
\fB<<WidgetViewSync>>\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<<Clear>>\fR

Delete the currently selected widget contents.
.TP
\fB<<Copy>>\fR

Copy the currently selected widget contents to the clipboard.
.TP
\fB<<Cut>>\fR

Move the currently selected widget contents to the clipboard.
.TP
\fB<<LineEnd>>\fR
.
Move to the end of the line in the current widget while deselecting any
selected contents.
.TP
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
.TP
\fB<<NextWord>>\fR
.
Move to the next group of items (i.e., visible word) in the current widget
while deselecting any selected contents.
.TP
\fB<<Paste>>\fR
.
Replace the currently selected widget contents with the contents of
the clipboard.
.TP
\fB<<PasteSelection>>\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<<PrevChar>>\fR
.
Move to the previous item (i.e., visible character) in the current widget
while deselecting any selected contents.
.TP
\fB<<PrevLine>>\fR
.
Move to the previous line in the current widget while deselecting any selected
contents.
.TP
\fB<<PrevPara>>\fR
.
Move to the previous paragraph in the current widget while deselecting any
selected contents.
.TP
\fB<<PrevWindow>>\fR
.
Traverse to the previous window.
.TP
\fB<<PrevWord>>\fR
.
Move to the previous group of items (i.e., visible word) in the current widget
while deselecting any selected contents.
.TP
\fB<<Redo>>\fR
.
Redo one undone action.
.TP
\fB<<SelectAll>>\fR
.
Set the range of selected contents to the complete widget.
.TP
\fB<<SelectLineEnd>>\fR







<




<



















<








<







414
415
416
417
418
419
420

421
422
423
424

425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443

444
445
446
447
448
449
450
451

452
453
454
455
456
457
458
.TP
\fB<<NextWord>>\fR
.
Move to the next group of items (i.e., visible word) in the current widget
while deselecting any selected contents.
.TP
\fB<<Paste>>\fR

Replace the currently selected widget contents with the contents of
the clipboard.
.TP
\fB<<PasteSelection>>\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<<PrevChar>>\fR
.
Move to the previous item (i.e., visible character) in the current widget
while deselecting any selected contents.
.TP
\fB<<PrevLine>>\fR
.
Move to the previous line in the current widget while deselecting any selected
contents.
.TP
\fB<<PrevPara>>\fR
.
Move to the previous paragraph in the current widget while deselecting any
selected contents.
.TP
\fB<<PrevWindow>>\fR

Traverse to the previous window.
.TP
\fB<<PrevWord>>\fR
.
Move to the previous group of items (i.e., visible word) in the current widget
while deselecting any selected contents.
.TP
\fB<<Redo>>\fR

Redo one undone action.
.TP
\fB<<SelectAll>>\fR
.
Set the range of selected contents to the complete widget.
.TP
\fB<<SelectLineEnd>>\fR

Changes to doc/focus.n.

51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
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.







<








<









|
<





<








|
<







51
52
53
54
55
56
57

58
59
60
61
62
63
64
65

66
67
68
69
70
71
72
73
74
75

76
77
78
79
80

81
82
83
84
85
86
87
88
89

90
91
92
93
94
95
96
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\fR \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\fR \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.
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
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 <Tab> {
   if {!$traverseToMiddle} {
      \fBfocus\fR .after
      break
   }
}
bind .after <Shift-Tab> {
   if {!$traverseToMiddle} {
      \fBfocus\fR .before
      break
   }
}
\fBfocus\fR .before
.CE
.SH KEYWORDS
events, focus, keyboard, top-level, window manager
'\" Local Variables:
'\" mode: nroff
'\" End:







<

|
|
|
|
|







|












105
106
107
108
109
110
111

112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
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:

.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 <Tab> {
   if {!$traverseToMiddle} {
      \fBfocus\fR .after
      break
   }
}
bind .after <Shift\-Tab> {
   if {!$traverseToMiddle} {
      \fBfocus\fR .before
      break
   }
}
\fBfocus\fR .before
.CE
.SH KEYWORDS
events, focus, keyboard, top-level, window manager
'\" Local Variables:
'\" mode: nroff
'\" End:

Changes to doc/focusNext.n.

8
9
10
11
12
13
14
15
16

17

18
19
20
21
22
23
24
25
26
.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







<

>

>

<







8
9
10
11
12
13
14

15
16
17
18
19

20
21
22
23
24
25
26
.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

\fBtk_focusNext \fIwindow\fR
.sp
\fBtk_focusPrev \fIwindow\fR
.sp
\fBtk_focusFollowsMouse\fR

.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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
\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:







<
|








45
46
47
48
49
50
51

52
53
54
55
56
57
58
59
60
\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.

Note: 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:

Changes to doc/font.n.

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
.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/Mac OS X, 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







<


















<




















<









<

|







<






<














<











<


<







16
17
18
19
20
21
22

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

61
62
63
64
65
66
67
68
69

70
71
72
73
74
75
76
77
78

79
80
81
82
83
84

85
86
87
88
89
90
91
92
93
94
95
96
97
98

99
100
101
102
103
104
105
106
107
108
109

110
111

112
113
114
115
116
117
118
.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:

.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.

.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/Mac OS X, 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

.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.

.TP
\fBfont delete\fR \fIfontname\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.

.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.

.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.

.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.

.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
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
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
\fBMac OS X\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







<

|



<

|



<







<

|
















<
















<



















<







<


<






<


<


<


<







>
|
>

>
|
>

>
|
>

>
|
>

>
|
>

>
|
>

>
|
>

>
|
>

>
|
>










<



<











<







196
197
198
199
200
201
202

203
204
205
206
207

208
209
210
211
212

213
214
215
216
217
218
219

220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237

238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253

254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272

273
274
275
276
277
278
279

280
281

282
283
284
285
286
287

288
289

290
291

292
293

294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345

346
347
348

349
350
351
352
353
354
355
356
357
358
359

360
361
362
363
364
365
366
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.

.TP
\fB\-ascent        \0\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.

.TP
\fB\-descent       \0\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.

.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.

.TP
\fB\-fixed          \0\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:

.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.

.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

.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.

.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.

.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.

.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.
.TP
\fBTkDefaultFont\fR
.
This font is the default for all GUI items not otherwise specified.
.TP
\fBTkTextFont\fR
.
This font should be used for user text in entry widgets, listboxes etc.
.TP
\fBTkFixedFont\fR
.
This font is the standard fixed-width font.
.TP
\fBTkMenuFont\fR
.
This font is used for menu items.
.TP
\fBTkHeadingFont\fR
.
This font should be used for column headings in lists and tables.
.TP
\fBTkCaptionFont\fR
.
This font should be used for window and dialog caption bars.
.TP
\fBTkSmallCaptionFont\fR
.
This font should be used for captions on contained windows or tool dialogs.
.TP
\fBTkIconFont\fR
.
This font should be used for icon captions.
.TP
\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
\fBMac OS X\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
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
.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:







|


|
|
|

|
|
|
|










382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
.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}:\\t {} \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:

Changes to doc/fontchooser.n.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

16

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
'\"
'\" Copyright (c) 2008 Daniel A. Steffen <das@users.sourceforge.net>
'\"
'\" 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 (Mac OS X) 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<<TkFontchooserVisibility>>\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<<TkFontchooserFontChanged>>\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













<

>

>

<














<





<





<







<


<



<


<


<


<





<


<









<


<







<








<







1
2
3
4
5
6
7
8
9
10
11
12
13

14
15
16
17
18

19
20
21
22
23
24
25
26
27
28
29
30
31
32

33
34
35
36
37

38
39
40
41
42

43
44
45
46
47
48
49

50
51

52
53
54

55
56

57
58

59
60

61
62
63
64
65

66
67

68
69
70
71
72
73
74
75
76

77
78

79
80
81
82
83
84
85

86
87
88
89
90
91
92
93

94
95
96
97
98
99
100
'\"
'\" Copyright (c) 2008 Daniel A. Steffen <das@users.sourceforge.net>
'\"
'\" 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

\fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value ...\fR?
.sp
\fBtk fontchooser\fR \fBshow\fR
.sp
\fBtk fontchooser\fR \fBhide\fR

.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 (Mac OS X) 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:

.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).

.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.

.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"

.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.

.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.

.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.

.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).

.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<<TkFontchooserVisibility>>\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<<TkFontchooserFontChanged>>\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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
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<<TkFontchooserVisibility>>\fR \e
            [list fontchooserVisibility .b]
    foreach w {.t1 .t2} {
        text $w -width 20 -height 4 -borderwidth 1 -relief solid
        bind $w <FocusIn> [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:







|
|

|


|



|
|




|



|
|



|
|


|










135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
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<<TkFontchooserVisibility>>\fR \\
            [list fontchooserVisibility .b]
    foreach w {.t1 .t2} {
        text $w \-width 20 \-height 4 \-borderwidth 1 \-relief solid
        bind $w <FocusIn> [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] \\
            \-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:

Changes to doc/frame.n.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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







|







8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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\fR \fIpathName\fR ?\fIoptions\fR?
.SO
\-borderwidth	\-highlightcolor	\-pady
\-cursor	\-highlightthickness	\-relief
\-highlightbackground	\-padx	\-takefocus
.SE
.SH "WIDGET-SPECIFIC OPTIONS"
.OP \-background background Background
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
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 less than or equal
to 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 "8.7, TIP262"
This specifies how to draw the background image (see







|
|







62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
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 "8.7, TIP262"
This specifies how to draw the background image (see
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
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 less than or equal
to 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







|
|







86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
\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







<

|





<







123
124
125
126
127
128
129

130
131
132
133
134
135
136

137
138
139
140
141
142
143
\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:

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

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

Changes to doc/getOpenFile.n.

30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
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 Mac OS X.
.\" 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 Mac OS X, 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 Mac OS X.
.\" 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 Mac OS X, 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







<

|
<





<

|
<




<

|








<

|









<

|









<

|


<

|



<

|


<

|




<

|



<

|







30
31
32
33
34
35
36

37
38

39
40
41
42
43

44
45

46
47
48
49

50
51
52
53
54
55
56
57
58
59

60
61
62
63
64
65
66
67
68
69
70

71
72
73
74
75
76
77
78
79
80
81

82
83
84
85

86
87
88
89
90

91
92
93
94

95
96
97
98
99
100

101
102
103
104
105

106
107
108
109
110
111
112
113
114
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:

.TP
\fB\-command\fR \fIstring\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 Mac OS X.

.TP
\fB\-confirmoverwrite\fR \fIboolean\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.

.TP
\fB\-defaultextension\fR \fIextension\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 Mac OS X, 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.

.TP
\fB\-filetypes\fR \fIfilePatternList\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.

.TP
\fB\-initialdir\fR \fIdirectory\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.

.TP
\fB\-initialfile\fR \fIfilename\fR
.
Specifies a filename to be displayed in the dialog when it pops up.

.TP
\fB\-message\fR \fIstring\fR
.
Specifies a message to include in the client area of the dialog.
This is only available on Mac OS X.

.TP
\fB\-multiple\fR \fIboolean\fR
.
Allows the user to choose multiple files from the Open dialog.

.TP
\fB\-parent\fR \fIwindow\fR
.
Makes \fIwindow\fR the logical parent of the file dialog. The file
dialog is displayed on top of its parent window. On Mac OS X, this
turns the file dialog into a sheet attached to the parent window.

.TP
\fB\-title\fR \fItitleString\fR
.
Specifies a string to display as the title of the dialog box. If this
option is not specified, then a default title is displayed.

.TP
\fB\-typevariable\fR \fIvariableName\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
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
    {{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:







|












188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
    {{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:

Changes to doc/grab.n.

8
9
10
11
12
13
14
15
16

17
18
19
20
21
22
23
24
25
.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







<

>

<







8
9
10
11
12
13
14

15
16
17

18
19
20
21
22
23
24
.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

\fBgrab \fR?\fB\-global\fR? \fIwindow\fR
.sp
\fBgrab \fIoption \fR?\fIarg \fR...?

.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
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
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







<

<


<






<


<


<


<







<


<







79
80
81
82
83
84
85

86

87
88

89
90
91
92
93
94

95
96

97
98

99
100

101
102
103
104
105
106
107

108
109

110
111
112
113
114
115
116
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.

.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.

.TP
\fBgrab release \fIwindow\fR

Releases the grab on \fIwindow\fR if there is one, otherwise does
nothing.  Returns an empty string.

.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.

.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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
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:







|
|
|









132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
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:

Changes to doc/grid.n.

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
\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.







<






<













<







24
25
26
27
28
29
30

31
32
33
34
35
36

37
38
39
40
41
42
43
44
45
46
47
48
49

50
51
52
53
54
55
56
\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.

.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.

.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.

.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.
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
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.







|

<












<












<







<






<








<







<









<









<








<








<







78
79
80
81
82
83
84
85
86

87
88
89
90
91
92
93
94
95
96
97
98

99
100
101
102
103
104
105
106
107
108
109
110

111
112
113
114
115
116
117

118
119
120
121
122
123

124
125
126
127
128
129
130
131

132
133
134
135
136
137
138

139
140
141
142
143
144
145
146
147

148
149
150
151
152
153
154
155
156

157
158
159
160
161
162
163
164

165
166
167
168
169
170
171
172

173
174
175
176
177
178
179
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 "\-option value"
pairs.

.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

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
.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<<NoManagedChild>>\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







<
<
<
<
<
<
<
<
<
<












|
|



<









<



|
|
|
|
<












<
<

<
<










|
|
|







189
190
191
192
193
194
195










196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212

213
214
215
216
217
218
219
220
221

222
223
224
225
226
227
228

229
230
231
232
233
234
235
236
237
238
239
240


241


242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
.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










.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<<NoManagedChild>>\fR to the container; the container
may choose to resize itself (or otherwise respond) to such a change.
.VE "TIP 518"
.RE

.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.

.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.

.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.


Propagation is enabled by default.


.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
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336







337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356

357

358
359
360
361

362

363
364

365

366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
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<<NoManagedChild>>\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







<












|
|
|


<







|
>
>
>
>
>
>
>




















>
|
>

|
|
|
>
|
>


>
|
>
















|
|







272
273
274
275
276
277
278

279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295

296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
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.

.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<<NoManagedChild>>\fR to the container; the container
may choose to resize itself (or otherwise respond) to such a change.
.VE "TIP 518"
.RE

.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.
.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.
.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
.TP
\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.
.TP
\fBx\fR
.
This leaves an empty column between the \fIcontent\fR on the left and
the \fIcontent\fR on the right.
.TP
\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
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
.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:







|
|
|


|
|


|
|







|
|
|

|
|








437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
.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:

Changes to doc/image.n.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

102
103
104
105

106
107
108
109

110
111
112
113
114
115
116
117
.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







|






<


<

















<


<










<


<


<


<


<


<

<


<


<


<



<


<











>
|



>
|



>
|







8
9
10
11
12
13
14
15
16
17
18
19
20
21

22
23

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

41
42

43
44
45
46
47
48
49
50
51
52

53
54

55
56

57
58

59
60

61
62

63

64
65

66
67

68
69

70
71
72

73
74

75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
.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\fR \fIoption \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:

.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).

.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.

.TP
\fBimage height \fIname\fR

Returns a decimal string giving the height of image \fIname\fR
in pixels.

.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.

.TP
\fBimage names\fR

Returns a list containing the names of all existing images.

.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).

.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).

.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.
.TP
\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.
.TP
\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.
.TP
\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

Changes to doc/label.n.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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







|







8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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\fR \fIpathName \fR?\fIoptions\fR?
.SO
\-activebackground	\-disabledforeground	\-padx
\-activeforeground	\-font	\-pady
\-anchor	\-foreground	\-relief
\-background	\-highlightbackground	\-takefocus
\-bitmap	\-highlightcolor	\-text
\-borderwidth	\-highlightthickness	\-textvariable
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
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:







<

|
<




<


<




















|
|
|
|



|
|
|
|
|








76
77
78
79
80
81
82

83
84

85
86
87
88

89
90

91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
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:

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

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

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

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

Changes to doc/labelframe.n.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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"







|







8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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\fR \fIpathName\fR ?\fIoptions\fR?
.SO
\-borderwidth	\-highlightbackground	\-pady
\-cursor	\-highlightcolor	\-relief
\-font	\-highlightthickness	\-takefocus
\-foreground	\-padx	\-text
.SE
.SH "WIDGET-SPECIFIC OPTIONS"
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
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 less than or equal to 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.







|







43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
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.
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
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 less than or equal to 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







|







67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
.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







<

|
<




<


<







97
98
99
100
101
102
103

104
105

106
107
108
109

110
111

112
113
114
115
116
117
118
.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:

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

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

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

Query or modify the configuration options of the widget.
If no \fIoption\fR is specified, returns a list describing all of
the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
information on the format of this list).  If \fIoption\fR is specified
with no \fIvalue\fR, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no \fIoption\fR is specified).  If
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
.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







|
|
|
|







128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
.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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
    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:







|
|
|













153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
    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:

Changes to doc/listbox.n.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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







|







8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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\fR \fIpathName \fR?\fIoptions\fR?
.SO
\-background	\-borderwidth	\-cursor
\-disabledforeground	\-exportselection	\-font
\-foreground	\-highlightbackground	\-highlightcolor
\-highlightthickness	\-justify	\-relief
\-selectbackground	\-selectborderwidth	\-selectforeground
\-setgrid	\-takefocus	\-xscrollcommand
91
92
93
94
95
96
97

98

99
100

101

102
103
104
105

106

107
108

109

110
111
112
113

114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
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
.







>
|
>


>
|
>




>
|
>


>
|
>




>
|




|


















<

|







<

|













<

|





<















<







<







<











<






<







<






<















<





<





<






<







<





<

|







91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

147
148
149
150
151
152
153
154
155

156
157
158
159
160
161
162
163
164
165
166
167
168
169
170

171
172
173
174
175
176
177

178
179
180
181
182
183
184
185
186
187
188
189
190
191
192

193
194
195
196
197
198
199

200
201
202
203
204
205
206

207
208
209
210
211
212
213
214
215
216
217

218
219
220
221
222
223

224
225
226
227
228
229
230

231
232
233
234
235
236

237
238
239
240
241
242
243
244
245
246
247
248
249
250
251

252
253
254
255
256

257
258
259
260
261

262
263
264
265
266
267

268
269
270
271
272
273
274

275
276
277
278
279

280
281
282
283
284
285
286
287
288
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:
.TP 12
\fInumber\fR
.
Specifies the element as a numerical index, where 0 corresponds
to the first element in the listbox.
.TP 12
\fBactive\fR
.
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.
.TP 12
\fBanchor\fR
.
Indicates the anchor point for the selection, which is set with the
\fBselection anchor\fR widget command.
.TP 12
\fBend\fR
.
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.
.TP 12
\fB@\fIx\fB,\fIy\fR
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.
.LP
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:

.TP
\fIpathName \fBactivate\fR \fIindex\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.

.TP
\fIpathName \fBbbox\fR \fIindex\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.

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

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

.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.

.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.

.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.

.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).

.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.

.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.

.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

.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.

.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.

.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.

.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

.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.

.TP
\fIpathName \fBscan\fR \fIoption 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
.
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
\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







<









<







298
299
300
301
302
303
304

305
306
307
308
309
310
311
312
313

314
315
316
317
318
319
320
\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

.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.

.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
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
.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







<





<







342
343
344
345
346
347
348

349
350
351
352
353

354
355
356
357
358
359
360
.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

.TP
\fIpathName \fBsize\fR
.
Returns a decimal string indicating the total number of elements
in the listbox.

.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
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
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.







<









<







395
396
397
398
399
400
401

402
403
404
405
406
407
408
409
410

411
412
413
414
415
416
417
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

.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.

Changes to doc/loadTk.n.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
'\"
'\" 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.













|




















|


















|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
'\"
'\" 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\fR \fIwindowId\fR? ?\fB\-display\fR \fIdisplayName\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\fR \fB.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\fR \fIwindowId\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.

Changes to doc/menu.n.

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
.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"







|
|
<







9
10
11
12
13
14
15
16
17

18
19
20
21
22
23
24
.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\fR \fIpathName \fR?\fIoptions\fR?
\fBtk_menuSetFocus\fR \fIpathName\fR

.SO
\-activebackground	\-borderwidth	\-foreground
\-activeborderwidth	\-cursor	\-relief
\-activeforeground	\-disabledforeground	\-takefocus
\-background	\-font	\-activerelief
.SE
.SH "WIDGET-SPECIFIC OPTIONS"
309
310
311
312
313
314
315

316

317
318
319

320

321
322
323

324

325

326

327
328
329
330
331
332






333

334
335
336
337

338

339
340
341

342

343
344

345

346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
\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







>
|
>



>
|
>



>
|
>

>
|
>






>
>
>
>
>
>
|
>




>
|
>



>
|
>


>
|
>













<






|


<













<







<









<















<








<







<













<








<




|
<










<












<














<









<







<







<





<








<











<







|









<









<












<








<





<










<








<









<







<












<






<





<






<






<





<








<










<

















<










<







<







308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378

379
380
381
382
383
384
385
386
387

388
389
390
391
392
393
394
395
396
397
398
399
400

401
402
403
404
405
406
407

408
409
410
411
412
413
414
415
416

417
418
419
420
421
422
423
424
425
426
427
428
429
430
431

432
433
434
435
436
437
438
439

440
441
442
443
444
445
446

447
448
449
450
451
452
453
454
455
456
457
458
459

460
461
462
463
464
465
466
467

468
469
470
471
472

473
474
475
476
477
478
479
480
481
482

483
484
485
486
487
488
489
490
491
492
493
494

495
496
497
498
499
500
501
502
503
504
505
506
507
508

509
510
511
512
513
514
515
516
517

518
519
520
521
522
523
524

525
526
527
528
529
530
531

532
533
534
535
536

537
538
539
540
541
542
543
544

545
546
547
548
549
550
551
552
553
554
555

556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572

573
574
575
576
577
578
579
580
581

582
583
584
585
586
587
588
589
590
591
592
593

594
595
596
597
598
599
600
601

602
603
604
605
606

607
608
609
610
611
612
613
614
615
616

617
618
619
620
621
622
623
624

625
626
627
628
629
630
631
632
633

634
635
636
637
638
639
640

641
642
643
644
645
646
647
648
649
650
651
652

653
654
655
656
657
658

659
660
661
662
663

664
665
666
667
668
669

670
671
672
673
674
675

676
677
678
679
680

681
682
683
684
685
686
687
688

689
690
691
692
693
694
695
696
697
698

699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715

716
717
718
719
720
721
722
723
724
725

726
727
728
729
730
731
732

733
734
735
736
737
738
739
\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:
.TP 12
\fBactive\fR
.
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.
.TP 12
\fBend\fR
.
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.
.TP 12
\fBlast\fR
.
Same as \fBend\fR.
.TP 12
\fB{}\fR
.
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.
.TP 12
\fBnone\fR
.
Same as \fB{}\fR
This form is deprecated and may not be abbreviated.
.TP 12
\fB@\fIx\fB,\fIy\fR
.
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.
.TP 12
\fInumber\fR
.
Specifies the entry numerically, where 0 corresponds
to the top-most entry of the menu, 1 to the entry below it, and
so on.
.TP 12
\fIid\fR
.
If the index does not satisfy one of the above forms then the menu is
searched for an entry with the specified id.
.TP 12
\fIpattern\fR
.
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:

.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 \fBnone\fR, or if the specified entry is
disabled, then the menu ends up with no active entry.
Returns an empty string.

.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.

.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.

.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.

.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.

.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).

.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.

.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).

.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.

.TP
\fIpathName \fBindex \fIindex\fR
.
Returns the numerical index corresponding to \fIindex\fR, or
\fB{}\fR if \fIindex\fR was specified as \fB{}\fR or \fBnone\fR.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.
This option is not available for separator or tear-off entries.
.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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

Changes to doc/menubutton.n.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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







|







8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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\fR \fIpathName \fR?\fIoptions\fR?
.SO
\-activebackground	\-disabledforeground	\-padx
\-activeforeground	\-font	\-pady
\-anchor	\-foreground	\-relief
\-background	\-highlightbackground	\-takefocus
\-bitmap	\-highlightcolor	\-text
\-borderwidth	\-highlightthickness	\-textvariable
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
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







<







<







118
119
120
121
122
123
124

125
126
127
128
129
130
131

132
133
134
135
136
137
138
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:

.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.

.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

Changes to doc/message.n.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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







|







8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.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\fR \fIpathName \fR?\fIoptions\fR?
.SO
\-anchor	\-background	\-borderwidth
\-cursor	\-font	\-foreground
\-highlightbackground	\-highlightcolor	\-highlightthickness
\-padx	\-pady	\-relief
\-takefocus	\-text	\-textvariable
.SE
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
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 has a value less than or equal to 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







|







53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
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







<







<







107
108
109
110
111
112
113

114
115
116
117
118
119
120

121
122
123
124
125
126
127
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:

.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.

.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

Changes to doc/messageBox.n.

19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

86

87
88

89

90

91

92

93

94

95

96

97

98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
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 Mac OS X.
.\" 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.

.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:







<

|
<




<

|








<

|





<

|





<

|



<

|



<

|



<

|




>
|
>


>
|
>

>
|
>

>
|
>

>
|
>

>
|
>







|
|
|
|

|
|







19
20
21
22
23
24
25

26
27

28
29
30
31

32
33
34
35
36
37
38
39
40
41

42
43
44
45
46
47
48

49
50
51
52
53
54
55

56
57
58
59
60

61
62
63
64
65

66
67
68
69
70

71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
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:

.TP
\fB\-command\fR \fIstring\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 Mac OS X.

.TP
\fB\-default\fR \fIname\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.

.TP
\fB\-detail\fR \fIstring\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.

.TP
\fB\-icon\fR \fIiconImage\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.

.TP
\fB\-message\fR \fIstring\fR
.
Specifies the message to display in this message box. The
default value is an empty string.

.TP
\fB\-parent\fR \fIwindow\fR
.
Makes \fIwindow\fR the logical parent of the message box. The message
box is displayed on top of its parent window.

.TP
\fB\-title\fR \fItitleString\fR
.
Specifies a string to display as the title of the message box. The
default value is an empty string.

.TP
\fB\-type\fR \fIpredefinedType\fR
.
Arranges for a predefined set of buttons to be displayed. The
following values are possible for \fIpredefinedType\fR:
.RS
.TP 18
\fBabortretryignore\fR
.
Displays three buttons whose symbolic names are \fBabort\fR,
\fBretry\fR and \fBignore\fR.
.TP 18
\fBok\fR
.
Displays one button whose symbolic name is \fBok\fR.
.TP 18
\fBokcancel\fR
.
Displays two buttons whose symbolic names are \fBok\fR and \fBcancel\fR.
.TP 18
\fBretrycancel\fR
.
Displays two buttons whose symbolic names are \fBretry\fR and \fBcancel\fR.
.TP 18
\fByesno\fR
.
Displays two buttons whose symbolic names are \fByes\fR and \fBno\fR.
.TP 18
\fByesnocancel\fR
.
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:

Changes to doc/nsimage.n.

22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

47
48
49
50

51
52

53

54
55
56

57

58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
\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 interpr