An Overview of the Tk C Library

Main Programs and Command-Line Arguments

The Tk_Main procedure does the standard setup for your application's main window and event loop. The Tk_ParseArgv procedure parses command-line arguments. This procedure is designed for use by main programs. It uses a table of Tk_ArgvInfo records to describe your program's arguments. These procedures are illustrated by Example 47-14 on page 721.

If your extension uses the Tk library, you should link against the Tk stub library. In this case, you must call Tk_InitStubs in your extension's initialization routine.

Creating Windows

The Tk_Init procedure creates the main window for your application. The Tk_CreateWindow and Tk_CreateWindowFromPath are used to create windows for widgets. The actual creation of the window is delayed until an idle point. You can force the window to be created with Tk_MakeWindowExist or destroy a window with Tk_DestroyWindow.

The Tk_MainWindow procedure returns the handle on the application's main window. The Tk_MapWindow and Tk_UnmapWindow are used to display and withdraw a window, respectively. The Tk_MoveToplevelWindow call is used to position a top-level window. Tk_GetNumMainWindows returns the number of main windows opened by the current process.

Translate between window names and the Tk_Window type with Tk_Name, Tk_PathName, and Tk_NameToWindow. You can convert from an operating system window ID to the corresponding Tk_Window with Tk_IdToWindow procedure.

Tk_SetClassProcs registers widget-specific handlers to react to system wide font and color changes, to create platform-specific windows, and to handle modal input loops.

Application Name for Send

The name of the application is defined or changed with Tk_SetAppName. This name is used when other applications send it Tcl commands using the send command.

Configuring Windows

The configuration of a window includes its width, height, cursor, and so on. Tk provides a set of routines that configure a window and also cache the results. This makes it efficient to query these settings because the system does not need to be contacted. The window configuration routines are Tk_ConfigureWindow, Tk_ResizeWindow, Tk_MoveWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_DefineCursor, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowColormap, Tk_UndefineCursor, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorderPixmap, Tk_MoveWindow, and Tk_SetWindowBorder.

Command Options

The Tk_CreateOptionTable, Tk_SetOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_RestoreSavedOptions, Tk_FreeSavedOptions, Tk_InitOptions, Tk_FreeConfigOptions, and Tk_DeleteOptionTable procedures are used to parse command line options with procedures that use Tcl_Obj values. Canvas item types are supported by Tk_CanvasTagsOption.

Tk_AddOption is used to add a value to the option database. This creates defaults for command line options that are not explicitly passed to widget commands.

Window Coordinates

The coordinates of a widget relative to the root window (the main screen) are returned by Tk_GetRootCoords. The Tk_GetVRootGeometry procedure returns the size and position of a window relative to the virtual root window. The Tk_CoordsToWindow procedure locates the window under a given coordinate.

Window Stacking Order

Control the stacking order of windows in the window hierarchy with Tk_RestackWindow. Windows higher in the stacking order obscure lower windows.

Window Information

Tk keeps lots of information associated with each window, or widget. The following calls are fast macros that return the information without calling the X server: Tk_WindowId, Tk_Parent, Tk_StrictMotif, Tk_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsMapped, Tk_IsTopLevel, Tk_IsContainer, Tk_IsEmbedded, Tk_ReqWidth, Tk_ReqHeight, Tk_InternalBorderWidth, Tk_MinReqWidth, Tk_MinReqHeight, Tk_InternalBorderLeft, Tk_InternalBorderRight, Tk_InternalBorderTop, Tk_InternalBorderBottom, Tk_Visual, Tk_Depth, and Tk_Colormap.

Configuring Widget Attributes

The Tk_ConfigureWidget procedure parses command-line specification of attributes and allocates resources like colors and fonts. Related procedures include Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue, and Tk_FreeOptions. Tk_GetScrollInfo and Tk_GetScrollInfoObj parse arguments to scrolling commands like the xview and yview widget operations.

The Selection and Clipboard

Retrieve the current selection with Tk_GetSelection. Clear the selection with Tk_ClearSelection. Register a handler for selection requests with Tk_CreateSelHandler. Unregister the handler with Tk_DeleteSelHandler. Claim ownership of the selection with Tk_OwnSelection. Manipulate the clipboard with Tk_ClipboardClear and Tk_ClipboardAppend.

Event Loop Interface

The standard event loop is implemented by Tk_MainLoop. If you write your own event loop, you need to call Tcl_DoOneEvent so that Tcl can handle its events. Call Tcl_DoOneEvent with TCL_DONT_WAIT until it returns 0 to indicate no more events need to be processed. If you read window events directly, (e.g., through Tk_CreateGenericHandler), you can dispatch to the correct handler for the event with Tk_HandleEvent. Note that most of the event loop is implemented in the Tcl library, except for Tk_MainLoop and the window event handler interface that are part of the Tk library. You can create handlers for file, timer, and idle events after this call. Restrict or delay events with the Tk_RestrictEvent procedure.

Handling Window Events

Use Tk_CreateEventHandler to set up a handler for specific window events. Widget implementations need a handler for expose and resize events, for example. Remove the registration with Tk_DeleteEventHandler. You can set up a handler for all window events with Tk_CreateGenericHandler. This is useful in some modal interactions where you have to poll for a certain event. If you get an event you do not want to handle yourself, you can push it onto the event queue with Tk_QueueWindowEvent. Tk_CollapseMotionEvents will eliminate extra motion events from the queue. Tk_RestrictEvents will filter and selectively delay events. Delete the event handler with Tk_DeleteGenericHandler. Tk_CreateClientMessageHandler is used for WM_PROTOCOL events. Delete the handler with Tk_DeleteClientMessageHandler.

Event Bindings

The routines that manage bindings are exported by the Tk library, so you can manage bindings yourself. For example, the canvas widget uses the API to implement bindings on canvas items. The procedures are Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_BindEvent, Tk_GetBinding, Tk_GetAllBindings, and Tk_DeleteAllBindings.

Keyboard Grab

Tk_Grab and Tk_Ungrab change the state of any keyboard grab, which is used to restrict input to a particular window.

Handling Graphic Protocol Errors

You can handle graphic protocol errors by registering a handler with Tk_CreateErrorHandler. Unregister it with Tk_DeleteErrorHandler. UNIX has an asynchronous interface, so the error will be reported sometime after the offending call was made. You can call the Xlib XSynchronize routine to turn off the asynchronous behavior in order to help you debug.

Using the Resource Database

The Tk_GetOption procedure looks up items in the resource database. The resource class of a window is set with Tk_SetClass, and the current class setting is retrieved with Tk_Class.

Managing Bitmaps

Tk maintains a registry of bitmaps by name, (e.g., gray50 and questhead). You can define new bitmaps with Tk_DefineBitmap, and you can get a handle on the bitmap from its name with Tk_GetBitmap. Related procedures include Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_GetBitmapFromData, Tk_FreeBitmap, Tk_AllocBitmapFromObj, Tk_GetBitmapFromObj, and Tk_FreeBitmapFromObj.

Creating New Image Types

Tk_CreateImageType and Tk_InitImageArgs are used to register the implementation of a new image type. The registration includes image command options and several procedures that call back into the implementation to support creation, display, and deletion of images. When an image changes, the widgets that display it are notified by calling Tk_ImageChanged. The Tk_NameOfImage procedure returns the Tcl name of an image. The Tk_GetImageMasterData returns the client data associated with an image type.

Using an Image in a Widget

The following routines support widgets that display images. Tk_GetImage maps from the name to a Tk_Image data structure. Tk_RedrawImage causes the image to update its display. Tk_SizeOfImage tells you how big it is. When the image is no longer in use, call Tk_FreeImage. The Tk_DeleteImage deletes an image.

Photo Image Types

One of the image types is photo, which has its own C interface for defining new formats. The job of a format handler is to read and write different image formats such as GIF or JPEG so that the photo image can display them. The Tk_CreatePhotoImageFormat procedure sets up the interface. There are several support routines for photo format handlers. The Tk_FindPhoto procedure maps from a photo name to its associated Tk_PhotoHandle data structure. The image is updated with Tk_PhotoBlank, Tk_PhotoPutBlock, and Tk_PhotoPutZoomedBlock. The image values can be obtained with Tk_PhotoGetImage. The size of the image can be manipulated with Tk_PhotoExpand, Tk_PhotoGetSize, and Tk_PhotoSetSize

Canvas Object Support

The C interface for defining new canvas items is exported via the Tk_CreateItemType procedure. The description for a canvas item includes a set of procedures that the canvas widget uses to call the implementation of the canvas item type. The Tk_GetItemTypes returns information about all types of canvas objects. The support routines for the managers of new item types are Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasTkwin, Tk_CanvasWindowCoords, and Tk_CanvasEventuallyRedraw. The following procedures help with the generation of postscript: Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, and Tk_CanvasPsStipple. If you are manipulating text items directly, then you can use the Tk_CanvasGetTextInfo procedure to get a description of the selection state and other details about the text item.

Geometry Management

A widget requests a certain size with the Tk_GeometryRequest procedure. If it draws a border inside that area, it calls Tk_SetInternalBorder. The geometry manager responds to these requests, although the widget may get a different size. The Tk_ManageGeometry procedure sets up the relationship between the geometry manager and a widget. The Tk_MaintainGeometry procedure arranges for one window to stay at a fixed position relative to another widget. This is used by the place geometry manager. The relationship is broken with the Tk_UnmaintainGeometry call. The Tk_SetGrid call enables gridded geometry management. The grid is turned off with Tk_UnsetGrid.

String Identifiers (UIDS)

Tk maintains a database of string values such that a string appears in it only once. The Tk_Uid type refers to such a string. You can test for equality by using the value of Tk_Uid, which is the string's address, as an identifier. A Tk_Uid is used as a name in the various GetByName calls introduced below. The Tk_GetUid procedure installs a string into the registry.

Note: The table of Tk_Uid values is a memory leak. The leak is not serious under normal operation. However, if you continually register new strings as Tk_Uid values, then the hash table that records them continues to grow. This table is not cleaned up when Tk is finalized. The mapping from a string to a constant is better served by the Tcl_GetIndexFromObj call.

Colors, Colormaps, and Visuals

Use Tk_GetColor, Tk_GetColorByValue, Tk_AllocColorFromObj, and Tk_GetColorFromObj to allocate a color. You can retrieve the string name of a color with Tk_NameOfColor. When you are done using a color, you need to call Tk_FreeColor or Tk_FreeColorFromObj. You can get a graphics context for drawing a particular color with Tk_GCForColor. Colors are shared among widgets, so it is important to free them when you are done using them. Use Tk_GetColormap and Tk_FreeColormap to allocate and free a colormap. Colormaps are shared, if possible, so you should use these routines instead of the platform-specific routines to allocate colormaps. The window's visual type is set with Tk_SetWindowVisual. You can get a visual context with Tk_GetVisual.

3D Borders

The three-dimensional relief used for widget borders is supported by Tk_Get3DBorder, Tk_3DBorderGC, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Free3DBorder, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_Alloc3DBorderFromObj, Tk_Get3DBorderFromObj, and Tk_Free3DBorderFromObj. Widgets use Tk_DrawFocusHighlight to draw their focus highlight.

Mouse Cursors

Allocate a cursor with Tk_GetCursor, Tk_GetCursorFromData, Tk_GetCursorFromObj, and Tk_AllocCursorFromObj. Map back to the name of the cursor with Tk_NameOfCursor. Release the cursor resource with Tk_FreeCursor or Tk_FreeCursorFromObj. Tk_SetCaretPos sets the per-window caret position, which is used for over-the-spot X Input Methods and Windows IME windows.

Fonts and Text Display

Allocate a font with Tk_GetFont, Tk_GetFontFromObj, or Tk_AllocFontFromObj. Get the name of a font with Tk_NameOfFont. Release the font with Tk_FreeFont or Tk_FreeFontFromObj. Once you have a font, you can get information about it with Tk_FontId, Tk_FontMetrics, and Tk_PostscriptFontName. Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, and Tk_UnderlineChars measure and display simple strings. Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_PointToChar, Tk_IntersectTextLayout, and Tk_TextLayoutToPostscript measure and display multiline, justified text.

Graphics Contexts

A graphics context records information about colors, fonts, line drawing styles, and so on. Instead of specifying this information on every graphics operation, a graphics context is created first. Individual graphics operations specify a particular graphic context. Allocate a graphics context with Tk_GetGC and free it with Tk_FreeGC.

Allocate a Pixmap

A pixmap is a simple color image. Allocate and free pixmaps with Tk_GetPixmap and Tk_FreePixmap.

Screen Measurements

Translate between strings like 4c or 72p and screen distances with Tk_GetPixels, Tk_GetPixelsFromObj, Tk_GetMMFromObj, and Tk_GetScreenMM. The first call returns pixels (integers); the second returns millimeters as a floating point number.

Relief Style

Window frames are drawn with a particular 3D relief such as raised, sunken, or grooved. Translate between relief styles and names with Tk_GetRelief, Tk_GetReliefFromObj, and Tk_NameOfRelief.

Text Anchor Positions

Anchor positions specify the position of a window within its geometry parcel. Translate between strings and anchor positions with Tk_GetAnchor, Tk_GetAnchorFromObj, and Tk_NameOfAnchor.

Line Cap Styles

The line cap defines how the end point of a line is drawn. Translate between line cap styles and names with Tk_GetCapStyle and Tk_NameOfCapStyle.

Line Join Styles

The line join style defines how the junction between two line segments is drawn. Translate between line join styles and names with Tk_GetJoinStyle and Tk_NameOfJoinStyle.

Dashed Lines

Tk_GetDash converts from a string to a dash pattern.

Text Justification Styles

Translate between line justification styles and names with Tk_GetJustify, Tk_GetJustifyFromObj, and Tk_NameOfJustify.

Atoms

An atom is an integer that references a string that has been registered with the system. Tk maintains a cache of the atom registry to avoid contacting the system when atoms are used. Use Tk_InternAtom to install an atom in the registry, and Tk_GetAtomName to return the name given an atom.

X Resource ID Management

Each window system resource like a color or pixmap has a resource ID associated with it. The Tk_FreeXId call releases an ID so it can be reused. This is used, for example, by routines like Tk_FreeColor and Tk_FreePixmap.

Windows Application Handles

Tk_GetHINSTANCE returns the global application handle for Windows. Tk_GetHWND returns the Windows HWND identifier for the Tk window. Tk_HWNDToWindow maps from the Windows handle to the corresponding Tk window.