1*cd17ce43SforsythNotes on the Tk implementation. 2*cd17ce43Sforsyth 3*cd17ce43SforsythGeneral 4*cd17ce43Sforsyth 5*cd17ce43Sforsyth TkTop represents a top-level window. 6*cd17ce43Sforsyth It holds pointers to the widgets created in that 7*cd17ce43Sforsyth window: 8*cd17ce43Sforsyth windows gives a list of all windows (this includes "." and any menu widgets) 9*cd17ce43Sforsyth root the list of all widgets, whether packed or not. 10*cd17ce43Sforsyth 11*cd17ce43Sforsyth Each Tk widget holds pointers to the widgets packed inside it, its slaves. 12*cd17ce43Sforsyth Widgets that do their own child widget management (canvas 13*cd17ce43Sforsyth and text) do not use the slaves list, but store pointers 14*cd17ce43Sforsyth to them in their own data structures. 15*cd17ce43Sforsyth 16*cd17ce43Sforsyth Each Tk widget, w, holds a pointer to the widget it's packed or stored inside. 17*cd17ce43Sforsyth 18*cd17ce43Sforsyth w->master 19*cd17ce43Sforsyth if it's packed or stored in a grid 20*cd17ce43Sforsyth w->parent 21*cd17ce43Sforsyth if it's a child widget of a canvas or text widget. 22*cd17ce43Sforsyth 23*cd17ce43Sforsyth A widget type is operated on through functions referred to in its TkMethod structure, 24*cd17ce43Sforsyth defined in that widget type's source file, and pointed to by the 25*cd17ce43Sforsyth method dispatch table, tkmethod, defined in xdata.c. 26*cd17ce43Sforsyth 27*cd17ce43Sforsyth utils.c contains the master table holding the built-in commands 28*cd17ce43Sforsyth (e.g. widget creation, focus, grab, etc) with their 29*cd17ce43Sforsyth associated functions. 30*cd17ce43Sforsyth 31*cd17ce43Sforsyth xdata.c holds the method table (tkmethod) mapping from 32*cd17ce43Sforsyth widget type to the method functions supported by individual widgets. 33*cd17ce43Sforsyth 34*cd17ce43Sforsyth 35*cd17ce43Sforsyth 36*cd17ce43SforsythCoordinates: 37*cd17ce43Sforsyth 38*cd17ce43Sforsyth A widget requests a particular size allocation 39*cd17ce43Sforsyth by setting its req.width and req.height fields. 40*cd17ce43Sforsyth The packer (or its parent) determines the actual 41*cd17ce43Sforsyth size allocation, and position and sets act.x, act.y, act.width 42*cd17ce43Sforsyth and act.height appropriately. 43*cd17ce43Sforsyth 44*cd17ce43Sforsyth The requested width and height do not include the 45*cd17ce43Sforsyth borderwidth, which is factored in additionally. 46*cd17ce43Sforsyth 47*cd17ce43Sforsyth Coordinates as delivered by the %x and %y verbs provided 48*cd17ce43Sforsyth by bind(9) are relative to the top left of the widget, 49*cd17ce43Sforsyth inside its border. I'll call this the "widget's coordinate system". 50*cd17ce43Sforsyth 51*cd17ce43Sforsyth The draw method of each widget type is provided with 52*cd17ce43Sforsyth an "origin" argument. 53*cd17ce43Sforsyth 54*cd17ce43Sforsyth (origin.x + act.x + borderwidth, origin.y + act.y + borderwidth) 55*cd17ce43Sforsyth 56*cd17ce43Sforsyth gives the screen coordinate of (0, 0) in the widget coordinate 57*cd17ce43Sforsyth system. 58*cd17ce43Sforsyth 59*cd17ce43Sforsyth 60*cd17ce43SforsythDirtiness 61*cd17ce43Sforsyth 62*cd17ce43Sforsyth Each widget has a "dirty" rectangle, the bounding 63*cd17ce43Sforsyth box of any changes that it needs to make visible. 64*cd17ce43Sforsyth This is in the widget's coordinate system. 65*cd17ce43Sforsyth 66*cd17ce43Sforsyth A widget does not have to update everything in 67*cd17ce43Sforsyth the dirty rectangle, unless the Tkrefresh flag 68*cd17ce43Sforsyth is set, in which case it must. 69*cd17ce43Sforsyth 70*cd17ce43Sforsyth A widget never has to draw anything outside of its dirty 71*cd17ce43Sforsyth rectangle. 72*cd17ce43Sforsyth 73*cd17ce43SforsythLocking 74*cd17ce43Sforsyth 75*cd17ce43Sforsyth Mostly, Tk is non-reentrant because the interpreter is held 76*cd17ce43Sforsyth when a call to, e.g. Tk_cmd, is made. 77*cd17ce43Sforsyth 78*cd17ce43Sforsyth However, when the display is remote, any access of the display 79*cd17ce43Sforsyth (drawing, stringsize, etc) can do a release() and therefore 80*cd17ce43Sforsyth let another thread access tk. 81*cd17ce43Sforsyth 82*cd17ce43Sforsyth The drawing code itself locks the display, so code invoked 83*cd17ce43Sforsyth from within a widgets draw() method is guaranteed 84*cd17ce43Sforsyth non-reentrant. 85*cd17ce43Sforsyth 86*cd17ce43Sforsyth If access to the draw device is required during code executed 87*cd17ce43Sforsyth in a non-drawing context (e.g. to calculate the size of a 88*cd17ce43Sforsyth string), care must be taken to lock the draw device 89*cd17ce43Sforsyth appropriately. Tk provides some convenience functions to do 90*cd17ce43Sforsyth this (e.g. tkstringsize). 91