doc/options.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
   4 '\" Copyright (c) 1996-1999 Christian Werner
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .so man.macros
  10 .TH options n 8.0 Ck "Ck Built-In Commands"
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 options \- Standard options supported by widgets
  15 .BE
  16
  17 .SH DESCRIPTION
  18 This manual entry describes the common configuration options supported
  19 by widgets in the Ck toolkit.  Every widget does not necessarily support
  20 every option (see the manual entries for individual widgets for a list
  21 of the standard options supported by that widget), but if a widget does
  22 support an option with one of the names listed below, then the option
  23 has exactly the effect described below.
  24 .PP
  25 In the descriptions below,
  26 ``Name'' refers to the option's name in the option database
  27 ``Class'' refers to the option's class value
  28 in the option database.  ``Command-Line Switch'' refers to the
  29 switch used in widget-creation and \fBconfigure\fR widget commands to
  30 set this value.  For example, if an option's command-line switch is
  31 \fB\-foreground\fR and there exists a widget \fB.a.b.c\fR, then the
  32 command
  33 .DS
  34 \&\fB.a.b.c\0\0configure\0\0\-foreground black\fR
  35 .DE
  36 may be used to specify the value \fBblack\fR for the option in the
  37 the widget \fB.a.b.c\fR.  Command-line switches may be abbreviated,
  38 as long as the abbreviation is unambiguous.
  39 .ta 4c
  40 .LP
  41 .nf
  42 Name:   \fBactiveAttributes\fR
  43 Class:  \fBAttributes\fR
  44 Command-Line Switch:    \fB\-activeattributes\fR
  45 .fi
  46 .IP
  47 Specifies video attributes to use when drawing active elements of
  48 widgets. This option must be a proper Tcl list which may contain
  49 the elements:
  50 .PP
  51 .ta 4c 8c
  52 .nf
  53         \fBblink\fR     \fBreverse\fR
  54         \fBbold\fR      \fBstandout\fR
  55         \fBdim\fR       \fBunderline\fR
  56         \fBnormal\fR
  57 .fi
  58 .ta 4c
  59 .IP
  60 If the list is empty, the \fBnormal\fR attribute is automatically present.
  61 .LP
  62 .nf
  63 Name:   \fBactiveBackground\fR
  64 Class:  \fBForeground\fR
  65 Command-Line Switch:    \fB\-activebackground\fR
  66 .fi
  67 .IP
  68 Specifies background color to use when drawing active elements of
  69 widgets. Color specifications are always symbolic; valid color names are:
  70 .PP
  71 .ta 4c 8c
  72 .nf
  73         \fBblack\fR     \fBmagenta\fR
  74         \fBblue\fR      \fBred\fR
  75         \fBcyan\fR      \fByellow\fR
  76         \fBgreen\fR     \fBwhite\fR
  77 .fi
  78 .ta 4c
  79 .PP
  80 .LP
  81 .nf
  82 Name:   \fBactiveForeground\fR
  83 Class:  \fBBackground\fR
  84 Command-Line Switch:    \fB\-activeforeground\fR
  85 .fi
  86 .IP
  87 Specifies foreground color to use when drawing active elements.
  88 See above for possible colors.
  89 .LP
  90 .nf
  91 Name:   \fBanchor\fR
  92 Class:  \fBAnchor\fR
  93 Command-Line Switch:    \fB\-anchor\fR
  94 .fi
  95 .IP
  96 Specifies how the text in a widget is to be displayed in the widget.
  97 Must be one of the values \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR,
  98 \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR.
  99 For example, \fBnw\fR means display the text such that its
 100 top-left corner is at the top-left corner of the widget.
 101 .LP
 102 .nf
 103 Name:   \fBattributes\fR
 104 Class:  \fBAttributes\fR
 105 Command-Line Switch:    \fB\-attributes\fR
 106 .fi
 107 .IP
 108 Specifies video attributes to use when displaying the widget.
 109 See \fBactiveAttributes\fR for possible values.
 110 .LP
 111 .nf
 112 Name:   \fBbackground\fR
 113 Class:  \fBBackground\fR
 114 Command-Line Switch:    \fB\-background or \-bg\fR
 115 .fi
 116 .IP
 117 Specifies the normal background color to use when displaying the
 118 widget. See \fBactiveBackground\fR for possible colors.
 119 .LP
 120 .nf
 121 Name:   \fBborder\fR
 122 Class:  \fBBorder\fR
 123 Command-Line Switch:    \fB\-border\fR
 124 .fi
 125 .IP
 126 Specifies the characters used for drawing a border around a widget.
 127 This options must be a proper Tcl list with exactly zero, one, three, six,
 128 or eight elements:
 129 .RS
 130 .TP 12
 131 0 elements
 132 No extra space for the border is allocated by the widget.
 133 .TP 12
 134 1 element
 135 All four sides of the border's rectangle plus the corners are made from
 136 the sole element.
 137 .TP 12
 138 3 elements
 139 The first element is used for the rectangle's corners, the second for
 140 the horizontal sides, and the third for the vertical sides.
 141 .TP 12
 142 6 elements
 143 The order of elements in the rectangle is: upper left corner, horizontal
 144 side, upper right corner, vertical side, lower right corner, lower left
 145 corner.
 146 .TP 12
 147 8 elements
 148 Each element gives corner and side, alternating, starting at the upper
 149 left corner of the square, clockwise.
 150 .RE
 151 .IP
 152 The list elements must be either a single character or a symbolic name
 153 of a graphical character. For valid names of graphical characters refer
 154 to the \fBcurses gchar\fR command.
 155 .LP
 156 .nf
 157 Name:   \fBdisabledAttributes\fR
 158 Class:  \fBDisabledAttributes\fR
 159 Command-Line Switch:    \fB\-disabledattributes\fR
 160 .fi
 161 .IP
 162 Specifies video attributes to use when drawing a disabled element.
 163 See \fBactiveAttributes\fR for possible values.
 164 .LP
 165 .nf
 166 Name:   \fBdisabledBackground\fR
 167 Class:  \fBDisabledBackground\fR
 168 Command-Line Switch:    \fB\-disabledbackground\fR
 169 .fi
 170 .IP
 171 Specifies background color to use when drawing a disabled element.
 172 See \fBactiveBackground\fR for possible colors.
 173 .LP
 174 .nf
 175 Name:   \fBdisabledForeground\fR
 176 Class:  \fBDisabledForeground\fR
 177 Command-Line Switch:    \fB\-disabledforeground\fR
 178 .fi
 179 .IP
 180 Specifies foreground color to use when drawing a disabled element.
 181 See \fBactiveBackground\fR for possible colors.
 182 .LP
 183 .nf
 184 Name:   \fBforeground\fR
 185 Class:  \fBForeground\fR
 186 Command-Line Switch:    \fB\-foreground or \-fg\fR
 187 .fi
 188 .IP
 189 Specifies the normal foreground color to use when displaying the widget.
 190 See \fBactiveBackground\fR for possible colors.
 191 .LP
 192 .nf
 193 Name:   \fBjustify\fR
 194 Class:  \fBJustify\fR
 195 Command-Line Switch:    \fB\-justify\fR
 196 .fi
 197 .IP
 198 When there are multiple lines of text displayed in a widget, this
 199 option determines how the lines line up with each other.
 200 Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR.
 201 \fBLeft\fR means that the lines' left edges all line up, \fBcenter\fR
 202 means that the lines' centers are aligned, and \fBright\fR means
 203 that the lines' right edges line up.
 204 .LP
 205 .nf
 206 Name:   \fBorient\fR
 207 Class:  \fBOrient\fR
 208 Command-Line Switch:    \fB\-orient\fR
 209 .fi
 210 .IP
 211 For widgets that can lay themselves out with either a horizontal
 212 or vertical orientation, such as scrollbars, this option specifies
 213 which orientation should be used.  Must be either \fBhorizontal\fR
 214 or \fBvertical\fR or an abbreviation of one of these.
 215 .LP
 216 .nf
 217 Name:   \fBselectAttributes\fR
 218 Class:  \fBSelectAttributes\fR
 219 Command-Line Switch:    \fB\-selectattributes\fR
 220 .fi
 221 .IP
 222 Specifies video attributes to use when displaying selected items.
 223 See \fBactiveAttributes\fR for possible values.
 224 .LP
 225 .nf
 226 Name:   \fBselectBackground\fR
 227 Class:  \fBForeground\fR
 228 Command-Line Switch:    \fB\-selectbackground\fR
 229 .fi
 230 .IP
 231 Specifies the background color to use when displaying selected
 232 items. See \fBactiveBackground\fR for possible colors.
 233 .LP
 234 .nf
 235 Name:   \fBselectForeground\fR
 236 Class:  \fBBackground\fR
 237 Command-Line Switch:    \fB\-selectforeground\fR
 238 .fi
 239 .IP
 240 Specifies the foreground color to use when displaying selected
 241 items. See \fBactiveBackground\fR for possible colors.
 242 .LP
 243 .nf
 244 Name:   \fBtakeFocus\fR
 245 Class:  \fBTakeFocus\fR
 246 Command-Line Switch:    \fB\-takefocus\fR
 247 .fi
 248 .IP
 249 Provides information used when moving the focus from window to window
 250 via keyboard traversal (e.g., Tab and BackTab).
 251 Before setting the focus to a window, the traversal scripts first
 252 check whether the window is viewable (it and all its ancestors are mapped);
 253 if not, the window is skipped.
 254 Next, the scripts consult the value of the \fBtakeFocus\fR option.
 255 A value of \fB0\fR means that this window should be skipped entirely
 256 during keyboard traversal.
 257 \fB1\fR means that the this window should always receive the input
 258 focus.
 259 An empty value means that the traversal scripts make the decision
 260 about whether or not to focus on the window:  the current
 261 algorithm is to skip the window if it is
 262 disabled or if it has no key bindings.
 263 If the value has any other form, then the traversal scripts take
 264 the value, append the name of the window to it (with a separator space),
 265 and evaluate the resulting string as a Tcl script.
 266 The script must return 0, 1, or an empty string;  this value is used
 267 just as if the option had that value in the first place.
 268 Note: this interpretation of the option is defined entirely by
 269 the Tcl scripts that implement traversal:  the widget implementations
 270 ignore the option entirely, so you can change its meaning if you
 271 redefine the keyboard traversal scripts.
 272 .LP
 273 .nf
 274 Name:   \fBtext\fR
 275 Class:  \fBText\fR
 276 Command-Line Switch:    \fB\-text\fR
 277 .fi
 278 .IP
 279 Specifies a string to be displayed inside the widget.  The way in which
 280 the string is displayed depends on the particular widget and may be
 281 determined by other options, such as \fBanchor\fR or \fBjustify\fR.
 282 .LP
 283 .nf
 284 Name:   \fBtextVariable\fR
 285 Class:  \fBVariable\fR
 286 Command-Line Switch:    \fB\-textvariable\fR
 287 .fi
 288 .IP
 289 Specifies the name of a variable.  The value of the variable is a text
 290 string to be displayed inside the widget;  if the variable value changes
 291 then the widget will automatically update itself to reflect the new value.
 292 The way in which the string is displayed in the widget depends on the
 293 particular widget and may be determined by other options, such as
 294 \fBanchor\fR or \fBjustify\fR.
 295 .LP
 296 .nf
 297 Name:   \fBunderline\fR
 298 Class:  \fBUnderline\fR
 299 Command-Line Switch:    \fB\-underline\fR
 300 .fi
 301 .IP
 302 Specifies the integer index of a character to underline in the widget.
 303 This option is used by the default bindings to implement keyboard
 304 traversal for menu buttons and menu entries.
 305 0 corresponds to the first character of the text displayed in the
 306 widget, 1 to the next character, and so on.
 307 .LP
 308 .nf
 309 Name:   \fBunderlineAttributes\fR
 310 Class:  \fBUnderlineAttributes\fR
 311 Command-Line Switch:    \fB\-underlineattributes\fR
 312 .fi
 313 .IP
 314
 315 .LP
 316 .nf
 317 Name:   \fBunderlineForeground\fR
 318 Class:  \fBUnderlineForeground\fR
 319 Command-Line Switch:    \fB\-underlineforeground\fR
 320 .fi
 321 .IP
 322 Specifies the foreground color to use when displaying an underlined
 323 character. See \fBactiveBackground\fR for possible colors.
 324 .LP
 325 .nf
 326 Name:   \fBxScrollCommand\fR
 327 Class:  \fBScrollCommand\fR
 328 Command-Line Switch:    \fB\-xscrollcommand\fR
 329 .fi
 330 .IP
 331 Specifies the prefix for a command used to communicate with horizontal
 332 scrollbars.
 333 When the view in the widget's window changes (or
 334 whenever anything else occurs that could change the display in a
 335 scrollbar, such as a change in the total size of the widget's
 336 contents), the widget will
 337 generate a Tcl command by concatenating the scroll command and
 338 two numbers.
 339 Each of the numbers is a fraction between 0 and 1, which indicates
 340 a position in the document.  0 indicates the beginning of the document,
 341 1 indicates the end, .333 indicates a position one third the way through
 342 the document, and so on.
 343 The first fraction indicates the first information in the document
 344 that is visible in the window, and the second fraction indicates
 345 the information just after the last portion that is visible.
 346 The command is
 347 then passed to the Tcl interpreter for execution.  Typically the
 348 \fBxScrollCommand\fR option consists of the path name of a scrollbar
 349 widget followed by ``set'', e.g. ``.x.scrollbar set'':  this will cause
 350 the scrollbar to be updated whenever the view in the window changes.
 351 If this option is not specified, then no command will be executed.
 352 .LP
 353 .nf
 354 Name:   \fByScrollCommand\fR
 355 Class:  \fBScrollCommand\fR
 356 Command-Line Switch:    \fB\-yscrollcommand\fR
 357 .fi
 358 .IP
 359 Specifies the prefix for a command used to communicate with vertical
 360 scrollbars.  This option is treated in the same way as the
 361 \fBxScrollCommand\fR option, except that it is used for vertical
 362 scrollbars and is provided by widgets that support vertical scrolling.
 363 See the description of \fBxScrollCommand\fR for details
 364 on how this option is used.
 365
 366 .SH KEYWORDS
 367 class, name, standard option, switch