Xorn
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Pages
storage.py
Go to the documentation of this file.
1 # Copyright (C) 2013-2016 Roland Lutz
2 #
3 # This program is free software; you can redistribute it and/or modify
4 # it under the terms of the GNU General Public License as published by
5 # the Free Software Foundation; either version 2 of the License, or
6 # (at your option) any later version.
7 #
8 # This program is distributed in the hope that it will be useful,
9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 # GNU General Public License for more details.
12 #
13 # You should have received a copy of the GNU General Public License
14 # along with this program; if not, write to the Free Software Foundation,
15 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 
17 ## \file storage.py
18 ## Placeholder file for xorn.storage documentation.
19 #
20 # This file DOES NOT contain the actual source code of the
21 # xorn.storage module. It contains documented stubs of the code from
22 # which the Doxygen documentation is generated. For the actual
23 # definition of the module, see the Python extension in \c src/cpython/.
24 
25 ## \namespace xorn.storage
26 ## Xorn storage backend.
27 #
28 # Python extension providing access to the storage library.
29 #
30 # \sa \ref storage
31 # \sa xornstorage.h
32 
33 ## A particular state of the contents of a file.
34 
35 class Revision:
36  ## Create a new revision, either from scratch or by copying an
37  ## existing one.
38  #
39  # \param rev %Revision to copy, or \c None.
40  #
41  # There is a slight difference between creating two empty
42  # revisions and copying an empty one: only in the second case,
43  # objects of one revision will be valid in the other.
44  #
45  # \throw MemoryError if there is not enough memory
46 
47  def __init__(self, rev = None):
48  ## Whether the revision is transient.
49  #
50  # Reading and writing this is equivalent to calling \ref
51  # is_transient and \ref finalize. Cannot be set to \c True.
52 
53  self.transient = True
54 
55  ## Return whether a revision can be changed.
56  #
57  # When a revision is created, it is initially \a transient,
58  # i.e. changeable. This can be changed by calling \ref finalize.
59  # After that, it can't be changed directly any more---you will
60  # have to create a transient copy if you want to change it again.
61 
62  def is_transient(self):
63  pass
64 
65  ## Prevent further changes to a revision.
66  #
67  # When a revision is created, it is initially \a transient,
68  # i.e. changeable. However, it is typically not desired for a
69  # revision to change once it is in its desired state. Using this
70  # function, you can prevent further changes to the revision. It
71  # will still be possible to create a copy of the revision and
72  # change that.
73  #
74  # \return \c None
75 
76  def finalize(self):
77  pass
78 
79  ## Return a list of all objects in a revision.
80  #
81  # The objects are returned in their actual order. Attached
82  # objects are listed after the object they are attached to.
83  #
84  # \throw MemoryError if there is not enough memory
85  #
86  # Example:
87  # \snippet functions.py get objects
88 
89  def get_objects(self):
90  pass
91 
92  ## Return whether an object exists in a revision.
93 
94  def object_exists(self, ob):
95  pass
96 
97  ## Get the data of an object in a revision.
98  #
99  # Changing the returned data will not have an effect on the
100  # object; use \ref set_object_data to change the object.
101  #
102  # \return Returns an instance of the appropriate data class.
103  #
104  # \throw KeyError if \a ob doesn't exist in the revision
105  # \throw ValueError if the object type is not supported
106  # (should not happen)
107  # \throw MemoryError if there is not enough memory
108  #
109  # Example:
110  # \snippet functions.py get/set object data
111 
112  def get_object_data(self, ob):
113  pass
114 
115  ## Get the location of an object in the object structure.
116  #
117  # \return Returns a tuple <tt>(attached_to, pos)</tt> where \c
118  # attached_to is the object to which \a ob is attached and \c pos
119  # is the index of \a ob relative to its sibling objects.
120  #
121  # \throw KeyError if \a ob doesn't exist in the revision
122 
123  def get_object_location(self, ob):
124  pass
125 
126  ## Add a new object to a transient revision.
127  #
128  # The object is appended to the end of the object list.
129  #
130  # \a data must be an instance of one of the object data types
131  # (Arc, Box, Circle, Component, Line, Net, Path, Picture, or Text).
132  #
133  # \return Returns the new object.
134  #
135  # \throw ValueError if the revision isn't transient
136  # \throw TypeError if \a data doesn't have a valid type
137  # \throw MemoryError if there is not enough memory
138  #
139  # Example:
140  # \snippet functions.py add object
141 
142  def add_object(self, data):
143  pass
144 
145  ## Set the data of an object in a transient revision.
146  #
147  # If the object does not exist in the revision, it is created and
148  # appended to the end of the object list.
149  #
150  # \param ob An object which has previously been returned by a Xorn
151  # function for either this revision, one of its
152  # ancestors, or a revision which has a common ancestor
153  # with it.
154  #
155  # \param data An instance of one of the object data types (Arc,
156  # Box, Circle, Component, Line, Net, Path, Picture, or
157  # Text). The type may be different from the previous
158  # type of the object but must be Net or Component if
159  # there are objects attached to \a ob, and must be
160  # Text if \a ob itself is attached to an object.
161  #
162  # \return \c None
163  #
164  # \throw ValueError if the revision isn't transient
165  # \throw TypeError if \a data doesn't have a valid type
166  # \throw ValueError if \a ob is attached to an object but the new
167  # object type wouldn't permit attaching the object
168  # \throw ValueError if there are objects attached to \a ob but
169  # the new object type wouldn't permit attaching
170  # objects
171  # \throw MemoryError if there is not enough memory
172  #
173  # Example:
174  # \snippet functions.py get/set object data
175 
176  def set_object_data(self, ob, data):
177  pass
178 
179  ## Change the location of an object in the object structure of a
180  ## transient revision.
181  #
182  # This function performs two distinct operations:
183  #
184  # 1. Change the order in which an object is drawn and written to
185  # files as compared to its sibling objects.
186  #
187  # 2. Attach a schematic text object to a schematic net or component
188  # object. As far as this library is concerned, this will cause
189  # the text to be copied and deleted along with the net or component.
190  #
191  # If \a attach_to is \c None, the object becomes un-attached. If \a
192  # ob and \a insert_before are identical, the revision is left unchanged.
193  #
194  # \param ob The object which should be reordered
195  # and/or attached (must be Text if \a
196  # attach_to is not \c None)
197  # \param attach_to The object to which \a ob should be attached
198  # (must be Net or Component, or \c None)
199  # \param insert_before An object already attached to \a attach_to
200  # before which \a ob should be inserted, or
201  # \c None to append it at the end.
202  #
203  # \return \c None
204  #
205  # \throw ValueError if the revision isn't transient
206  # \throw KeyError if \a ob or (if not \c None) \a attach_to or
207  # \a insert_before don't exist in the revision
208  # \throw ValueError if \a attach_to is not \c None and
209  # - \a ob is not a schematic text or
210  # - \a attach_to is not a schematic net or
211  # schematic component
212  # \throw ValueError if \a insert_before is not \c None and not
213  # attached to \a attach_to
214  # \throw MemoryError if there is not enough memory
215  #
216  # Example:
217  # \snippet functions.py add attribute
218 
219  def relocate_object(self, ob, attach_to, insert_before):
220  pass
221 
222  ## Copy an object to a transient revision.
223  #
224  # Any objects attached to \a ob are copied as well, their copies
225  # being attached to the copy of \a ob, which is appended to the
226  # end of the object list.
227  #
228  # \param self Destination revision (must be transient)
229  # \param rev Source revision (does not need to be transient)
230  # \param ob %Object in the source revision which should be copied
231  #
232  # \return Returns the copy of \a ob.
233  #
234  # \throw ValueError if \a self isn't transient
235  # \throw KeyError if \a ob doesn't exist in \a rev
236  # \throw MemoryError if there is not enough memory
237 
238  def copy_object(self, rev, ob):
239  pass
240 
241  ## Copy some objects to a transient revision.
242  #
243  # Any objects attached to the objects are copied as well and
244  # attached to the corresponding new object. The copied objects
245  # are appended to the end of the object list in an unspecified
246  # order.
247  #
248  # \param self Destination revision (must be transient)
249  # \param rev Source revision (does not need to be transient)
250  # \param sel Objects in the source revision which should be copied
251  #
252  # \return Returns a selection containing the copied objects,
253  # excluding attached objects.
254  #
255  # \throw ValueError if \a self isn't transient
256  # \throw MemoryError if there is not enough memory
257 
258  def copy_objects(self, rev, sel):
259  pass
260 
261  ## Delete an object from a transient revision.
262  #
263  # Any objects attached to \a ob are deleted as well.
264  #
265  # The deleted object(s) stay valid and can later be re-added using
266  # \ref set_object_data.
267  #
268  # \return \c None
269  #
270  # \throw ValueError if the revision isn't transient
271  # \throw KeyError if \a ob doesn't exist in the revision
272 
273  def delete_object(self, ob):
274  pass
275 
276  ## Delete some objects from a transient revision.
277  #
278  # Any objects attached to a deleted object are deleted as well.
279  #
280  # The deleted objects stay valid and can later be re-added using
281  # \ref set_object_data.
282  #
283  # Objects that don't exist in the revision are ignored.
284  #
285  # \return \c None
286  #
287  # \throw ValueError if the revision isn't transient
288 
289  def delete_objects(self, sel):
290  pass
291 
292 ## The identity of an object across revisions.
293 #
294 # A value of this type is used as a key to look up and change the
295 # state of an object in a revision. It is created by
296 # Revision.add_object, Revision.copy_object, or (indirectly)
297 # Revision.copy_objects or returned by one of the other functions of
298 # this module.
299 #
300 # This type can't be directly instantiated.
301 
302 class Object:
303  ## x.__cmp__(y) <==> cmp(x,y)
304  def __cmp__(...):
305  pass
306 
307  ## x.__hash__() <==> hash(x)
308  def __hash__(...):
309  pass
310 
311 ## The identity of a set of objects across revisions.
312 #
313 # A value of this type is used as a set of keys for mass object
314 # inspection or manipulation and does not designate a specific order
315 # of the objects. It is created using one of the \c
316 # select_<em>something</em> class of functions.
317 #
318 # This type can't be directly instantiated.
319 
320 class Selection:
321  pass
322 
323 ## Return a list of objects in a revision which are attached to a
324 ## certain object.
325 #
326 # If \a ob is \c None, return all objects in the revision which are
327 # *not* attached. The objects are returned in their actual order.
328 # Objects attached to the returned objects are not returned.
329 #
330 # \throw KeyError if \a ob is not \c None and does not exist in \a rev
331 # \throw MemoryError if there is not enough memory
332 
334  pass
335 
336 ## Return a list of objects which are in a revision as well as in a
337 ## selection.
338 #
339 # The objects are not necessarily returned in a meaningful order.
340 #
341 # \throw MemoryError if there is not enough memory
342 
343 def get_selected_objects(rev, sel):
344  pass
345 
346 ## Return a list of objects which are in one revision but not in
347 ## another.
348 #
349 # Returns objects in \a to which are not in \a from. They are not
350 # necessarily returned in a meaningful order.
351 #
352 # \throw MemoryError if there is not enough memory
353 
354 def get_added_objects(from, to):
355  pass
356 
357 ## Return a list of objects which are in one revision but not in
358 ## another.
359 #
360 # Returns objects in \a from which are not in \a to. They are not
361 # necessarily returned in a meaningful order.
362 #
363 # \throw MemoryError if there is not enough memory
364 
365 def get_removed_objects(from, to):
366  pass
367 
368 ## Return a list of objects which exist in two revisions but have
369 ## different type or data.
370 #
371 # The objects are not necessarily returned in a meaningful order.
372 #
373 # \throw MemoryError if there is not enough memory
374 
375 def get_modified_objects(from, to):
376  pass
377 
378 ## Return an empty selection.
379 #
380 # \throw MemoryError if there is not enough memory
381 
383  pass
384 
385 ## Return a selection containing a single object.
386 #
387 # \throw MemoryError if there is not enough memory
388 
390  pass
391 
392 ## Return a selection containing all objects in a revision attached to
393 ## a given object.
394 #
395 # The object may be \c None, in which case the selection contains all
396 # objects which are *not* attached.
397 #
398 # \throw KeyError if \a ob is not \c None and does not exist in \a rev
399 # \throw MemoryError if there is not enough memory
400 
401 def select_attached_to(rev, ob):
402  pass
403 
404 ## Return a selection containing all objects in a revision.
405 #
406 # \throw MemoryError if there is not enough memory
407 
408 def select_all(rev):
409  pass
410 
411 ## Return a selection containing all objects in a revision except
412 ## those in a given selection.
413 #
414 # \throw MemoryError if there is not enough memory
415 
416 def select_all_except(rev, sel):
417  pass
418 
419 ## Return a selection which contains all the objects in an existing
420 ## selection plus a given object.
421 #
422 # \throw MemoryError if there is not enough memory
423 
424 def select_including(sel, ob):
425  pass
426 
427 ## Return a selection which contains all the objects in an existing
428 ## selection minus a given object.
429 #
430 # \throw MemoryError if there is not enough memory
431 
432 def select_excluding(sel, ob):
433  pass
434 
435 ## Return a selection containing the objects in either given
436 ## selection.
437 #
438 # \throw MemoryError if there is not enough memory
439 
440 def select_union(sel0, sel1):
441  pass
442 
443 ## Return a selection containing the objects in both given selections.
444 #
445 # \throw MemoryError if there is not enough memory
446 
447 def select_intersection(sel0, sel1):
448  pass
449 
450 ## Return a selection containing the objects contained in one given
451 ## selection, but not the other.
452 #
453 # \throw MemoryError if there is not enough memory
454 
455 def select_difference(sel0, sel1):
456  pass
457 
458 ## Return whether a selection is empty in a given revision.
459 
460 def selection_is_empty(rev, sel):
461  pass
462 
463 ## Return whether an object exists in a revision and is selected in a
464 ## selection.
465 
466 def object_is_selected(rev, sel, ob):
467  pass
468 
469 ## Schematic line style.
470 
471 class LineAttr:
472  def __init__(self):
473  self.width = 0.
474  self.cap_style = 0
475  self.dash_style = 0
476  self.dash_length = 0.
477  self.dash_space = 0.
478 
479 ## Schematic fill style.
480 
481 class FillAttr:
482  def __init__(self):
483  self.type = 0
484  self.width = 0.
485  self.angle0 = 0
486  self.pitch0 = 0.
487  self.angle1 = 0
488  self.pitch1 = 0.
489 
490 ## Schematic arc.
491 
492 class Arc:
493  def __init__(self):
494  self.x = 0.
495  self.y = 0.
496  self.radius = 0.
497  self.startangle = 0
498  self.sweepangle = 0
499  self.color = 0
500  self.line = LineAttr()
501 
502 ## Schematic box.
503 
504 class Box:
505  def __init__(self):
506  self.x = 0.
507  self.y = 0.
508  self.width = 0.
509  self.height = 0.
510  self.color = 0
511  self.line = LineAttr()
512  self.fill = FillAttr()
513 
514 ## Schematic circle.
515 
516 class Circle:
517  def __init__(self):
518  self.x = 0.
519  self.y = 0.
520  self.radius = 0.
521  self.color = 0
522  self.line = LineAttr()
523  self.fill = FillAttr()
524 
525 ## Schematic component.
526 
527 class Component:
528  def __init__(self):
529  self.x = 0.
530  self.y = 0.
531  self.selectable = False
532  self.angle = 0
533  self.mirror = False
534  self.symbol = None
535 
536 ## Schematic line.
537 
538 class Line:
539  def __init__(self):
540  self.x = 0.
541  self.y = 0.
542  self.width = 0.
543  self.height = 0.
544  self.color = 0
545  self.line = LineAttr()
546 
547 ## Schematic net segment, bus segment, or pin.
548 
549 class Net:
550  def __init__(self):
551  self.x = 0.
552  self.y = 0.
553  self.width = 0.
554  self.height = 0.
555  self.color = 0
556  self.is_bus = False
557  self.is_pin = False
558  self.is_inverted = False
559 
560 ## Schematic path.
561 
562 class Path:
563  def __init__(self):
564  self.pathdata = ''
565  self.color = 0
566  self.line = LineAttr()
567  self.fill = FillAttr()
568 
569 ## Schematic picture.
570 
571 class Picture:
572  def __init__(self):
573  self.x = 0.
574  self.y = 0.
575  self.width = 0.
576  self.height = 0.
577  self.angle = 0
578  self.mirror = False
579  self.pixmap = None
580 
581 ## Schematic text or attribute.
582 
583 class Text:
584  def __init__(self):
585  self.x = 0.
586  self.y = 0.
587  self.color = 0
588  self.text_size = 0
589  self.visibility = False
591  self.angle = 0
592  self.alignment = 0
593  self.text = ''
def add_object
Add a new object to a transient revision.
Definition: storage.py:142
def select_union
Return a selection containing the objects in either given selection.
Definition: storage.py:440
Schematic net segment, bus segment, or pin.
Definition: storage.py:549
def select_attached_to
Return a selection containing all objects in a revision attached to a given object.
Definition: storage.py:401
Schematic arc.
Definition: storage.py:492
def object_is_selected
Return whether an object exists in a revision and is selected in a selection.
Definition: storage.py:466
def select_all
Return a selection containing all objects in a revision.
Definition: storage.py:408
def copy_objects
Copy some objects to a transient revision.
Definition: storage.py:258
def get_added_objects
Return a list of objects which are in one revision but not in another.
Definition: storage.py:354
def __init__
Create a new revision, either from scratch or by copying an existing one.
Definition: storage.py:47
def get_removed_objects
Return a list of objects which are in one revision but not in another.
Definition: storage.py:365
def set_object_data
Set the data of an object in a transient revision.
Definition: storage.py:176
def object_exists
Return whether an object exists in a revision.
Definition: storage.py:94
def relocate_object
Change the location of an object in the object structure of a transient revision. ...
Definition: storage.py:219
Schematic picture.
Definition: storage.py:571
def select_intersection
Return a selection containing the objects in both given selections.
Definition: storage.py:447
def select_object
Return a selection containing a single object.
Definition: storage.py:389
transient
Whether the revision is transient.
Definition: storage.py:53
def select_none
Return an empty selection.
Definition: storage.py:382
def delete_object
Delete an object from a transient revision.
Definition: storage.py:273
Schematic path.
Definition: storage.py:562
def finalize
Prevent further changes to a revision.
Definition: storage.py:76
def select_difference
Return a selection containing the objects contained in one given selection, but not the other...
Definition: storage.py:455
def delete_objects
Delete some objects from a transient revision.
Definition: storage.py:289
Schematic box.
Definition: storage.py:504
Schematic component.
Definition: storage.py:527
Schematic circle.
Definition: storage.py:516
Schematic fill style.
Definition: storage.py:481
The identity of a set of objects across revisions.
Definition: storage.py:320
def __hash__
x.__hash__() <==> hash(x)
Definition: storage.py:308
def copy_object
Copy an object to a transient revision.
Definition: storage.py:238
Schematic line style.
Definition: storage.py:471
Schematic text or attribute.
Definition: storage.py:583
def selection_is_empty
Return whether a selection is empty in a given revision.
Definition: storage.py:460
def get_objects_attached_to
Return a list of objects in a revision which are attached to a certain object.
Definition: storage.py:333
A particular state of the contents of a file.
Definition: storage.py:35
The identity of an object across revisions.
Definition: storage.py:302
def select_excluding
Return a selection which contains all the objects in an existing selection minus a given object...
Definition: storage.py:432
def get_modified_objects
Return a list of objects which exist in two revisions but have different type or data.
Definition: storage.py:375
def select_all_except
Return a selection containing all objects in a revision except those in a given selection.
Definition: storage.py:416
def get_objects
Return a list of all objects in a revision.
Definition: storage.py:89
def __cmp__
x.__cmp__(y) <==> cmp(x,y)
Definition: storage.py:304
def select_including
Return a selection which contains all the objects in an existing selection plus a given object...
Definition: storage.py:424
def get_object_data
Get the data of an object in a revision.
Definition: storage.py:112
def get_object_location
Get the location of an object in the object structure.
Definition: storage.py:123
def is_transient
Return whether a revision can be changed.
Definition: storage.py:62
Schematic line.
Definition: storage.py:538
def get_selected_objects
Return a list of objects which are in a revision as well as in a selection.
Definition: storage.py:343