zynaddsubfx

ZynAddSubFX open source synthesizer
Log | Files | Refs | Submodules | LICENSE

commit 096a2a2db9bc7d7f9bb2bf8ee12136134708ef23
parent bd1d380fbf729f12391f7f154ea9270996906cc8
Author: fundamental <mark.d.mccurry@gmail.com>
Date:   Fri,  4 Sep 2009 18:45:57 -0400

Gave XMLwrapper doxygen comments

Diffstat:
Msrc/Misc/XMLwrapper.h | 253+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------
1 file changed, 195 insertions(+), 58 deletions(-)

diff --git a/src/Misc/XMLwrapper.h b/src/Misc/XMLwrapper.h @@ -1,9 +1,11 @@ /* ZynAddSubFX - a software synthesizer - XML.h - XML wrapper + XMLwrapper.h - XML wrapper Copyright (C) 2003-2005 Nasca Octavian Paul + Copyright (C) 2009-2009 Mark McCurry Author: Nasca Octavian Paul + Mark McCurry This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License @@ -34,143 +36,278 @@ //the maxim tree depth #define STACKSIZE 100 +/**Mxml wrapper*/ class XMLwrapper { public: + /** + * Constructor. + * Will Construct the object and fill in top level branch + * */ XMLwrapper(); - ~XMLwrapper(); - /********************************/ - /* SAVE to XML */ - /********************************/ + /**Destructor*/ + ~XMLwrapper(); - //returns 0 if ok or -1 if the file cannot be saved + /** + * Saves the XML to a file. + * @param filename the name of the destination file. + * @returns 0 if ok or -1 if the file cannot be saved. + */ int saveXMLfile(const std::string &filename); - //returns the new allocated string that contains the XML data (used for clipboard) - //the string is NULL terminated + /** + * Return XML tree as a string. + * Note: The string must be freed with free() to deallocate + * @returns a newly allocated NULL terminated string of the XML data. + */ char *getXMLdata(); - //add simple parameter (name and value) + /** + * Add simple parameter. + * @param name The name of the mXML node. + * @param val The string value of the mXml node + */ void addpar(const std::string &name,int val); + + /** + * Adds a realtype parameter. + * @param name The name of the mXML node. + * @param val The REALTYPE value of the node. + */ void addparreal(const std::string &name,REALTYPE val); - //add boolean parameter (name and boolean value) - //if the value is 0 => "yes", else "no" + /** + * Add boolean parameter. + * \todo Fix this reverse boolean logic. + * @param name The name of the mXML node. + * @param val The boolean value of the node (0->"yes";else->"no"). + */ void addparbool(const std::string &name,int val); - //add string parameter (name and string) + /** + * Add string parameter. + * @param name The name of the mXML node. + * @param val The string value of the node. + */ void addparstr(const std::string &name,const std::string &val); - //add a branch + /** + * Create a new branch. + * @param name Name of new branch + * @see void endbranch() + */ void beginbranch(const std::string &name); + /** + * Create a new branch. + * @param name Name of new branch + * @param id "id" value of branch + * @see void endbranch() + */ void beginbranch(const std::string &name, int id); - //this must be called after each branch (nodes that contains child nodes) + /**Closes new branches. + * This must be called to exit each branch created by beginbranch( ). + * @see void beginbranch(const std::string &name) + * @see void beginbranch(const std::string &name, int id) + */ void endbranch(); - /********************************/ - /* LOAD from XML */ - /********************************/ - - //returns 0 if ok or -1 if the file cannot be loaded + /** + * Loads file into XMLwrapper. + * @param filename file to be loaded + * @returns 0 if ok or -1 if the file cannot be loaded + */ int loadXMLfile(const std::string &filename); - //used by the clipboard + /** + * Loads string into XMLwrapper. + * @param xmldata NULL terminated string of XML data. + * @returns true if successful. + */ bool putXMLdata(const char *xmldata); - //enter into the branch - //returns 1 if is ok, or 0 otherwise + /** + * Enters the branch. + * @param name Name of branch. + * @returns 1 if is ok, or 0 otherwise. + */ int enterbranch(const std::string &name); - - //enter into the branch with id - //returns 1 if is ok, or 0 otherwise + /** + * Enter into the branch \c name with id \c id. + * @param name Name of branch. + * @param id Value of branch's "id". + * @returns 1 if is ok, or 0 otherwise. + */ int enterbranch(const std::string &name, int id); - //exits from a branch + /**Exits from a branch*/ void exitbranch(); - //get the the branch_id and limits it between the min and max - //if min==max==0, it will not limit it - //if there isn't any id, will return min - //this must be called only imediately after enterbranch() + /**Get the the branch_id and limits it between the min and max. + * if min==max==0, it will not limit it + * if there isn't any id, will return min + * this must be called only imediately after enterbranch() + */ int getbranchid(int min, int max); - //it returns the parameter and limits it between min and max - //if min==max==0, it will not limit it - //if no parameter will be here, the defaultpar will be returned + /** + * Returns the integer value stored in node name. + * It returns the integer value between the limits min and max. + * If min==max==0, then the value will not be limited. + * If there is no location named name, then defaultpar will be returned. + * @param name The parameter name. + * @param defaultpar The default value if the real value is not found. + * @param min The minimum return value. + * @param max The maximum return value. + */ int getpar(const std::string &name,int defaultpar,int min,int max); - //the same as getpar, but the limits are 0 and 127 + /** + * Returns the integer value stored in the node with range [0,127]. + * @param name The parameter name. + * @param defaultpar The default value if the real value is not found. + */ int getpar127(const std::string &name,int defaultpar); + /** + * Returns the boolean value stored in the node. + * @param name The parameter name. + * @param defaultpar The default value if the real value is not found. + */ int getparbool(const std::string &name,int defaultpar); + /** + * Get the string value stored in the node. + * @param name The parameter name. + * @param par Pointer to destination string + * @param maxstrlen Max string length for destination + */ void getparstr(const std::string &name,char *par,int maxstrlen); + + /** + * Returns the real value stored in the node. + * @param name The parameter name. + * @param defaultpar The default value if the real value is not found. + */ REALTYPE getparreal(const char *name,REALTYPE defaultpar); + + /** + * Returns the real value stored in the node. + * @param name The parameter name. + * @param defaultpar The default value if the real value is not found. + * @param min The minimum value + * @param max The maximum value + */ REALTYPE getparreal(const char *name,REALTYPE defaultpar,REALTYPE min,REALTYPE max); - bool minimal;//false if all parameters will be stored (used only for clipboard) + bool minimal;/**<false if all parameters will be stored (used only for clipboard)*/ struct { - bool PADsynth_used; - }information; + bool PADsynth_used;/**<if PADsynth is used*/ + }information;/**<Defines if PADsynth is used*/ - //opens a file and parse only the "information" data on it - //returns "true" if all went ok or "false" on errors + /** + * Opens a file and parses the "information" section data on it. + * @returns "true" if all went ok or "false" on errors. + */ bool checkfileinformation(const char *filename); private: + /** + * Save the file. + * @param filename File to save to + * @param compression Level of gzip compression + * @param xmldata String to be saved + */ int dosavefile(const char *filename,int compression,const char *xmldata); + + /**Loads the file. + * @param filename the name of the file + * @returns gunziped contents of file + */ char *doloadfile(const std::string &filename); - mxml_node_t *tree;//all xml data - mxml_node_t *root;//xml data used by zynaddsubfx - mxml_node_t *node;//current node - mxml_node_t *info;//this node is used to store the information about the data + mxml_node_t *tree;/**<all xml data*/ + mxml_node_t *root;/**<xml data used by zynaddsubfx*/ + mxml_node_t *node;/**<current node*/ + mxml_node_t *info;/**<Node used to store the information about the data*/ - //adds params like this: - // <name> - //returns the node + /** + * Adds params like this: + * <name>. + * @returns The node + */ mxml_node_t *addparams0(const char *name); - //adds params like this: - // <name par1="val1"> - //returns the node + /** + * Adds params like this: + * <name par1="val1">. + * @returns The node + */ mxml_node_t *addparams1(const char *name,const char *par1,const char *val1); - //adds params like this: - // <name par1="val1" par2="val2"> - //returns the node + /** + * Adds params like this: + * <name par1="val1" par2="val2">. + * @returns the node + */ mxml_node_t *addparams2(const char *name,const char *par1,const char *val1,const char *par2, const char *val2); + /** + * Convert integer to string + * @param x integer input + * @returns string output + */ char *int2str(int x); + + /** + * Convert integer to string + * @param x integer input + * @returns string output + */ char *real2str(REALTYPE x); + /** + * Convert string to int + * @param str string input + * @returns integer output + */ int str2int(const char *str); + + /** + * Convert string to realtype + * @param x integer input + * @returns string output + */ REALTYPE str2real(const char *str); + /**Temporary string for various uses*/ char tmpstr[TMPSTR_SIZE]; - //this is used to store the parents + /**this is used to store the parents. + * @todo Use the stack class provided by C++*/ mxml_node_t *parentstack[STACKSIZE]; - int stackpos; + int stackpos;/**<position in stack*/ void push(mxml_node_t *node); + + /**Pops top node off of parent stack*/ mxml_node_t *pop(); + /**Returns top node off of parent stack*/ mxml_node_t *peek(); - //theese are used to store the values struct { struct { - int major,minor; - }xml_version; - }values; + int major;/**<major version number.*/ + int minor;/**<minor version number.*/ + }xml_version;/**<Stores ZynAddSubFX versioning information*/ + }values;/**< Stores ZynAddSubFX versioning information*/ };