take into account kerning and inter-character spacing in bounding box
[PyX.git] / pyx / attr.py
blob0b05769d0bc62c6303cd1dc64a8c00026e5567e3
1 # -*- encoding: utf-8 -*-
4 # Copyright (C) 2003-2004 Jörg Lehmann <joergl@users.sourceforge.net>
5 # Copyright (C) 2003-2004 Michael Schindler <m-schindler@users.sourceforge.net>
6 # Copyright (C) 2003-2013 André Wobst <wobsta@users.sourceforge.net>
8 # This file is part of PyX (http://pyx.sourceforge.net/).
10 # PyX is free software; you can redistribute it and/or modify
11 # it under the terms of the GNU General Public License as published by
12 # the Free Software Foundation; either version 2 of the License, or
13 # (at your option) any later version.
15 # PyX is distributed in the hope that it will be useful,
16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 # GNU General Public License for more details.
20 # You should have received a copy of the GNU General Public License
21 # along with PyX; if not, write to the Free Software
22 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
25 # some helper functions for the attribute handling
28 def mergeattrs(attrs):
29 """perform merging of the attribute list attrs as defined by the
30 merge methods of the attributes"""
31 newattrs = []
32 for a in attrs:
33 # XXX Do we really need this test?
34 if isinstance(a, attr):
35 newattrs = a.merge(newattrs)
36 else:
37 raise TypeError("only instances of class attr.attr are allowed")
38 return newattrs
41 def getattrs(attrs, getclasses):
42 """return all attributes in the attribute list attrs, which are
43 instances of one of the classes in getclasses"""
44 return [attr for attr in attrs if isinstance(attr, tuple(getclasses))]
47 def checkattrs(attrs, allowedclasses):
48 """check whether only attributes which are instances of classes in
49 allowedclasses are present in the attribute list attrs; if not it
50 raises a TypeError"""
51 if len(attrs) != len(getattrs(attrs, allowedclasses)):
52 for attr1, attr2 in zip(attrs, getattrs(attrs, allowedclasses)):
53 if attr1 is not attr2:
54 raise TypeError("instance %r not allowed" % attr1)
55 else:
56 raise TypeError("instance %r not allowed" % attrs[len(getattrs(attrs, allowedclasses))])
58 def refineattrs(attrs, defaults, allowedclasses, allow_none=True):
59 """combine the typical handling for attribues passed to a function in a
60 single call"""
61 # TODO the whole attribute handling needs some major documentation
62 if allow_none and attrs is None:
63 return None
64 checkattrs(attrs, allowedclasses)
65 return mergeattrs(defaults + attrs)
68 # attr class and simple descendants
71 class attr:
73 """ attr is the base class of all attributes, i.e., colors, decorators,
74 styles, text attributes and trafos"""
76 def merge(self, attrs):
77 """merge self into list of attrs
79 self may either be appended to attrs or inserted at a proper position
80 immediately before a dependent attribute. Attributes of the same type
81 should be removed, if redundant. Note that it is safe to modify
82 attrs."""
84 attrs.append(self)
85 return attrs
88 class exclusiveattr(attr):
90 """an attribute which swallows all but the last of the same type (specified
91 by the exlusiveclass argument to the constructor) in an attribute list"""
93 def __init__(self, exclusiveclass):
94 self.exclusiveclass = exclusiveclass
96 def merge(self, attrs):
97 attrs = [attr for attr in attrs if not isinstance(attr, self.exclusiveclass)]
98 attrs.append(self)
99 return attrs
102 class sortbeforeattr(attr):
104 """an attribute which places itself previous to all attributes given
105 in the beforetheclasses argument to the constructor"""
107 def __init__(self, beforetheclasses):
108 self.beforetheclasses = tuple(beforetheclasses)
110 def merge(self, attrs):
111 first = True
112 result = []
113 for attr in attrs:
114 if first and isinstance(attr, self.beforetheclasses):
115 result.append(self)
116 first = False
117 result.append(attr)
118 if first:
119 result.append(self)
120 return result
123 class sortbeforeexclusiveattr(attr):
125 """an attribute which swallows all but the last of the same type (specified
126 by the exlusiveclass argument to the constructor) in an attribute list and
127 places itself previous to all attributes given in the beforetheclasses
128 argument to the constructor"""
130 def __init__(self, exclusiveclass, beforetheclasses):
131 self.exclusiveclass = exclusiveclass
132 self.beforetheclasses = tuple(beforetheclasses)
134 def merge(self, attrs):
135 first = 1
136 result = []
137 for attr in attrs:
138 if first and isinstance(attr, self.beforetheclasses):
139 result.append(self)
140 first = 0
141 if not isinstance(attr, self.exclusiveclass):
142 result.append(attr)
143 if first:
144 result.append(self)
145 return result
148 class clearclass(attr):
150 """a special attribute which allows to remove all predecessing attributes of
151 the same type in an attribute list"""
153 def __init__(self, clearclass):
154 self.clearclass = clearclass
156 def merge(self, attrs):
157 return [attr for attr in attrs if not isinstance(attr, self.clearclass)]
160 class _clear(attr):
162 """a special attribute which removes all predecessing attributes
163 in an attribute list"""
165 def merge(self, attrs):
166 return []
168 # we define the attribute "clear", an instance of "_clear",
169 # which can be used to remove all predecessing attributes
170 # in an attribute list
172 clear = _clear()
175 # changeable attrs
178 def selectattrs(attrs, index, total):
179 """performs select calls for all changeable attributes and
180 returns the resulting attribute list
181 - attrs should be a list containing attributes and changeable
182 attributes
183 - index should be an unsigned integer
184 - total should be a positive number
185 - valid sections fullfill 0<=index<total
186 - returns None, when attrs is None
187 - returns None, when a changeable attribute returns None"""
188 if attrs is None:
189 return None
190 result = []
191 for a in attrs:
192 if isinstance(a, changeattr):
193 select = a.select(index, total)
194 if select is None:
195 return None
196 result.append(select)
197 else:
198 result.append(a)
199 return result
202 def selectattr(attr, index, total):
203 """as select, but for a single attribute"""
204 if isinstance(attr, changeattr):
205 select = attr.select(index, total)
206 if select is None:
207 return None
208 return select
209 else:
210 return attr
213 class changeattr:
215 """changeattr is the base class of all changeable attributes"""
217 def select(self, index, total):
218 """returns an attribute for a given index out of a total number
219 if attributes to be provided
220 - index should be an unsigned integer
221 - total should be a positive number
222 - valid selections fullfill 0 <= index < total
223 - the select method may raise a ValueError, when the
224 changeable attribute does not allow for a requested
225 selection"""
227 raise RuntimeError("not implemented")
230 class changelist(changeattr):
232 """a changeable attribute over a list of attribute choises"""
234 def __init__(self, attrs, cyclic=1):
235 """initializes the instance
236 - attrs is a list of attributes to cycle
237 - If cyclic is set, we restart from the beginning after
238 the end of the list has been reached; otherwise
239 selecting beyond the end of the list returns None"""
240 self.attrs = attrs
241 self.cyclic = cyclic
243 def select(self, index, total):
244 if self.cyclic:
245 return self.attrs[index % len(self.attrs)]
246 elif index < len(self.attrs):
247 return self.attrs[index]
248 else:
249 return None
252 class multichangeattr(changeattr):
254 """a changeable attr, which selects a changeable attr from
255 a given dict (or list) of changeable attrs depending on the
256 value of total in the select call"""
258 def __init__(self, changeattrs):
259 self.changeattrs = changeattrs
261 def select(self, index, total):
262 return self.changeattrs[total].select(index, total)