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 44-14 on page 632. 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. It is described in the TkInit man page. 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. They are described in the MapWindow man page. The Tk_MoveToplevelWindow call is used to position a top-level window. 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. 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_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_DefineCursor, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowColormap, Tk_UndefineCursor, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorderPixmap, Tk_MoveWindow, and Tk_SetWindowBorder. The 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. 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_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_InternalBorderWidth, 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. The Tk_GetScrollInfo parses 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 Tcl can handle its events. 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. Delete the handler with Tk_DeleteGenericHandler. Event Bindings The routines that manage bindings are exported by the Tk library so you can manage bindings yourself. For example, the canvas widget does this 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. These are described in the BindTable man page. 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 The Tk_CreateImageType procedure is used to register the implementation of a new image type. The registration includes 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. There are support routines for the managers of new item types. The CanvTkwin man page describes 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 only appears in it 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 a collection of routines described by the 3DBorder man page. The routines are 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. 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 it 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. 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. | 
