tk.h

是初学者升入中级必看的书籍

/*
 * tk.h --
 *
 *	Declarations for Tk-related things that are visible
 *	outside of the Tk module itself.
 *
 * Copyright (c) 1989-1994 The Regents of the University of California.
 * Copyright (c) 1994 The Australian National University.
 * Copyright (c) 1994-1998 Sun Microsystems, Inc.
 * Copyright (c) 1998-2000 Ajuba Solutions.
 *
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
 * RCS: @(#) $Id: tk.h,v 1.74.2.3 2003/10/03 16:32:39 dgp Exp $
 */

#ifndef _TK
#define _TK

/*
 * For C++ compilers, use extern "C"
 */

#ifdef __cplusplus
extern "C" {
#endif

/*
 * When version numbers change here, you must also go into the following files
 * and update the version numbers:
 *
 * library/tk.tcl	(only if Major.minor changes, not patchlevel)
 * unix/configure.in	(2 LOC Major, 2 LOC minor, 1 LOC patch)
 * win/configure.in	(as above)
 * win/makefile.vc	(not patchlevel)
 * README		(sections 0 and 1)
 * mac/README		(not patchlevel)
 * macosx/Wish.pbproj/project.pbxproj
 * 			(14 LOC total, 4 LOC patch)
 * win/README		(not patchlevel)
 * unix/README		(not patchlevel)
 * unix/tk.spec		(3 LOC Major/Minor, 2 LOC patch)
 * win/tcl.m4		(not patchlevel)
 *
 * You may also need to update some of these files when the numbers change
 * for the version of Tcl that this release of Tk is compiled against.
 */

#define TK_MAJOR_VERSION   8
#define TK_MINOR_VERSION   4
#define TK_RELEASE_LEVEL   TCL_FINAL_RELEASE
#define TK_RELEASE_SERIAL  5

#define TK_VERSION	"8.4"
#define TK_PATCH_LEVEL	"8.4.5"

/*
 * The following definitions set up the proper options for Macintosh
 * compilers.  We use this method because there is no autoconf equivalent.
 */

#if defined(MAC_TCL) || defined(MAC_OSX_TK)
#   ifndef REDO_KEYSYM_LOOKUP
#	define REDO_KEYSYM_LOOKUP
#   endif
#endif

#ifndef _TCL
#   include <tcl.h>
#   if (TCL_MAJOR_VERSION != 8) || (TCL_MINOR_VERSION != 4)
#	error Tk 8.4 must be compiled with tcl.h from Tcl 8.4
#   endif
#endif

/* 
 * A special definition used to allow this header file to be included
 * from windows or mac resource files so that they can obtain version
 * information.  RC_INVOKED is defined by default by the windows RC tool
 * and manually set for macintosh.
 *
 * Resource compilers don't like all the C stuff, like typedefs and
 * procedure declarations, that occur below, so block them out.
 */
    
#ifndef RC_INVOKED
    
#ifndef _XLIB_H
#   if defined (MAC_TCL)
#	include <Xlib.h>
#	include <X.h>
#   elif defined(MAC_OSX_TK)
#	include <X11/Xlib.h>
#	include <X11/X.h>
#   else
#	include <X11/Xlib.h>
#   endif
#endif
#ifdef __STDC__
#   include <stddef.h>
#endif

#ifdef BUILD_tk
# undef TCL_STORAGE_CLASS
# define TCL_STORAGE_CLASS DLLEXPORT
#endif

/*
 * Decide whether or not to use input methods.
 */

#ifdef XNQueryInputStyle
#define TK_USE_INPUT_METHODS
#endif

/*
 * Dummy types that are used by clients:
 */

typedef struct Tk_BindingTable_ *Tk_BindingTable;
typedef struct Tk_Canvas_ *Tk_Canvas;
typedef struct Tk_Cursor_ *Tk_Cursor;
typedef struct Tk_ErrorHandler_ *Tk_ErrorHandler;
typedef struct Tk_Font_ *Tk_Font;
typedef struct Tk_Image__ *Tk_Image;
typedef struct Tk_ImageMaster_ *Tk_ImageMaster;
typedef struct Tk_OptionTable_ *Tk_OptionTable;
typedef struct Tk_PostscriptInfo_ *Tk_PostscriptInfo;
typedef struct Tk_TextLayout_ *Tk_TextLayout;
typedef struct Tk_Window_ *Tk_Window;
typedef struct Tk_3DBorder_ *Tk_3DBorder;
typedef struct Tk_Style_ *Tk_Style;
typedef struct Tk_StyleEngine_ *Tk_StyleEngine;
typedef struct Tk_StyledElement_ *Tk_StyledElement;

/*
 * Additional types exported to clients.
 */

typedef CONST char *Tk_Uid;

/*
 * The enum below defines the valid types for Tk configuration options
 * as implemented by Tk_InitOptions, Tk_SetOptions, etc.
 */

typedef enum {
    TK_OPTION_BOOLEAN,
    TK_OPTION_INT,
    TK_OPTION_DOUBLE,
    TK_OPTION_STRING,
    TK_OPTION_STRING_TABLE,
    TK_OPTION_COLOR,
    TK_OPTION_FONT,
    TK_OPTION_BITMAP,
    TK_OPTION_BORDER,
    TK_OPTION_RELIEF,
    TK_OPTION_CURSOR,
    TK_OPTION_JUSTIFY,
    TK_OPTION_ANCHOR,
    TK_OPTION_SYNONYM,
    TK_OPTION_PIXELS,
    TK_OPTION_WINDOW,
    TK_OPTION_END,
    TK_OPTION_CUSTOM,
    TK_OPTION_STYLE
} Tk_OptionType;

/*
 * Structures of the following type are used by widgets to specify
 * their configuration options.  Typically each widget has a static
 * array of these structures, where each element of the array describes
 * a single configuration option.  The array is passed to
 * Tk_CreateOptionTable.
 */

typedef struct Tk_OptionSpec {
    Tk_OptionType type;		/* Type of option, such as TK_OPTION_COLOR; 
				 * see definitions above. Last option in
				 * table must have type TK_OPTION_END. */
    char *optionName;		/* Name used to specify option in Tcl	
				 * commands. */
    char *dbName;		/* Name for option in option database. */
    char *dbClass;		/* Class for option in database. */
    char *defValue;		/* Default value for option if not specified
				 * in command line, the option database,
				 * or the system. */
    int objOffset;		/* Where in record to store a Tcl_Obj * that
				 * holds the value of this option, specified
				 * as an offset in bytes from the start of
				 * the record. Use the Tk_Offset macro to
				 * generate values for this.  -1 means don't
				 * store the Tcl_Obj in the record. */
    int internalOffset;		/* Where in record to store the internal
				 * representation of the value of this option,
				 * such as an int or XColor *.  This field
				 * is specified as an offset in bytes
				 * from the start of the record. Use the
				 * Tk_Offset macro to generate values for it.
				 * -1 means don't store the internal
				 * representation in the record. */
    int flags;			/* Any combination of the values defined
				 * below. */
    ClientData clientData;	/* An alternate place to put option-specific
    				 * data. Used for the monochrome default value
				 * for colors, etc. */
    int typeMask;		/* An arbitrary bit mask defined by the
				 * class manager; typically bits correspond
				 * to certain kinds of options such as all
				 * those that require a redisplay when they
				 * change.  Tk_SetOptions returns the bit-wise
				 * OR of the typeMasks of all options that
				 * were changed. */
} Tk_OptionSpec;

/*
 * Flag values for Tk_OptionSpec structures.  These flags are shared by
 * Tk_ConfigSpec structures, so be sure to coordinate any changes
 * carefully.
 */

#define TK_OPTION_NULL_OK		(1 << 0)
#define TK_OPTION_DONT_SET_DEFAULT	(1 << 3)

/*
 * The following structure and function types are used by TK_OPTION_CUSTOM
 * options; the structure holds pointers to the functions needed by the Tk
 * option config code to handle a custom option.
 */

typedef int (Tk_CustomOptionSetProc) _ANSI_ARGS_((ClientData clientData,
	Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj **value, char *widgRec,
	int offset, char *saveInternalPtr, int flags));
typedef Tcl_Obj *(Tk_CustomOptionGetProc) _ANSI_ARGS_((ClientData clientData,
	Tk_Window tkwin, char *widgRec, int offset));
typedef void (Tk_CustomOptionRestoreProc) _ANSI_ARGS_((ClientData clientData,
	Tk_Window tkwin, char *internalPtr, char *saveInternalPtr));
typedef void (Tk_CustomOptionFreeProc) _ANSI_ARGS_((ClientData clientData,
	Tk_Window tkwin, char *internalPtr));
    
typedef struct Tk_ObjCustomOption {
    char *name;				/* Name of the custom option. */
    Tk_CustomOptionSetProc *setProc;	/* Function to use to set a record's
					 * option value from a Tcl_Obj */
    Tk_CustomOptionGetProc *getProc;	/* Function to use to get a Tcl_Obj
					 * representation from an internal
					 * representation of an option. */
    Tk_CustomOptionRestoreProc *restoreProc;	/* Function to use to restore a
						 * saved value for the internal
						 * representation. */
    Tk_CustomOptionFreeProc *freeProc;	/* Function to use to free the internal
					 * representation of an option. */
    ClientData clientData;		/* Arbitrary one-word value passed to
					 * the handling procs. */
} Tk_ObjCustomOption;


/*
 * Macro to use to fill in "offset" fields of the Tk_OptionSpec.
 * struct.  Computes number of bytes from beginning of structure
 * to a given field.
 */

#ifdef offsetof
#define Tk_Offset(type, field) ((int) offsetof(type, field))
#else
#define Tk_Offset(type, field) ((int) ((char *) &((type *) 0)->field))
#endif

/*
 * The following two structures are used for error handling.  When
 * configuration options are being modified, the old values are
 * saved in a Tk_SavedOptions structure.  If an error occurs, then the
 * contents of the structure can be used to restore all of the old
 * values.  The contents of this structure are for the private use
 * Tk.  No-one outside Tk should ever read or write any of the fields
 * of these structures.
 */

typedef struct Tk_SavedOption {
    struct TkOption *optionPtr;		/* Points to information that describes
					 * the option. */
    Tcl_Obj *valuePtr;			/* The old value of the option, in
					 * the form of a Tcl object; may be
					 * NULL if the value wasn't saved as
					 * an object. */
    double internalForm;		/* The old value of the option, in
					 * some internal representation such
					 * as an int or (XColor *).  Valid
					 * only if optionPtr->specPtr->objOffset
					 * is < 0.  The space must be large
					 * enough to accommodate a double, a
					 * long, or a pointer; right now it
					 * looks like a double is big
					 * enough.  Also, using a double
					 * guarantees that the field is
					 * properly aligned for storing large
					 * values. */
} Tk_SavedOption;

#ifdef TCL_MEM_DEBUG
#   define TK_NUM_SAVED_OPTIONS 2
#else
#   define TK_NUM_SAVED_OPTIONS 20
#endif

typedef struct Tk_SavedOptions {
    char *recordPtr;			/* The data structure in which to
					 * restore configuration options. */
    Tk_Window tkwin;			/* Window associated with recordPtr;
					 * needed to restore certain options. */
    int numItems;			/* The number of valid items in 
					 * items field. */
    Tk_SavedOption items[TK_NUM_SAVED_OPTIONS];
					/* Items used to hold old values. */
    struct Tk_SavedOptions *nextPtr;	/* Points to next structure in list;	
					 * needed if too many options changed
					 * to hold all the old values in a
					 * single structure.  NULL means no
					 * more structures. */
} Tk_SavedOptions;

/*
 * Structure used to describe application-specific configuration
 * options:  indicates procedures to call to parse an option and
 * to return a text string describing an option. THESE ARE
 * DEPRECATED; PLEASE USE THE NEW STRUCTURES LISTED ABOVE.
 */

/*
 * This is a temporary flag used while tkObjConfig and new widgets
 * are in development.
 */

#ifndef __NO_OLD_CONFIG

typedef int (Tk_OptionParseProc) _ANSI_ARGS_((ClientData clientData,
	Tcl_Interp *interp, Tk_Window tkwin, CONST84 char *value, char *widgRec,
	int offset));
typedef char *(Tk_OptionPrintProc) _ANSI_ARGS_((ClientData clientData,
	Tk_Window tkwin, char *widgRec, int offset,
	Tcl_FreeProc **freeProcPtr));

typedef struct Tk_CustomOption {
    Tk_OptionParseProc *parseProc;	/* Procedure to call to parse an
					 * option and store it in converted
					 * form. */
    Tk_OptionPrintProc *printProc;	/* Procedure to return a printable
					 * string describing an existing
					 * option. */
    ClientData clientData;		/* Arbitrary one-word value used by
					 * option parser:  passed to
					 * parseProc and printProc. */
} Tk_CustomOption;

/*
 * Structure used to specify information for Tk_ConfigureWidget.  Each
 * structure gives complete information for one option, including
 * how the option is specified on the command line, where it appears
 * in the option database, etc.
 */

typedef struct Tk_ConfigSpec {
    int type;			/* Type of option, such as TK_CONFIG_COLOR;
				 * see definitions below.  Last option in
				 * table must have type TK_CONFIG_END. */
    char *argvName;		/* Switch used to specify option in argv.
				 * NULL means this spec is part of a group. */
    Tk_Uid dbName;		/* Name for option in option database. */
    Tk_Uid dbClass;		/* Class for option in database. */
    Tk_Uid defValue;		/* Default value for option if not
				 * specified in command line or database. */
    int offset;			/* Where in widget record to store value;
				 * use Tk_Offset macro to generate values
				 * for this. */
    int specFlags;		/* Any combination of the values defined
				 * below;  other bits are used internally
				 * by tkConfig.c. */
    Tk_CustomOption *customPtr;	/* If type is TK_CONFIG_CUSTOM then this is
				 * a pointer to info about how to parse and
				 * print the option.  Otherwise it is
				 * irrelevant. */
} Tk_ConfigSpec;

/*
 * Type values for Tk_ConfigSpec structures.  See the user
 * documentation for details.
 */

typedef enum {
    TK_CONFIG_BOOLEAN, TK_CONFIG_INT, TK_CONFIG_DOUBLE, TK_CONFIG_STRING,
    TK_CONFIG_UID, TK_CONFIG_COLOR, TK_CONFIG_FONT, TK_CONFIG_BITMAP,
    TK_CONFIG_BORDER, TK_CONFIG_RELIEF, TK_CONFIG_CURSOR, 
    TK_CONFIG_ACTIVE_CURSOR, TK_CONFIG_JUSTIFY, TK_CONFIG_ANCHOR, 
    TK_CONFIG_SYNONYM, TK_CONFIG_CAP_STYLE, TK_CONFIG_JOIN_STYLE,
    TK_CONFIG_PIXELS, TK_CONFIG_MM, TK_CONFIG_WINDOW, TK_CONFIG_CUSTOM, 
    TK_CONFIG_END
} Tk_ConfigTypes;

/*
 * Possible values for flags argument to Tk_ConfigureWidget:
 */

#define TK_CONFIG_ARGV_ONLY	1
#define TK_CONFIG_OBJS		0x80