Parcourir la source

Add comment for SetText().

Uli Kusterer il y a 12 ans
Parent
commit
85fff5e50a
1 fichiers modifiés avec 34 ajouts et 0 suppressions
  1. 34 0
      tinyxml2.h

+ 34 - 0
tinyxml2.h

@@ -1369,6 +1369,40 @@ public:
     */
     */
     const char* GetText() const;
     const char* GetText() const;
 
 
+    /** Convenience function for easy access to the text inside an element. Although easy
+    	and concise, SetText() is limited compared to creating an XMLText child
+    	and mutating it directly.
+
+    	If the first child of 'this' is a XMLText, SetText() sets its value to
+		the given string, otherwise it will create a first child that is an XMLText.
+
+    	This is a convenient method for setting the text of simple contained text:
+    	@verbatim
+    	<foo>This is text</foo>
+    		fooElement->SetText( "Hullaballoo!" );
+     	<foo>Hullaballoo!</foo>
+		@endverbatim
+
+    	Note that this function can be misleading. If the element foo was created from
+    	this XML:
+    	@verbatim
+    		<foo><b>This is text</b></foo>
+    	@endverbatim
+
+    	then it will not change "This is text", but rather prefix it with a text element:
+    	@verbatim
+    		<foo>Hullaballoo!<b>This is text</b></foo>
+    	@endverbatim
+		
+		For this XML:
+    	@verbatim
+    		<foo />
+    	@endverbatim
+    	SetText() will generate
+    	@verbatim
+    		<foo>Hullaballoo!</foo>
+    	@endverbatim
+    */
 	void	SetText( const char* inText );
 	void	SetText( const char* inText );
 
 
     /**
     /**