tk/generic/tkButton.h

   1 /*
   2  * tkButton.h --
   3  *
   4  *      Declarations of types and functions used to implement
   5  *      button-like widgets.
   6  *
   7  * Copyright (c) 1996-1998 by Sun Microsystems, Inc.
   8  *
   9  * See the file "license.terms" for information on usage and redistribution
  10  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  11  *
  12  * RCS: @(#) $Id$
  13  */
  14
  15 #ifndef _TKBUTTON
  16 #define _TKBUTTON
  17
  18 #ifndef _TKINT
  19 #include "tkInt.h"
  20 #endif
  21
  22 #ifdef BUILD_tk
  23 # undef TCL_STORAGE_CLASS
  24 # define TCL_STORAGE_CLASS DLLEXPORT
  25 #endif
  26
  27 /*
  28  * Legal values for the "compound" field of TkButton records.
  29  */
  30
  31 enum compound {
  32     COMPOUND_BOTTOM, COMPOUND_CENTER, COMPOUND_LEFT, COMPOUND_NONE,
  33         COMPOUND_RIGHT, COMPOUND_TOP
  34 };
  35
  36 /*
  37  * Legal values for the "state" field of TkButton records.
  38  */
  39
  40 enum state {
  41     STATE_ACTIVE, STATE_DISABLED, STATE_NORMAL
  42 };
  43
  44 /*
  45  * Legal values for the "defaultState" field of TkButton records.
  46  */
  47
  48 enum defaultState {
  49     DEFAULT_ACTIVE, DEFAULT_DISABLED, DEFAULT_NORMAL
  50 };
  51
  52 /*
  53  * A data structure of the following type is kept for each
  54  * widget managed by this file:
  55  */
  56
  57 typedef struct {
  58     Tk_Window tkwin;            /* Window that embodies the button.  NULL
  59                                  * means that the window has been destroyed. */
  60     Display *display;           /* Display containing widget.  Needed to
  61                                  * free up resources after tkwin is gone. */
  62     Tcl_Interp *interp;         /* Interpreter associated with button. */
  63     Tcl_Command widgetCmd;      /* Token for button's widget command. */
  64     int type;                   /* Type of widget, such as TYPE_LABEL:
  65                                  * restricts operations that may be performed
  66                                  * on widget.  See below for legal values. */
  67     Tk_OptionTable optionTable; /* Table that defines configuration options
  68                                  * available for this widget. */
  69
  70     /*
  71      * Information about what's in the button.
  72      */
  73
  74     Tcl_Obj *textPtr;           /* Value of -text option: specifies text to
  75                                  * display in button. */
  76     int underline;              /* Value of -underline option: specifies
  77                                  * index of character to underline.  < 0 means
  78                                  * don't underline anything. */
  79     Tcl_Obj *textVarNamePtr;    /* Value of -textvariable option: specifies
  80                                  * name of variable or NULL.  If non-NULL,
  81                                  * button displays the contents of this
  82                                  * variable. */
  83     Pixmap bitmap;              /* Value of -bitmap option.  If not None,
  84                                  * specifies bitmap to display and text and
  85                                  * textVar are ignored. */
  86     Tcl_Obj *imagePtr;          /* Value of -image option: specifies image
  87                                  * to display in window, or NULL if none.
  88                                  * If non-NULL, bitmap, text, and textVarName
  89                                  * are ignored.*/
  90     Tk_Image image;             /* Derived from imagePtr by calling
  91                                  * Tk_GetImage, or NULL if imagePtr is NULL. */
  92     Tcl_Obj *selectImagePtr;    /* Value of -selectimage option: specifies
  93                                  * image to display in window when selected,
  94                                  * or NULL if none.  Ignored if imagePtr is
  95                                  * NULL. */
  96     Tk_Image selectImage;       /* Derived from selectImagePtr by calling
  97                                  * Tk_GetImage, or NULL if selectImagePtr
  98                                  * is NULL. */
  99
 100     /*
 101      * Information used when displaying widget:
 102      */
 103
 104     enum state state;           /* Value of -state option: specifies
 105                                  * state of button for display purposes.*/
 106     Tk_3DBorder normalBorder;   /* Value of -background option: specifies
 107                                  * color for background (and border) when
 108                                  * window isn't active. */
 109     Tk_3DBorder activeBorder;   /* Value of -activebackground option:
 110                                  * this is the color used to draw 3-D border
 111                                  * and background when widget is active. */
 112     Tcl_Obj *borderWidthPtr;    /* Value of -borderWidth option: specifies
 113                                  * width of border in pixels. */
 114     int borderWidth;            /* Integer value corresponding to
 115                                  * borderWidthPtr.  Always >= 0. */
 116     int relief;                 /* Value of -relief option: specifies 3-d
 117                                  * effect for border, such as
 118                                  * TK_RELIEF_RAISED. */
 119     int overRelief;             /* Value of -overrelief option: specifies a 3-d
 120                                  * effect for the border, such as
 121                                  * TK_RELIEF_RAISED, to be used when the mouse
 122                                  * is over the button. */
 123     int offRelief;              /* Value of -offrelief option: specifies a 3-d
 124                                  * effect for the border, such as
 125                                  * TK_RELIEF_RAISED, to be used when a
 126                                  * checkbutton or radiobutton without
 127                                  * indicator is off */
 128     Tcl_Obj *highlightWidthPtr; /* Value of -highlightthickness option:
 129                                  * specifies width in pixels of highlight to
 130                                  * draw around widget when it has the focus.
 131                                  * <= 0 means don't draw a highlight. */
 132     int highlightWidth;         /* Integer value corresponding to
 133                                  * highlightWidthPtr.  Always >= 0. */
 134     Tk_3DBorder highlightBorder;/* Value of -highlightbackground option:
 135                                  * specifies background with which to draw 3-D
 136                                  * default ring and focus highlight area when
 137                                  * highlight is off. */
 138     XColor *highlightColorPtr;  /* Value of -highlightcolor option:
 139                                  * specifies color for drawing traversal
 140                                  * highlight. */
 141     int inset;                  /* Total width of all borders, including
 142                                  * traversal highlight and 3-D border.
 143                                  * Indicates how much interior stuff must
 144                                  * be offset from outside edges to leave
 145                                  * room for borders. */
 146     Tk_Font tkfont;             /* Value of -font option: specifies font
 147                                  * to use for display text. */
 148     XColor *normalFg;           /* Value of -font option: specifies foreground
 149                                  * color in normal mode. */
 150     XColor *activeFg;           /* Value of -activeforeground option:
 151                                  * foreground color in active mode.  NULL
 152                                  * means use -foreground instead. */
 153     XColor *disabledFg;         /* Value of -disabledforeground option:
 154                                  * foreground color when disabled.  NULL
 155                                  * means use normalFg with a 50% stipple
 156                                  * instead. */
 157     GC normalTextGC;            /* GC for drawing text in normal mode.  Also
 158                                  * used to copy from off-screen pixmap onto
 159                                  * screen. */
 160     GC activeTextGC;            /* GC for drawing text in active mode (NULL
 161                                  * means use normalTextGC). */
 162     GC disabledGC;              /* Used to produce disabled effect.  If
 163                                  * disabledFg isn't NULL, this GC is used to
 164                                  * draw button text or icon.  Otherwise
 165                                  * text or icon is drawn with normalGC and
 166                                  * this GC is used to stipple background
 167                                  * across it.  For labels this is None. */
 168     Pixmap gray;                /* Pixmap for displaying disabled text if
 169                                  * disabledFg is NULL. */
 170     GC copyGC;                  /* Used for copying information from an
 171                                  * off-screen pixmap to the screen. */
 172     Tcl_Obj *widthPtr;          /* Value of -width option. */
 173     int width;                  /* Integer value corresponding to widthPtr. */
 174     Tcl_Obj *heightPtr;         /* Value of -height option. */
 175     int height;                 /* Integer value corresponding to heightPtr. */
 176     Tcl_Obj *wrapLengthPtr;     /* Value of -wraplength option: specifies
 177                                  * line length (in pixels) at which to wrap
 178                                  * onto next line.  <= 0 means don't wrap
 179                                  * except at newlines. */
 180     int wrapLength;             /* Integer value corresponding to
 181                                  * wrapLengthPtr. */
 182     Tcl_Obj *padXPtr;           /* Value of -padx option: specifies how many
 183                                  * pixels of extra space to leave on left and
 184                                  * right of text.  Ignored for bitmaps and
 185                                  * images. */
 186     int padX;                   /* Integer value corresponding to padXPtr. */
 187     Tcl_Obj *padYPtr;           /* Value of -padx option: specifies how many
 188                                  * pixels of extra space to leave above and
 189                                  * below text.  Ignored for bitmaps and
 190                                  * images. */
 191     int padY;                   /* Integer value corresponding to padYPtr. */
 192     Tk_Anchor anchor;           /* Value of -anchor option: specifies where
 193                                  * text/bitmap should be displayed inside
 194                                  * button region. */
 195     Tk_Justify justify;         /* Value of -justify option: specifies how
 196                                  * to align lines of multi-line text. */
 197     int indicatorOn;            /* Value of -indicatoron option:  1 means
 198                                  * draw indicator in checkbuttons and
 199                                  * radiobuttons, 0 means don't draw it. */
 200     Tk_3DBorder selectBorder;   /* Value of -selectcolor option: specifies
 201                                  * color for drawing indicator background, or
 202                                  * perhaps widget background, when selected. */
 203     int textWidth;              /* Width needed to display text as requested,
 204                                  * in pixels. */
 205     int textHeight;             /* Height needed to display text as requested,
 206                                  * in pixels. */
 207     Tk_TextLayout textLayout;   /* Saved text layout information. */
 208     int indicatorSpace;         /* Horizontal space (in pixels) allocated for
 209                                  * display of indicator. */
 210     int indicatorDiameter;      /* Diameter of indicator, in pixels. */
 211     enum defaultState defaultState;
 212                                 /* Value of -default option, such as
 213                                  * DEFAULT_NORMAL: specifies state
 214                                  * of default ring for buttons (normal,
 215                                  * active, or disabled).  NULL for other
 216                                  * classes. */
 217
 218     /*
 219      * For check and radio buttons, the fields below are used
 220      * to manage the variable indicating the button's state.
 221      */
 222
 223     Tcl_Obj *selVarNamePtr;     /* Value of -variable option: specifies name
 224                                  * of variable used to control selected
 225                                  * state of button. */
 226     Tcl_Obj *onValuePtr;        /* Value of -offvalue option: specifies value
 227                                  * to store in variable when this button is
 228                                  * selected. */
 229     Tcl_Obj *offValuePtr;       /* Value of -offvalue option: specifies value
 230                                  * to store in variable when this button
 231                                  * isn't selected.  Used only by
 232                                  * checkbuttons. */
 233
 234     /*
 235      * Miscellaneous information:
 236      */
 237
 238     Tk_Cursor cursor;           /* Value of -cursor option: if not None,
 239                                  * specifies current cursor for window. */
 240     Tcl_Obj *takeFocusPtr;      /* Value of -takefocus option;  not used in
 241                                  * the C code, but used by keyboard traversal
 242                                  * scripts. */
 243     Tcl_Obj *commandPtr;        /* Value of -command option: specifies script
 244                                  * to execute when button is invoked.  If
 245                                  * widget is label or has no command, this
 246                                  * is NULL. */
 247     int compound;               /* Value of -compound option; specifies whether
 248                                  * the button should show both an image and
 249                                  * text, and, if so, how. */
 250     int repeatDelay;            /* Value of -repeatdelay option; specifies
 251                                  * the number of ms after which the button will
 252                                  * start to auto-repeat its command. */
 253     int repeatInterval;         /* Value of -repeatinterval option; specifies
 254                                  * the number of ms between auto-repeat
 255                                  * invocataions of the button command. */
 256     int flags;                  /* Various flags;  see below for
 257                                  * definitions. */
 258 } TkButton;
 259
 260 /*
 261  * Possible "type" values for buttons.  These are the kinds of
 262  * widgets supported by this file.  The ordering of the type
 263  * numbers is significant:  greater means more features and is
 264  * used in the code.
 265  */
 266
 267 #define TYPE_LABEL              0
 268 #define TYPE_BUTTON             1
 269 #define TYPE_CHECK_BUTTON       2
 270 #define TYPE_RADIO_BUTTON       3
 271
 272 /*
 273  * Flag bits for buttons:
 274  *
 275  * REDRAW_PENDING:              Non-zero means a DoWhenIdle handler
 276  *                              has already been queued to redraw
 277  *                              this window.
 278  * SELECTED:                    Non-zero means this button is selected,
 279  *                              so special highlight should be drawn.
 280  * GOT_FOCUS:                   Non-zero means this button currently
 281  *                              has the input focus.
 282  * BUTTON_DELETED:              Non-zero needs that this button has been
 283  *                              deleted, or is in the process of being
 284  *                              deleted.
 285  */
 286
 287 #define REDRAW_PENDING          (1 << 0)
 288 #define SELECTED                (1 << 1)
 289 #define GOT_FOCUS               (1 << 2)
 290 #define BUTTON_DELETED          (1 << 3)
 291 /*
 292  * Declaration of variables shared between the files in the button module.
 293  */
 294
 295 extern Tk_ClassProcs tkpButtonProcs;
 296
 297 /*
 298  * Declaration of procedures used in the implementation of the button
 299  * widget.
 300  */
 301
 302 #ifndef TkpButtonSetDefaults
 303 EXTERN void             TkpButtonSetDefaults _ANSI_ARGS_((
 304                             Tk_OptionSpec *specPtr));
 305 #endif
 306 EXTERN void             TkButtonWorldChanged _ANSI_ARGS_((
 307                             ClientData instanceData));
 308 EXTERN void             TkpComputeButtonGeometry _ANSI_ARGS_((
 309                             TkButton *butPtr));
 310 EXTERN TkButton *       TkpCreateButton _ANSI_ARGS_((Tk_Window tkwin));
 311 #ifndef TkpDestroyButton
 312 EXTERN void             TkpDestroyButton _ANSI_ARGS_((TkButton *butPtr));
 313 #endif
 314 #ifndef TkpDisplayButton
 315 EXTERN void             TkpDisplayButton _ANSI_ARGS_((ClientData clientData));
 316 #endif
 317 EXTERN int              TkInvokeButton  _ANSI_ARGS_((TkButton *butPtr));
 318
 319 # undef TCL_STORAGE_CLASS
 320 # define TCL_STORAGE_CLASS DLLIMPORT
 321
 322 #endif /* _TKBUTTON */