1 /**
2  * @file ListOfDrawables.h
3  * @brief Definition of the ListOfDrawables class.
4  * @author SBMLTeam
5  *
6  * <!--------------------------------------------------------------------------
7  * This file is part of libSBML. Please visit http://sbml.org for more
8  * information about SBML, and the latest version of libSBML.
9  *
10  * Copyright (C) 2020 jointly by the following organizations:
11  *     1. California Institute of Technology, Pasadena, CA, USA
12  *     2. University of Heidelberg, Heidelberg, Germany
13  *     3. University College London, London, UK
14  *
15  * Copyright (C) 2019 jointly by the following organizations:
16  *     1. California Institute of Technology, Pasadena, CA, USA
17  *     2. University of Heidelberg, Heidelberg, Germany
18  *
19  * Copyright (C) 2013-2018 jointly by the following organizations:
20  * 1. California Institute of Technology, Pasadena, CA, USA
21  * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK
22  * 3. University of Heidelberg, Heidelberg, Germany
23  *
24  * Copyright (C) 2009-2013 jointly by the following organizations:
25  * 1. California Institute of Technology, Pasadena, CA, USA
26  * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK
27  *
28  * Copyright (C) 2006-2008 by the California Institute of Technology,
29  * Pasadena, CA, USA
30  *
31  * Copyright (C) 2002-2005 jointly by the following organizations:
32  * 1. California Institute of Technology, Pasadena, CA, USA
33  * 2. Japan Science and Technology Agency, Japan
34  *
35  * This library is free software; you can redistribute it and/or modify it
36  * under the terms of the GNU Lesser General Public License as published by the
37  * Free Software Foundation. A copy of the license agreement is provided in the
38  * file named "LICENSE.txt" included with this software distribution and also
39  * available online as http://sbml.org/software/libsbml/license.html
40  * ------------------------------------------------------------------------ -->
41  *
42  * @class ListOfDrawables
43  * @sbmlbrief{render} A list of Transformation2D objects.
44  *
45  * The ListOfDrawables is a container for Transformation2D elements.  It is
46  * implemented in libSBML only, and does not appear in the "render"
47  * specification, where the RenderGroup object contains child
48  * Transformation2D objects directly.
49  *
50  * @copydetails doc_what_is_listof
51  *
52  * @htmlinclude not-sbml-warning.html
53  *
54  * @see Transformation2D
55  * @see RenderGroup
56  */
57 
58 
59 #ifndef ListOfDrawables_H__
60 #define ListOfDrawables_H__
61 
62 
63 #include <sbml/common/extern.h>
64 #include <sbml/common/sbmlfwd.h>
65 #include <sbml/packages/render/common/renderfwd.h>
66 
67 
68 #ifdef __cplusplus
69 
70 
71 #include <string>
72 
73 
74 #include <sbml/ListOf.h>
75 #include <sbml/packages/render/extension/RenderExtension.h>
76 #include <sbml/packages/render/sbml/Transformation2D.h>
77 
78 
79 LIBSBML_CPP_NAMESPACE_BEGIN
80 
81 
82 class Image;
83 class Ellipse;
84 class Rectangle;
85 class Polygon;
86 class RenderGroup;
87 class LineEnding;
88 class Text;
89 class RenderCurve;
90 
91 class LIBSBML_EXTERN ListOfDrawables : public ListOf
92 {
93 
94 public:
95 
96   /**
97    * Creates a new ListOfDrawables using the given SBML Level, Version and
98    * &ldquo;render&rdquo; package version.
99    *
100    * @param level an unsigned int, the SBML Level to assign to this
101    * ListOfDrawables.
102    *
103    * @param version an unsigned int, the SBML Version to assign to this
104    * ListOfDrawables.
105    *
106    * @param pkgVersion an unsigned int, the SBML Render Version to assign to
107    * this ListOfDrawables.
108    *
109    * @copydetails doc_note_setting_lv_pkg
110    */
111   ListOfDrawables(unsigned int level = RenderExtension::getDefaultLevel(),
112                   unsigned int version = RenderExtension::getDefaultVersion(),
113                   unsigned int pkgVersion =
114                     RenderExtension::getDefaultPackageVersion());
115 
116 
117   /**
118    * Creates a new ListOfDrawables using the given RenderPkgNamespaces object.
119    *
120    * @copydetails doc_what_are_sbml_package_namespaces
121    *
122    * @param renderns the RenderPkgNamespaces object.
123    *
124    * @copydetails doc_note_setting_lv_pkg
125    */
126   ListOfDrawables(RenderPkgNamespaces *renderns);
127 
128 
129   /**
130    * Copy constructor for ListOfDrawables.
131    *
132    * @param orig the ListOfDrawables instance to copy.
133    */
134   ListOfDrawables(const ListOfDrawables& orig);
135 
136 
137   /**
138    * Assignment operator for ListOfDrawables.
139    *
140    * @param rhs the ListOfDrawables object whose values are to be used as the
141    * basis of the assignment.
142    */
143   ListOfDrawables& operator=(const ListOfDrawables& rhs);
144 
145 
146   /**
147    * Creates and returns a deep copy of this ListOfDrawables object.
148    *
149    * @return a (deep) copy of this ListOfDrawables object.
150    */
151   virtual ListOfDrawables* clone() const;
152 
153 
154   /**
155    * Destructor for ListOfDrawables.
156    */
157   virtual ~ListOfDrawables();
158 
159 
160   /**
161    * Get a Transformation2D from the ListOfDrawables.
162    *
163    * @param n an unsigned int representing the index of the Transformation2D to
164    * retrieve.
165    *
166    * @return the nth Transformation2D in this ListOfDrawables.
167    * If the index @p n is invalid, @c NULL is returned.
168    *
169    * @copydetails doc_returned_unowned_pointer
170    *
171    * @see addTransformation2D(const Transformation2D* object)
172    * @see createCurve()
173    * @see createEllipse()
174    * @see createGroup()
175    * @see createImage()
176    * @see createLineEnding()
177    * @see createPolygon()
178    * @see createRectangle()
179    * @see createText()
180    * @see get(const std::string& sid)
181    * @see getNumTransformation2Ds()
182    * @see remove(const std::string& sid)
183    * @see remove(unsigned int n)
184    */
185   virtual Transformation2D* get(unsigned int n);
186 
187 
188   /**
189    * Get a Transformation2D from the ListOfDrawables.
190    *
191    * @param n an unsigned int representing the index of the Transformation2D to
192    * retrieve.
193    *
194    * @return the nth Transformation2D in this ListOfDrawables.
195    * If the index @p n is invalid, @c NULL is returned.
196    *
197    * @copydetails doc_returned_unowned_pointer
198    *
199    * @see addTransformation2D(const Transformation2D* object)
200    * @see createCurve()
201    * @see createEllipse()
202    * @see createGroup()
203    * @see createImage()
204    * @see createLineEnding()
205    * @see createPolygon()
206    * @see createRectangle()
207    * @see createText()
208    * @see get(const std::string& sid)
209    * @see getNumTransformation2Ds()
210    * @see remove(const std::string& sid)
211    * @see remove(unsigned int n)
212    */
213   virtual const Transformation2D* get(unsigned int n) const;
214 
215 
216   /**
217    * Get a Transformation2D from the ListOfDrawables based on its identifier.
218    *
219    * @param sid a string representing the identifier of the Transformation2D to
220    * retrieve.
221    *
222    * @return the Transformation2D in this ListOfDrawables with the given @p sid
223    * or @c NULL if no such Transformation2D exists.
224    *
225    * @copydetails doc_returned_unowned_pointer
226    *
227    * @see addTransformation2D(const Transformation2D* object)
228    * @see createCurve()
229    * @see createEllipse()
230    * @see createGroup()
231    * @see createImage()
232    * @see createLineEnding()
233    * @see createPolygon()
234    * @see createRectangle()
235    * @see createText()
236    * @see get(unsigned int n)
237    * @see getNumTransformation2Ds()
238    * @see remove(const std::string& sid)
239    * @see remove(unsigned int n)
240    */
241   virtual Transformation2D* get(const std::string& sid);
242 
243 
244   /**
245    * Get a Transformation2D from the ListOfDrawables based on its identifier.
246    *
247    * @param sid a string representing the identifier of the Transformation2D to
248    * retrieve.
249    *
250    * @return the Transformation2D in this ListOfDrawables with the given @p sid
251    * or @c NULL if no such Transformation2D exists.
252    *
253    * @copydetails doc_returned_unowned_pointer
254    *
255    * @see addTransformation2D(const Transformation2D* object)
256    * @see createCurve()
257    * @see createEllipse()
258    * @see createGroup()
259    * @see createImage()
260    * @see createLineEnding()
261    * @see createPolygon()
262    * @see createRectangle()
263    * @see createText()
264    * @see get(unsigned int n)
265    * @see getNumTransformation2Ds()
266    * @see remove(const std::string& sid)
267    * @see remove(unsigned int n)
268    */
269   virtual const Transformation2D* get(const std::string& sid) const;
270 
271 
272   /**
273    * Removes the nth Transformation2D from this ListOfDrawables and returns a
274    * pointer to it.
275    *
276    * @param n an unsigned int representing the index of the Transformation2D to
277    * remove.
278    *
279    * @return a pointer to the nth Transformation2D in this ListOfDrawables.
280    *
281    * @copydetails doc_warning_returns_owned_pointer
282    *
283    * @see addTransformation2D(const Transformation2D* object)
284    * @see createCurve()
285    * @see createEllipse()
286    * @see createGroup()
287    * @see createImage()
288    * @see createLineEnding()
289    * @see createPolygon()
290    * @see createRectangle()
291    * @see createText()
292    * @see get(const std::string& sid)
293    * @see get(unsigned int n)
294    * @see getNumTransformation2Ds()
295    * @see remove(const std::string& sid)
296    */
297   virtual Transformation2D* remove(unsigned int n);
298 
299 
300   /**
301    * Removes the Transformation2D from this ListOfDrawables based on its
302    * identifier and returns a pointer to it.
303    *
304    * @param sid a string representing the identifier of the Transformation2D to
305    * remove.
306    *
307    * @return the Transformation2D in this ListOfDrawables based on the
308    * identifier or NULL if no such Transformation2D exists.
309    *
310    * @copydetails doc_warning_returns_owned_pointer
311    *
312    * @see addTransformation2D(const Transformation2D* object)
313    * @see createCurve()
314    * @see createEllipse()
315    * @see createGroup()
316    * @see createImage()
317    * @see createLineEnding()
318    * @see createPolygon()
319    * @see createRectangle()
320    * @see createText()
321    * @see get(const std::string& sid)
322    * @see get(unsigned int n)
323    * @see getNumTransformation2Ds()
324    * @see remove(unsigned int n)
325    */
326   virtual Transformation2D* remove(const std::string& sid);
327 
328 
329   /**
330    * Adds a copy of the given Transformation2D to this ListOfDrawables.
331    *
332    * @param td the Transformation2D object to add.
333    *
334    * @copydetails doc_returns_success_code
335    * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t}
336    * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t}
337    * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t}
338    * @li @sbmlconstant{LIBSBML_LEVEL_MISMATCH, OperationReturnValues_t}
339    * @li @sbmlconstant{LIBSBML_VERSION_MISMATCH, OperationReturnValues_t}
340    * @li @sbmlconstant{LIBSBML_PKG_VERSION_MISMATCH, OperationReturnValues_t}
341    * @li @sbmlconstant{LIBSBML_DUPLICATE_OBJECT_ID, OperationReturnValues_t}
342    *
343    * @copydetails doc_note_object_is_copied
344    *
345    * @see createCurve()
346    * @see createEllipse()
347    * @see createGroup()
348    * @see createImage()
349    * @see createLineEnding()
350    * @see createPolygon()
351    * @see createRectangle()
352    * @see createText()
353    * @see get(const std::string& sid)
354    * @see get(unsigned int n)
355    * @see getNumTransformation2Ds()
356    * @see remove(const std::string& sid)
357    * @see remove(unsigned int n)
358    */
359   int addTransformation2D(const Transformation2D* td);
360 
361 
362   /**
363    * Get the number of Transformation2D objects in this ListOfDrawables.
364    *
365    * @return the number of Transformation2D objects in this ListOfDrawables.
366    *
367    *
368    * @see addTransformation2D(const Transformation2D* object)
369    * @see createCurve()
370    * @see createEllipse()
371    * @see createGroup()
372    * @see createImage()
373    * @see createLineEnding()
374    * @see createPolygon()
375    * @see createRectangle()
376    * @see createText()
377    * @see get(const std::string& sid)
378    * @see get(unsigned int n)
379    * @see remove(const std::string& sid)
380    * @see remove(unsigned int n)
381    */
382   unsigned int getNumTransformation2Ds() const;
383 
384 
385   /**
386    * Creates a new Image object, adds it to this ListOfDrawables object and
387    * returns the Image object created.
388    *
389    * @return a new Image object instance.
390    *
391    * @copydetails doc_returned_unowned_pointer
392    *
393    * @see addTransformation2D(const Transformation2D* object)
394    * @see createCurve()
395    * @see createEllipse()
396    * @see createGroup()
397    * @see createLineEnding()
398    * @see createPolygon()
399    * @see createRectangle()
400    * @see createText()
401    * @see get(const std::string& sid)
402    * @see get(unsigned int n)
403    * @see getNumTransformation2Ds()
404    * @see remove(const std::string& sid)
405    * @see remove(unsigned int n)
406    */
407   Image* createImage();
408 
409 
410   /**
411    * Creates a new Ellipse object, adds it to this ListOfDrawables object and
412    * returns the Ellipse object created.
413    *
414    * @return a new Ellipse object instance.
415    *
416    * @copydetails doc_returned_unowned_pointer
417    *
418    * @see addTransformation2D(const Transformation2D* object)
419    * @see createCurve()
420    * @see createGroup()
421    * @see createImage()
422    * @see createLineEnding()
423    * @see createPolygon()
424    * @see createRectangle()
425    * @see createText()
426    * @see get(const std::string& sid)
427    * @see get(unsigned int n)
428    * @see getNumTransformation2Ds()
429    * @see remove(const std::string& sid)
430    * @see remove(unsigned int n)
431    */
432   Ellipse* createEllipse();
433 
434 
435   /**
436    * Creates a new Rectangle object, adds it to this ListOfDrawables object and
437    * returns the Rectangle object created.
438    *
439    * @return a new Rectangle object instance.
440    *
441    * @copydetails doc_returned_unowned_pointer
442    *
443    * @see addTransformation2D(const Transformation2D* object)
444    * @see createCurve()
445    * @see createEllipse()
446    * @see createGroup()
447    * @see createImage()
448    * @see createLineEnding()
449    * @see createPolygon()
450    * @see createText()
451    * @see get(const std::string& sid)
452    * @see get(unsigned int n)
453    * @see getNumTransformation2Ds()
454    * @see remove(const std::string& sid)
455    * @see remove(unsigned int n)
456    */
457   Rectangle* createRectangle();
458 
459 
460   /**
461    * Creates a new Polygon object, adds it to this ListOfDrawables object and
462    * returns the Polygon object created.
463    *
464    * @return a new Polygon object instance.
465    *
466    * @copydetails doc_returned_unowned_pointer
467    *
468    * @see addTransformation2D(const Transformation2D* object)
469    * @see createCurve()
470    * @see createEllipse()
471    * @see createGroup()
472    * @see createImage()
473    * @see createLineEnding()
474    * @see createRectangle()
475    * @see createText()
476    * @see get(const std::string& sid)
477    * @see get(unsigned int n)
478    * @see getNumTransformation2Ds()
479    * @see remove(const std::string& sid)
480    * @see remove(unsigned int n)
481    */
482   Polygon* createPolygon();
483 
484 
485   /**
486    * Creates a new RenderGroup object, adds it to this ListOfDrawables object
487    * and returns the RenderGroup object created.
488    *
489    * @return a new RenderGroup object instance.
490    *
491    * @copydetails doc_returned_unowned_pointer
492    *
493    * @see addTransformation2D(const Transformation2D* object)
494    * @see createCurve()
495    * @see createEllipse()
496    * @see createImage()
497    * @see createLineEnding()
498    * @see createPolygon()
499    * @see createRectangle()
500    * @see createText()
501    * @see get(const std::string& sid)
502    * @see get(unsigned int n)
503    * @see getNumTransformation2Ds()
504    * @see remove(const std::string& sid)
505    * @see remove(unsigned int n)
506    */
507   RenderGroup* createGroup();
508 
509 
510   /**
511    * Creates a new LineEnding object, adds it to this ListOfDrawables object
512    * and returns the LineEnding object created.
513    *
514    * @return a new LineEnding object instance.
515    *
516    * @copydetails doc_returned_unowned_pointer
517    *
518    * @see addTransformation2D(const Transformation2D* object)
519    * @see createCurve()
520    * @see createEllipse()
521    * @see createGroup()
522    * @see createImage()
523    * @see createPolygon()
524    * @see createRectangle()
525    * @see createText()
526    * @see get(const std::string& sid)
527    * @see get(unsigned int n)
528    * @see getNumTransformation2Ds()
529    * @see remove(const std::string& sid)
530    * @see remove(unsigned int n)
531    */
532   LineEnding* createLineEnding();
533 
534 
535   /**
536    * Creates a new Text object, adds it to this ListOfDrawables object and
537    * returns the Text object created.
538    *
539    * @return a new Text object instance.
540    *
541    * @copydetails doc_returned_unowned_pointer
542    *
543    * @see addTransformation2D(const Transformation2D* object)
544    * @see createCurve()
545    * @see createEllipse()
546    * @see createGroup()
547    * @see createImage()
548    * @see createLineEnding()
549    * @see createPolygon()
550    * @see createRectangle()
551    * @see get(const std::string& sid)
552    * @see get(unsigned int n)
553    * @see getNumTransformation2Ds()
554    * @see remove(const std::string& sid)
555    * @see remove(unsigned int n)
556    */
557   Text* createText();
558 
559 
560   /**
561    * Creates a new RenderCurve object, adds it to this ListOfDrawables object
562    * and returns the RenderCurve object created.
563    *
564    * @return a new RenderCurve object instance.
565    *
566    * @copydetails doc_returned_unowned_pointer
567    *
568    * @see addTransformation2D(const Transformation2D* object)
569    * @see createEllipse()
570    * @see createGroup()
571    * @see createImage()
572    * @see createLineEnding()
573    * @see createPolygon()
574    * @see createRectangle()
575    * @see createText()
576    * @see get(const std::string& sid)
577    * @see get(unsigned int n)
578    * @see getNumTransformation2Ds()
579    * @see remove(const std::string& sid)
580    * @see remove(unsigned int n)
581    */
582   RenderCurve* createCurve();
583 
584 
585   /**
586    * Returns the XML element name of this ListOfDrawables object.
587    *
588    * For ListOfDrawables, the XML element name is always @c "listOfDrawables".
589    *
590    * @return the name of this element, i.e. @c "listOfDrawables".
591    */
592   virtual const std::string& getElementName() const;
593 
594 
595   /**
596    * Returns the libSBML type code for this ListOfDrawables object.
597    *
598    * @copydetails doc_what_are_typecodes
599    *
600    * @return the SBML type code for this object:
601    * @sbmlconstant{SBML_LIST_OF, SBMLTypeCode_t}.
602    *
603    * @copydetails doc_warning_typecodes_not_unique
604    */
605   virtual int getTypeCode() const;
606 
607 
608   /**
609    * Returns the libSBML type code for the SBML objects contained in this
610    * ListOfDrawables object.
611    *
612    * @copydetails doc_what_are_typecodes
613    *
614    * @return the SBML typecode for the objects contained in this
615    * ListOfDrawables:
616    * @sbmlconstant{SBML_RENDER_TRANSFORMATION2D, SBMLRenderTypeCode_t}.
617    *
618    * @copydetails doc_warning_typecodes_not_unique
619    *
620    * @see getElementName()
621    * @see getPackageName()
622    */
623   virtual int getItemTypeCode() const;
624 
625 
626 
627 
628   #ifndef SWIG
629 
630 
631 
632 
633   #endif /* !SWIG */
634 
635 
636 protected:
637 
638 
639   /** @cond doxygenLibsbmlInternal */
640 
641   /**
642    * Creates a new Transformation2D in this ListOfDrawables
643    */
644   virtual SBase* createObject(XMLInputStream& stream);
645 
646   /** @endcond */
647 
648 
649   friend class RenderGroup;
650 
651   /** @cond doxygenLibsbmlInternal */
652 
653   /**
654    * Writes the namespace for the Render package
655    */
656   virtual void writeXMLNS(XMLOutputStream& stream) const;
657 
658   /** @endcond */
659 
660 
661 
662   /** @cond doxygenLibsbmlInternal */
663 
664   /**
665    * checks concrete types
666    */
667   virtual bool isValidTypeForList(SBase* item);
668 
669   /** @endcond */
670 
671 
672 };
673 
674 
675 
676 LIBSBML_CPP_NAMESPACE_END
677 
678 
679 
680 
681 #endif /* __cplusplus */
682 
683 
684 
685 
686 #ifndef SWIG
687 
688 
689 
690 
691 LIBSBML_CPP_NAMESPACE_BEGIN
692 
693 
694 
695 
696 BEGIN_C_DECLS
697 
698 
699 /**
700  * Get a Transformation2D_t from the ListOf_t.
701  *
702  * @param lo the ListOf_t structure to search.
703  *
704  * @param n an unsigned int representing the index of the Transformation2D_t to
705  * retrieve.
706  *
707  * @return the nth Transformation2D_t in this ListOf_t.
708  * If the index @p n is invalid, @c NULL is returned.
709  *
710  * @copydetails doc_returned_unowned_pointer
711  *
712  * @memberof ListOfDrawables_t
713  */
714 LIBSBML_EXTERN
715 Transformation2D_t*
716 ListOfDrawables_getTransformation2D(ListOf_t* lo, unsigned int n);
717 
718 
719 /**
720  * Get a Transformation2D_t from the ListOf_t based on its identifier.
721  *
722  * @param lo the ListOf_t structure to search.
723  *
724  * @param sid a string representing the identifier of the Transformation2D_t to
725  * retrieve.
726  *
727  * @return the Transformation2D_t in this ListOf_t with the given @p sid or
728  * @c NULL if no such Transformation2D_t exists.
729  *
730  * @copydetails doc_returned_unowned_pointer
731  *
732  * @memberof ListOfDrawables_t
733  */
734 LIBSBML_EXTERN
735 Transformation2D_t*
736 ListOfDrawables_getById(ListOf_t* lo, const char *sid);
737 
738 
739 /**
740  * Removes the nth Transformation2D_t from this ListOf_t and returns a pointer
741  * to it.
742  *
743  * @param lo the ListOf_t structure to search.
744  *
745  * @param n an unsigned int representing the index of the Transformation2D_t to
746  * remove.
747  *
748  * @return a pointer to the nth Transformation2D_t in this ListOf_t.
749  *
750  * @copydetails doc_warning_returns_owned_pointer
751  *
752  * @memberof ListOfDrawables_t
753  */
754 LIBSBML_EXTERN
755 Transformation2D_t*
756 ListOfDrawables_remove(ListOf_t* lo, unsigned int n);
757 
758 
759 /**
760  * Removes the Transformation2D_t from this ListOf_t based on its identifier
761  * and returns a pointer to it.
762  *
763  * @param lo the ListOf_t structure to search.
764  *
765  * @param sid a string representing the identifier of the Transformation2D_t to
766  * remove.
767  *
768  * @return the Transformation2D_t in this ListOf_t based on the identifier or
769  * NULL if no such Transformation2D_t exists.
770  *
771  * @copydetails doc_warning_returns_owned_pointer
772  *
773  * @memberof ListOfDrawables_t
774  */
775 LIBSBML_EXTERN
776 Transformation2D_t*
777 ListOfDrawables_removeById(ListOf_t* lo, const char* sid);
778 
779 
780 
781 
782 END_C_DECLS
783 
784 
785 
786 
787 LIBSBML_CPP_NAMESPACE_END
788 
789 
790 
791 
792 #endif /* !SWIG */
793 
794 
795 
796 
797 #endif /* !ListOfDrawables_H__ */
798 
799 
800