Index: Lib/lib-tk/Tkinter.py =================================================================== --- Lib/lib-tk/Tkinter.py (revision 73222) +++ Lib/lib-tk/Tkinter.py (working copy) @@ -1189,7 +1189,9 @@ if type(cnf) is StringType: x = self.tk.split( self.tk.call(_flatten((self._w, cmd, '-'+cnf)))) - return (x[0][1:],) + x[1:] + if x: + return (x[0][1:],) + x[1:] + return None self.tk.call(_flatten((self._w, cmd)) + self._options(cnf)) # These used to be defined in Widget: def configure(self, cnf=None, **kw): @@ -2128,16 +2130,20 @@ to nearest multiple of GRIDSPACING units.""" return getdouble(self.tk.call( self._w, 'canvasy', screeny, gridspacing)) - def coords(self, *args): - """Return a list of coordinates for the item given in ARGS.""" + def coords(self, tagOrId, *args): + """Return or set the coordinates for an item. + + To set the coordinates for an item, either a tuple or multiple values + should be passed.""" # XXX Should use _flatten on args + # XXX why ? return map(getdouble, self.tk.splitlist( - self.tk.call((self._w, 'coords') + args))) + self.tk.call((self._w, 'coords', tagOrId) + args))) def _create(self, itemType, args, kw): # Args: (val, val, ..., cnf={}) """Internal function.""" args = _flatten(args) - cnf = args[-1] + cnf = args[-1] if len(args) else None if type(cnf) in (DictionaryType, TupleType): args = args[:-1] else: @@ -2172,17 +2178,28 @@ def create_window(self, *args, **kw): """Create window with coordinates x1,y1,x2,y2.""" return self._create('window', args, kw) - def dchars(self, *args): - """Delete characters of text items identified by tag or id in ARGS (possibly - several times) from FIRST to LAST character (including).""" - self.tk.call((self._w, 'dchars') + args) + def dchars(self, tagOrId, first, last=None): + """For each item given by tagOrId, delete the characters, or + coordinates, in the range given by first and last, inclusive. + If some of the items given by tagOrId do not support indexing + operations then they ignore dchars. Text items interpret first + and last as indices to a character, line and polygon items + interpret them as indices to a coordinate (an x, y pair). + + If last is omitted, it defaults to first. + """ + self.tk.call(self._w, 'dchars', tagOrId, first, last) def delete(self, *args): - """Delete items identified by all tag or ids contained in ARGS.""" + """Delete all items identified by the tags or ids contained in ARGS.""" self.tk.call((self._w, 'delete') + args) - def dtag(self, *args): - """Delete tag or id given as last arguments in ARGS from items - identified by first argument in ARGS.""" - self.tk.call((self._w, 'dtag') + args) + def dtag(self, tagOrId, tagToDelete=None): + """ + For each of the items given by tagOrId, delete the tag given by + tagToDelete from the list of those associated with the item. + If an item does not have the tag tagToDelete then the item is + unaffected. If tagToDelete is omitted then it defaults to tagOrId. + """ + self.tk.call(self._w, 'dtag', tagOrId, tagToDelete) def find(self, *args): """Internal function.""" return self._getints( @@ -2213,24 +2230,56 @@ def find_withtag(self, tagOrId): """Return all items with TAGORID.""" return self.find('withtag', tagOrId) - def focus(self, *args): - """Set focus to the first item specified in ARGS.""" - return self.tk.call((self._w, 'focus') + args) - def gettags(self, *args): - """Return tags associated with the first item specified in ARGS.""" - return self.tk.splitlist( - self.tk.call((self._w, 'gettags') + args)) - def icursor(self, *args): - """Set cursor at position POS in the item identified by TAGORID. - In ARGS TAGORID must be first.""" - self.tk.call((self._w, 'icursor') + args) - def index(self, *args): - """Return position of cursor as integer in item specified in ARGS.""" - return getint(self.tk.call((self._w, 'index') + args)) - def insert(self, *args): - """Insert TEXT in item TAGORID at position POS. ARGS must - be TAGORID POS TEXT.""" - self.tk.call((self._w, 'insert') + args) + def focus(self, tagOrId=None): + """Set the keyboard focus to the item given by tagOrId. + + If tagOrId refers to several items, then the focus is set to the + first such item in the display list that supports the insertion + cursor. + If tagOrId does not refer to any items, or if none of them support + the insertion cursor, then the focus is not changed. + If tagOrId is an empty string, then the focus item is reset so + that no item has the focus. + If tagOrId is not specified then the command returns the id for the + item that currently has the focus, or None if no item has the focus. + """ + ret = self.tk.call(self._w, 'focus', tagOrId) + if tagOrId is None: + return None if ret == '' else getint(ret) + def gettags(self, tagOrId): + """Return the tags associated with the item given by tagOrId. + If tagOrId refers to more than one item, then the tags are returned + from the first such item in the display list. If tagOrId does not + refer to any items, or if the item contains no tags, then an + empty tuple is returned.""" + return self.tk.splitlist(self.tk.call(self._w, 'gettags', tagOrId)) + def icursor(self, tagOrId, index): + """Set the positions of the insertion cursor for item(s) given by + tagOrId to just before the character whose position is given by + index. + + If some or all of the items given by tagOrId do not support an + insertion cursor then icursor has no effect on them. + + Note: the insertion cursor is only displayed in an item if that + item currently has the keyboard focus, but the cursor position + may be set even when the item does not have the focus. + """ + self.tk.call(self._w, 'icursor', tagOrId, index) + def index(self, tagOrId, index): + """Return an integer giving the numerical index within tagOrId + corresponding to INDEX.""" + return getint(self.tk.call(self._w, 'index', tagOrId, index)) + def insert(self, tagOrId, pos, *args): + """For each of the items given by tagOrId, if the item supports + text or coordinate, insert args into the item's text just before + the character, or coordinate, whose index is POS. + + Text items interpret POS as an index to a character, line and + polygon items interpret it as an index to a coordinate + (an x, y pair). For lines and polygons args must be a valid + coordinate sequence.""" + self.tk.call(self._w, 'insert', tagOrId, pos, *args) def itemcget(self, tagOrId, option): """Return the resource value for an OPTION for item TAGORID.""" return self.tk.call( @@ -2248,29 +2297,35 @@ # so the preferred name for them is tag_lower, tag_raise # (similar to tag_bind, and similar to the Text widget); # unfortunately can't delete the old ones yet (maybe in 1.6) - def tag_lower(self, *args): + def tag_lower(self, tagOrId, belowThis=None): """Lower an item TAGORID given in ARGS (optional below another item).""" - self.tk.call((self._w, 'lower') + args) + self.tk.call(self._w, 'lower', tagOrId, belowThis) lower = tag_lower - def move(self, *args): - """Move an item TAGORID given in ARGS.""" - self.tk.call((self._w, 'move') + args) + def move(self, tagOrId, xAmount, yAmount): + """Move each of the items given by tagOrId by adding xAmount to + the x-coordinate of each point associated with the item and yAmount + to the y-coordinate of each point associated with the item.""" + self.tk.call(self._w, 'move', tagOrId, xAmount, yAmount) def postscript(self, cnf={}, **kw): - """Print the contents of the canvas to a postscript - file. Valid options: colormap, colormode, file, fontmap, + """Generate a Postscript representation for part or all of the + canvas. If the 'file' option is specified then the Postscript is + written to a file, otherwise the Postscript is returned. + + Valid options: colormap, colormode, file, fontmap, height, pageanchor, pageheight, pagewidth, pagex, pagey, rotate, witdh, x, y.""" - return self.tk.call((self._w, 'postscript') + - self._options(cnf, kw)) - def tag_raise(self, *args): + return self.tk.call((self._w, 'postscript') + self._options(kw)) + def tag_raise(self, tagOrId, aboveThis=None): """Raise an item TAGORID given in ARGS (optional above another item).""" - self.tk.call((self._w, 'raise') + args) + self.tk.call(self._w, 'raise', tagOrId, aboveThis) lift = tkraise = tag_raise - def scale(self, *args): - """Scale item TAGORID with XORIGIN, YORIGIN, XSCALE, YSCALE.""" - self.tk.call((self._w, 'scale') + args) + def scale(self, tagOrId, xOrigin, yOrigin, xScale, yScale): + """Scale items identified by TAGORID with XORIGIN, YORIGIN, XSCALE, + YSCALE.""" + self.tk.call(self._w, 'scale', tagOrId, + xOrigin, yOrigin, xScale, yScale) def scan_mark(self, x, y): """Remember the current X, Y coordinates.""" self.tk.call(self._w, 'scan', 'mark', x, y)