Index: doxygen/src_plugins/propedit/propedit.dox =================================================================== --- doxygen/src_plugins/propedit/propedit.dox (revision 7380) +++ doxygen/src_plugins/propedit/propedit.dox (revision 7381) @@ -1,22 +1,31 @@ -/** \file propedit.c - GUI / Actions ? - */ +/** \file propedit.c + \brief GUI / Actions related to Property Editor. -/** \fn int propedit_action(int argc, const char **argv, pcb_coord_t x, pcb_coord_t y); - Activates a portion of the GUI (the Property Editor) ... FIXME. develop, explain. + \fn int propedit_action(int argc, const char **argv, pcb_coord_t x, pcb_coord_t y); + Runs the Property Editor dialog after populating it with properties of selected objects. - Calls \ref pcb_propsel_map_core + Calls \ref pcb_propsel_map_core. + \remark Parameters are not used. They are there only to fulfill the function prototype. \return 0 if OK, 1 if there's no GUI or the active GUI can't edit properties. - */ -/** \fn int propset_action (int argc, const char **argv, pcb_coord_t x, pcb_coord_t y); - Calls \ref pcb_propsel_set - \return ? - */ + \fn int propset_action (int argc, const char **argv, pcb_coord_t x, pcb_coord_t y); + Sets _value_ for a named _prop_erty of objects selected set. -/** \fn pcb_uninit_t hid_propedit_init (void); - Calls PCB_REGISTER_ACTIONS(propedit_action_list, propedit_cookie) + Calls \ref pcb_propsel_set (argv[0], argv[1]); + \todo the \c printf statements should be issued only in DEBUG mode ? + + \param argc The number of arguments in \p argv. Should be at least 2 ? \todo CHECK + \param x, y Unused. + \return 0 + + + \fn pcb_uninit_t hid_propedit_init (void); + Calls PCB_REGISTER_ACTIONS(propedit_action_list, propedit_cookie) + \todo I(Alain) find the macro PCB_REGISTER_ACTIONS misleading + as it appears line 82, is redefined, and called again line 92 ! :( + + \return The function to be called when the action ends. See \ref pcb_hid_remove_actions_by_cookie */ Index: doxygen/src_plugins/propedit/props.dox =================================================================== --- doxygen/src_plugins/propedit/props.dox (revision 7380) +++ doxygen/src_plugins/propedit/props.dox (revision 7381) @@ -1,38 +1,3 @@ -/** \file props.h - Header file for \ref props.c - - \enum pcb_prop_type_t - A property type list, including string, integer, etc... - \var PCB_PROPT_invalid - How is this triggered ? - \var PCB_PROPT_max - Sentinel value - - - \union pcb_propval_t - Can hold the property value. - - - \typedef htsp_t - A string ? FIXME ? - - Macro generated typedef ... ! See : src_3rd/liblihata/genht/htsp.h - \todo how to document that complicated thing ? - - - \struct pcb_props_t - A single property, as a combination of property type and property values. - - - \var pcb_props_t::core - 1 if it is a core property... What defines a "core property" ? - - - \typedef pe_ctx_t - for internal use. - */ - - /** \file props.c \brief Builds and maintains a collection of values for each named property. @@ -39,9 +4,9 @@ A property list (props) is a string-keyed hash table of type \ref htsp_t. Each entry in this table is a named property with a value that is a type - and a value hash (_vhash_). _vhash_'s key is each value that - the property ever took, and _vhash_'s value is an - integer value of how many times the given property is taken. + and a value hash (_vhash_). Refer to \ref htsp_entry_t. + - _vhash_'s key is each value that the property ever took + - _vhash_'s value is an integer value of how many times the given property is taken. A value can be added any time using \ref pcb_props_add. All values ever seen for a property is stored. @@ -49,13 +14,16 @@ per value (per property) is kept tracked on. Typically at the end of a query, but generally any time, the caller may query for: - - all known properties (it's a \ref htsp returned by \ref pcb_props_init) + - all known properties (it's a \ref htsp_t returned by \ref pcb_props_init) - all known values of a property \ref pcb_props_get - statistics of values of a property \ref pcb_props_stat + A _core_ property is one handled by, and directly created, from pcb-rnd. + A non-core property is one added by the user. + \fn htsp_t *pcb_props_init(void); - Starts a new list of properties. + Starts a new list of properties. Use \ref pcb_props_uninit to free the list. \return A newly allocated string-keyed hash table. @@ -65,56 +33,147 @@ \fn const char *pcb_props_type_name(pcb_prop_type_t type); - \return The type name of a property type, or NULL on error. + \return The type name of a property \p type, or \c NULL on error. \fn pcb_props_t *pcb_props_add(htsp_t *props, const char *propname, pcb_prop_type_t type, pcb_propval_t val); - Adds a value \p val of \p type to a named property \p propname ; - if the value is already known, its counter is increased. - If \p propname didn't exist, creates it. + Adds to the list of \p props, a value \p val of \p type to a named + property \p propname ; if the value is already known, its counter is increased. + If \p propname doesn't exist, creates it. - Error conditions: - - invalid type - - mismatching type for the property + Error conditions: + - invalid type + - mismatching type for the property (all values of a given property must be of the same type) - \return NULL on error conditions, else the added (or modified) property. + \return \c NULL on error conditions, else the added (or modified) property. \fn pcb_props_t *pcb_props_get(htsp_t *props, const char *propname); - Retrieves property structure for a given \p propname property name. + Retrieves the property, for a given \p propname property name. \param props The list of all properties to explore. - \return NULL if \p propname doesn't exist. + \return \c NULL if \p propname doesn't exist, else the property. \fn pcb_props_t *pcb_props_stat(htsp_t *props, const char *propname, - pcb_propval_t *most_common, pcb_propval_t *min, pcb_propval_t *max, pcb_propval_t *avg); + pcb_propval_t *most_common, pcb_propval_t *min, pcb_propval_t *max, pcb_propval_t *avg); - Looks up property \p propname and calculates statistics for all values occured so far. - Any of most_common, min, max and avg can be NULL. + Looks up property \p propname in all \p props, and calculates statistics + for all values occured so far. + + min, max, avg are meaningful only for numeric value types. - Invalid type/stat combinations: - type=string min, max, avg ??? Do you mean when type=string, min, max, avg = NULL ? + Invalid type/stat combinations: + type=string min, max, avg Q:Alain->Igor2 : Do you mean when type=string, min, max, avg = NULL ? - \param [out] min, max, avg The statistic results. - \return NULL if \p propname doesn't exist or stat values that - can not be calculated for the given type are not NULL. + \param [out] min, max, avg The statistic results. + \param [out] most_common ? a string ? + \param [in] most_common, min, max, avg Pointers to value holder. Can be \c NULL. + \return \c NULL if \p propname doesn't exist or stat values that + can not ? be calculated for the given type are not \c NULL. ? + Your comments are ... not so clear. Need to sort this out. \fn const char *propedit_query(void *pe, const char *cmd, const char *key, const char *val, int idx); - String query API for HIDs to call back without having to link... ? + ?? String query API for HIDs to call back without having to link... ? + \param pe a \ref pe_ctx_t property editor context. \todo should be pe_ctx_t i.s.o **void** here ? + \param cmd There seems to have conventions for commands... Need to document somewhere. Is it in dev corner ? + \param key, val Queries for these key, val ? + \param idx Unused ? + \return \c NULL as an invalid query ; else ? + \fn const char *propedit_sprint_val(pcb_prop_type_t type, pcb_propval_t val); + Depending on \p type, the \p val value will be formated and returned. + \remark There's a set of static buffers, old values are discarded after 8 calls! - \return The value of a property as string - there's a set of static buffers, - old values are discarded after 8 calls! + \return The value of a property, as string. \fn void propedit_ins_prop(pe_ctx_t *ctx, htsp_entry_t *pe); + Adds a row at the end of the GUI Property Editor table, using \p pe property info. - Adds a row in the gui propedit table ! ?? - \param ctx ? - \param pe ? + \param ctx A Property Editor context. + \todo Not consistent here, as \ref pe_ctx_t is "for internal use only", and + there is no API to retrieve it !? */ + +/** \file props.h + Header file for \ref props.c + + \enum pcb_prop_type_t + A property type list, including string, integer, etc... + \var PCB_PROPT_invalid + At the moment, only used as a sentinel value. + \var PCB_PROPT_max + Sentinel value. + + + \union pcb_propval_t + Can hold the property value. + + + \struct pcb_props_t + A single property, as a combination of a property type and property values. + + \var pcb_props_t::core + 1 if it is a core property... Q:Alain->Igor2 : What is it used for ? + + + \typedef pe_ctx_t + for internal use. Keeps track of Property Editor context. + */ + +/** \todo Move those lines in htsp.dox file */ +/** \file htsp.c + A string-keyed hash table. + */ + +/** An entry in a string-keyed hash table. */ +typedef struct { + int flag; + unsigned int hash; + htsp_key_t key; + htsp_value_t value; +} htsp_entry_t; + +/** The string-keyed hash table structure. + + Macro generated typedef : + \see src_3rd/liblihata/genht/htsp.h + */ +typedef struct { + unsigned int mask; + unsigned int fill; + unsigned int used; + htsp_entry_t *table; + + unsigned int (*keyhash)(htsp_const_key_t); + int (*keyeq)(htsp_const_key_t, htsp_const_key_t); +#ifdef GENHT_USER_FIELDS + GENHT_USER_FIELDS +#endif +} htsp_t; + + +typedef struct { + int flag; + unsigned int hash; + htprop_key_t key; + htprop_value_t value; +} htprop_entry_t; + +typedef struct { + unsigned int mask; + unsigned int fill; + unsigned int used; + htprop_entry_t *table; + + unsigned int (*keyhash)(htprop_const_key_t); + int (*keyeq)(htprop_const_key_t, htprop_const_key_t); +#ifdef GENHT_USER_FIELDS + GENHT_USER_FIELDS +#endif +} htprop_t; Index: doxygen/src_plugins/propedit/propsel.dox =================================================================== --- doxygen/src_plugins/propedit/propsel.dox (revision 7380) +++ doxygen/src_plugins/propedit/propsel.dox (revision 7381) @@ -1,34 +1,44 @@ /** \file propsel.c - \brief This API builds a property list by looking at all selected objects on a design. + \brief Builds a property list by looking at all selected objects on a design. - - attribute : "a/" + path - - property : "p/" + path + Syntax definition: + - attribute : "a/" + \c element + "/" + \c property + - property : "p/" + \c element + "/" + \c property + ... ? + - \c element is \c line, \c trace, \c text ... + - \c property is \c rotation, ... + Q:Alain->Igor2 : Why the att AND prop ? To me they are synonyms. What difference do you make ? + \fn void pcb_propsel_map_core(htsp_t *props); - Loops through all PCB elements to populate the \p props properties Hash Table. + Loops through all PCB elements to only populate the selected elements + properties in \p props Hash Table. - Why \c core in name ? don't know. + Q:Alain->Igor2 : Why \c _core in name ? \fn int pcb_propsel_set(const char *prop, const char *value); - Applies property \p prop \p value to ?ALL PCB elements? most probably - to selection only (...sel_..) ? + Loops through all PCB elements to only set property \p value to \p prop + on selected elements. - \return The number of changes that has been operated. + \return The number of changes that has occured. \fn int pcb_propsel_del(const char *attr_name); - Do not attempt to remove anything but attributes named \p attr_name + Do not attempt to remove anything but attributes named \p attr_name. \return The number of attributes that has been deleted. \typedef set_ctx_t - Used to keep track of \ref pcb_propsel_set operations + Used to keep track of \ref pcb_propsel_set operations. \struct set_ctx_s the structure that is \ref set_ctx_t typedef'd \var int set_ctx_s::set_cnt Counts the number of operations. + + + \typedef del_ctx_t + Used to keep track of \ref pcb_propsel_del operations. */