util/X86LINUX64/man/mann/button.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH button n 4.4 Tk "Tk Built-In Commands"
   9 .\" The -*- nroff -*- definitions below are for supplemental macros used
  10 .\" in Tcl/Tk manual entries.
  11 .\"
  12 .\" .AP type name in/out ?indent?
  13 .\"     Start paragraph describing an argument to a library procedure.
  14 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 .\"     needed;  use .AS below instead)
  18 .\"
  19 .\" .AS ?type? ?name?
  20 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 .\"     name are examples of largest possible arguments that will be passed
  22 .\"     to .AP later.  If args are omitted, default tab stops are used.
  23 .\"
  24 .\" .BS
  25 .\"     Start box enclosure.  From here until next .BE, everything will be
  26 .\"     enclosed in one large box.
  27 .\"
  28 .\" .BE
  29 .\"     End of box enclosure.
  30 .\"
  31 .\" .CS
  32 .\"     Begin code excerpt.
  33 .\"
  34 .\" .CE
  35 .\"     End code excerpt.
  36 .\"
  37 .\" .VS ?version? ?br?
  38 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 .\"     of man pages.  The first argument is ignored and used for recording
  40 .\"     the version when the .VS was added, so that the sidebars can be
  41 .\"     found and removed when they reach a certain age.  If another argument
  42 .\"     is present, then a line break is forced before starting the sidebar.
  43 .\"
  44 .\" .VE
  45 .\"     End of vertical sidebar.
  46 .\"
  47 .\" .DS
  48 .\"     Begin an indented unfilled display.
  49 .\"
  50 .\" .DE
  51 .\"     End of indented unfilled display.
  52 .\"
  53 .\" .SO ?manpage?
  54 .\"     Start of list of standard options for a Tk widget. The manpage
  55 .\"     argument defines where to look up the standard options; if
  56 .\"     omitted, defaults to "options". The options follow on successive
  57 .\"     lines, in three columns separated by tabs.
  58 .\"
  59 .\" .SE
  60 .\"     End of list of standard options for a Tk widget.
  61 .\"
  62 .\" .OP cmdName dbName dbClass
  63 .\"     Start of description of a specific option.  cmdName gives the
  64 .\"     option's name as specified in the class command, dbName gives
  65 .\"     the option's name in the option database, and dbClass gives
  66 .\"     the option's class in the option database.
  67 .\"
  68 .\" .UL arg1 arg2
  69 .\"     Print arg1 underlined, then print arg2 normally.
  70 .\"
  71 .\" .QW arg1 ?arg2?
  72 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  73 .\"
  74 .\" .PQ arg1 ?arg2?
  75 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  76 .\"     (for trailing punctuation) and then a closing parenthesis.
  77 .\"
  78 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  79 .if t .wh -1.3i ^B
  80 .nr ^l \n(.l
  81 .ad b
  82 .\"     # Start an argument description
  83 .de AP
  84 .ie !"\\$4"" .TP \\$4
  85 .el \{\
  86 .   ie !"\\$2"" .TP \\n()Cu
  87 .   el          .TP 15
  88 .\}
  89 .ta \\n()Au \\n()Bu
  90 .ie !"\\$3"" \{\
  91 \&\\$1 \\fI\\$2\\fP (\\$3)
  92 .\".b
  93 .\}
  94 .el \{\
  95 .br
  96 .ie !"\\$2"" \{\
  97 \&\\$1  \\fI\\$2\\fP
  98 .\}
  99 .el \{\
 100 \&\\fI\\$1\\fP
 101 .\}
 102 .\}
 103 ..
 104 .\"     # define tabbing values for .AP
 105 .de AS
 106 .nr )A 10n
 107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 108 .nr )B \\n()Au+15n
 109 .\"
 110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 112 ..
 113 .AS Tcl_Interp Tcl_CreateInterp in/out
 114 .\"     # BS - start boxed text
 115 .\"     # ^y = starting y location
 116 .\"     # ^b = 1
 117 .de BS
 118 .br
 119 .mk ^y
 120 .nr ^b 1u
 121 .if n .nf
 122 .if n .ti 0
 123 .if n \l'\\n(.lu\(ul'
 124 .if n .fi
 125 ..
 126 .\"     # BE - end boxed text (draw box now)
 127 .de BE
 128 .nf
 129 .ti 0
 130 .mk ^t
 131 .ie n \l'\\n(^lu\(ul'
 132 .el \{\
 133 .\"     Draw four-sided box normally, but don't draw top of
 134 .\"     box if the box started on an earlier page.
 135 .ie !\\n(^b-1 \{\
 136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 137 .\}
 138 .el \}\
 139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 140 .\}
 141 .\}
 142 .fi
 143 .br
 144 .nr ^b 0
 145 ..
 146 .\"     # VS - start vertical sidebar
 147 .\"     # ^Y = starting y location
 148 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 149 .de VS
 150 .if !"\\$2"" .br
 151 .mk ^Y
 152 .ie n 'mc \s12\(br\s0
 153 .el .nr ^v 1u
 154 ..
 155 .\"     # VE - end of vertical sidebar
 156 .de VE
 157 .ie n 'mc
 158 .el \{\
 159 .ev 2
 160 .nf
 161 .ti 0
 162 .mk ^t
 163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 164 .sp -1
 165 .fi
 166 .ev
 167 .\}
 168 .nr ^v 0
 169 ..
 170 .\"     # Special macro to handle page bottom:  finish off current
 171 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 172 .\"     # page bottom macro.
 173 .de ^B
 174 .ev 2
 175 'ti 0
 176 'nf
 177 .mk ^t
 178 .if \\n(^b \{\
 179 .\"     Draw three-sided box if this is the box's first page,
 180 .\"     draw two sides but no top otherwise.
 181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .\}
 184 .if \\n(^v \{\
 185 .nr ^x \\n(^tu+1v-\\n(^Yu
 186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 187 .\}
 188 .bp
 189 'fi
 190 .ev
 191 .if \\n(^b \{\
 192 .mk ^y
 193 .nr ^b 2
 194 .\}
 195 .if \\n(^v \{\
 196 .mk ^Y
 197 .\}
 198 ..
 199 .\"     # DS - begin display
 200 .de DS
 201 .RS
 202 .nf
 203 .sp
 204 ..
 205 .\"     # DE - end display
 206 .de DE
 207 .fi
 208 .RE
 209 .sp
 210 ..
 211 .\"     # SO - start of list of standard options
 212 .de SO
 213 'ie '\\$1'' .ds So \\fBoptions\\fR
 214 'el .ds So \\fB\\$1\\fR
 215 .SH "STANDARD OPTIONS"
 216 .LP
 217 .nf
 218 .ta 5.5c 11c
 219 .ft B
 220 ..
 221 .\"     # SE - end of list of standard options
 222 .de SE
 223 .fi
 224 .ft R
 225 .LP
 226 See the \\*(So manual entry for details on the standard options.
 227 ..
 228 .\"     # OP - start of full description for a single option
 229 .de OP
 230 .LP
 231 .nf
 232 .ta 4c
 233 Command-Line Name:      \\fB\\$1\\fR
 234 Database Name:  \\fB\\$2\\fR
 235 Database Class: \\fB\\$3\\fR
 236 .fi
 237 .IP
 238 ..
 239 .\"     # CS - begin code excerpt
 240 .de CS
 241 .RS
 242 .nf
 243 .ta .25i .5i .75i 1i
 244 ..
 245 .\"     # CE - end code excerpt
 246 .de CE
 247 .fi
 248 .RE
 249 ..
 250 .\"     # UL - underline word
 251 .de UL
 252 \\$1\l'|0\(ul'\\$2
 253 ..
 254 .\"     # QW - apply quotation marks to word
 255 .de QW
 256 .ie '\\*(lq'"' ``\\$1''\\$2
 257 .\"" fix emacs highlighting
 258 .el \\*(lq\\$1\\*(rq\\$2
 259 ..
 260 .\"     # PQ - apply parens and quotation marks to word
 261 .de PQ
 262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 263 .\"" fix emacs highlighting
 264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 265 ..
 266 .\"     # QR - quoted range
 267 .de QR
 268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 269 .\"" fix emacs highlighting
 270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 271 ..
 272 .\"     # MT - "empty" string
 273 .de MT
 274 .QW ""
 275 ..
 276 .BS
 277 '\" Note:  do not modify the .SH NAME line immediately below!
 278 .SH NAME
 279 button \- Create and manipulate 'button' action widgets
 280 .SH SYNOPSIS
 281 \fBbutton\fR \fIpathName \fR?\fIoptions\fR?
 282 .SO
 283 \-activebackground      \-font  \-relief
 284 \-activeforeground      \-foreground    \-repeatdelay
 285 \-anchor        \-highlightbackground   \-repeatinterval
 286 \-background    \-highlightcolor        \-takefocus
 287 \-bitmap        \-highlightthickness    \-text
 288 \-borderwidth   \-image \-textvariable
 289 \-compound      \-justify       \-underline
 290 \-cursor        \-padx  \-wraplength
 291 \-disabledforeground    \-pady
 292 .SE
 293 .SH "WIDGET-SPECIFIC OPTIONS"
 294 .OP \-command command Command
 295 Specifies a Tcl command to associate with the button.  This command
 296 is typically invoked when mouse button 1 is released over the button
 297 window.
 298 .OP \-default default Default
 299 Specifies one of three states for the default ring: \fBnormal\fR,
 300 \fBactive\fR, or \fBdisabled\fR.  In active state, the button is drawn
 301 with the platform specific appearance for a default button.  In normal
 302 state, the button is drawn with the platform specific appearance for a
 303 non-default button, leaving enough space to draw the default button
 304 appearance.  The normal and active states will result in buttons of
 305 the same size.  In disabled state, the button is drawn with the
 306 non-default button appearance without leaving space for the default
 307 appearance.  The disabled state may result in a smaller button than
 308 the active state.
 309 .OP \-height height Height
 310 Specifies a desired height for the button.
 311 If an image or bitmap is being displayed in the button then the value is in
 312 screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR);
 313 for text it is in lines of text.
 314 If this option is not specified, the button's desired height is computed
 315 from the size of the image or bitmap or text being displayed in it.
 316 .OP \-overrelief overRelief OverRelief
 317 Specifies an alternative relief for the button, to be used when the
 318 mouse cursor is over the widget.  This option can be used to make
 319 toolbar buttons, by configuring \fB\-relief flat \-overrelief
 320 raised\fR.  If the value of this option is the empty string, then no
 321 alternative relief is used when the mouse cursor is over the button.
 322 The empty string is the default value.
 323 .OP \-state state State
 324 Specifies one of three states for the button:  \fBnormal\fR, \fBactive\fR,
 325 or \fBdisabled\fR.  In normal state the button is displayed using the
 326 \fB\-foreground\fR and \fB\-background\fR options.  The active state is
 327 typically used when the pointer is over the button.  In active state
 328 the button is displayed using the \fB\-activeforeground\fR and
 329 \fB\-activebackground\fR options.  Disabled state means that the button
 330 should be insensitive:  the default bindings will refuse to activate
 331 the widget and will ignore mouse button presses.
 332 In this state the \fB\-disabledforeground\fR and
 333 \fB\-background\fR options determine how the button is displayed.
 334 .OP \-width width Width
 335 Specifies a desired width for the button.
 336 If an image or bitmap is being displayed in the button then the value is in
 337 screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR).
 338 For a text button (no image or with \fB\-compound none\fR) then the width
 339 specifies how much space in characters to allocate for the text label.
 340 If the width is negative then this specifies a minimum width.
 341 If this option is not specified, the button's desired width is computed
 342 from the size of the image or bitmap or text being displayed in it.
 343 .BE
 344 .SH DESCRIPTION
 345 .PP
 346 The \fBbutton\fR command creates a new window (given by the
 347 \fIpathName\fR argument) and makes it into a button widget.
 348 Additional
 349 options, described above, may be specified on the command line
 350 or in the option database
 351 to configure aspects of the button such as its colors, font,
 352 text, and initial relief.  The \fBbutton\fR command returns its
 353 \fIpathName\fR argument.  At the time this command is invoked,
 354 there must not exist a window named \fIpathName\fR, but
 355 \fIpathName\fR's parent must exist.
 356 .PP
 357 A button is a widget that displays a textual string, bitmap or image.
 358 If text is displayed, it must all be in a single font, but it
 359 can occupy multiple lines on the screen (if it contains newlines
 360 or if wrapping occurs because of the \fB\-wraplength\fR option) and
 361 one of the characters may optionally be underlined using the
 362 \fB\-underline\fR option.
 363 It can display itself in either of three different ways, according
 364 to
 365 the \fB\-state\fR option;
 366 it can be made to appear raised, sunken, or flat;
 367 and it can be made to flash.  When a user invokes the
 368 button (by pressing mouse button 1 with the cursor over the
 369 button), then the Tcl command specified in the \fB\-command\fR
 370 option is invoked.
 371 .SH "WIDGET COMMAND"
 372 .PP
 373 The \fBbutton\fR command creates a new Tcl command whose
 374 name is \fIpathName\fR.  This
 375 command may be used to invoke various
 376 operations on the widget.  It has the following general form:
 377 .CS
 378 \fIpathName option \fR?\fIarg arg ...\fR?
 379 .CE
 380 \fIOption\fR and the \fIarg\fRs
 381 determine the exact behavior of the command.  The following
 382 commands are possible for button widgets:
 383 .TP
 384 \fIpathName \fBcget\fR \fIoption\fR
 385 Returns the current value of the configuration option given
 386 by \fIoption\fR.
 387 \fIOption\fR may have any of the values accepted by the \fBbutton\fR
 388 command.
 389 .TP
 390 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
 391 Query or modify the configuration options of the widget.
 392 If no \fIoption\fR is specified, returns a list describing all of
 393 the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
 394 information on the format of this list).  If \fIoption\fR is specified
 395 with no \fIvalue\fR, then the command returns a list describing the
 396 one named option (this list will be identical to the corresponding
 397 sublist of the value returned if no \fIoption\fR is specified).  If
 398 one or more \fIoption\-value\fR pairs are specified, then the command
 399 modifies the given widget option(s) to have the given value(s);  in
 400 this case the command returns an empty string.
 401 \fIOption\fR may have any of the values accepted by the \fBbutton\fR
 402 command.
 403 .TP
 404 \fIpathName \fBflash\fR
 405 Flash the button.  This is accomplished by redisplaying the button
 406 several times, alternating between the configured activebackground
 407 and background colors.  At the end of the flash the button is left
 408 in the same normal/active state as when the command was invoked.
 409 This command is ignored if the button's state is \fBdisabled\fR.
 410 .TP
 411 \fIpathName \fBinvoke\fR
 412 Invoke the Tcl command associated with the button, if there is one.
 413 The return value is the return value from the Tcl command, or an
 414 empty string if there is no command associated with the button.
 415 This command is ignored if the button's state is \fBdisabled\fR.
 416 .SH "DEFAULT BINDINGS"
 417 .PP
 418 Tk automatically creates class bindings for buttons that give them
 419 default behavior:
 420 .IP [1]
 421 A button activates whenever the mouse passes over it and deactivates
 422 whenever the mouse leaves the button.
 423 Under Windows, this binding is only active when mouse button 1 has
 424 been pressed over the button.
 425 .IP [2]
 426 A button's relief is changed to sunken whenever mouse button 1 is
 427 pressed over the button, and the relief is restored to its original
 428 value when button 1 is later released.
 429 .IP [3]
 430 If mouse button 1 is pressed over a button and later released over
 431 the button, the button is invoked.  However, if the mouse is not
 432 over the button when button 1 is released, then no invocation occurs.
 433 .IP [4]
 434 When a button has the input focus, the space key causes the button
 435 to be invoked.
 436 .PP
 437 If the button's state is \fBdisabled\fR then none of the above
 438 actions occur:  the button is completely non-responsive.
 439 .PP
 440 The behavior of buttons can be changed by defining new bindings for
 441 individual widgets or by redefining the class bindings.
 442 .SH "PLATFORM NOTES"
 443 .PP
 444 On Aqua/Mac OS X, some configuration options are ignored for the purpose of
 445 drawing of the widget because they would otherwise conflict with platform
 446 guidelines. The \fBconfigure\fR and \fBcget\fR subcommands can still
 447 manipulate the values, but do not cause any variation to the look of the
 448 widget. The options affected notably include \fB\-background\fR and
 449 \fB\-relief\fR.
 450 .SH EXAMPLES
 451 .PP
 452 This is the classic Tk
 453 .QW "Hello, World!"
 454 demonstration:
 455 .PP
 456 .CS
 457 \fBbutton\fR .b \-text "Hello, World!" \-command exit
 458 pack .b
 459 .CE
 460 .PP
 461 This example demonstrates how to handle button accelerators:
 462 .PP
 463 .CS
 464 \fBbutton\fR .b1 \-text Hello \-underline 0
 465 \fBbutton\fR .b2 \-text World \-underline 0
 466 bind . <Key\-h> {.b1 flash; .b1 invoke}
 467 bind . <Key\-w> {.b2 flash; .b2 invoke}
 468 pack .b1 .b2
 469 .CE
 470 .SH "SEE ALSO"
 471 ttk::button(n)
 472 .SH KEYWORDS
 473 button, widget
 474 '\" Local Variables:
 475 '\" mode: nroff
 476 '\" End: