diff --git a/include/c74_max_object.h b/include/c74_max_object.h index c6fc16c..1687ca6 100644 --- a/include/c74_max_object.h +++ b/include/c74_max_object.h @@ -3067,6 +3067,91 @@ namespace max { */ t_max_err atom_alloc_array(long minsize, long* ac, t_atom** av, char* alloc); + /** + Retrieves the integer value of a particular t_atom from an atom list, if the atom exists. + @ingroup atom + @param c Pointer to a long variable to receive the atom's data if the function is successful. + @param idx Offset into the atom list of the atom of interest, starting from 0. + For instance, if you want data from the 3rd atom in the atom list, idx should be set to 2. + @param ac Count of av. + @param av Pointer to the first t_atom of an atom list. + @return This function returns the error code #MAX_ERR_NONE if successful, + or one of the other error codes defined in #e_max_errorcodes if unsuccessful. + @remark The atom_arg_getlong() function only changes the value of c if the function is successful. + For instance, the following code snippet illustrates a simple, but typical use: + @code + void myobject_mymessage(t_myobject *x, t_symbol *s, long ac, t_atom *av) + { + t_atom_long var = -1; + // here, we are expecting a value of 0 or greater + atom_arg_getlong(&var, 0, ac, av); + if (val == -1) // i.e. unchanged + post("it is likely that the user did not provide a valid argument"); + else { + ... + } + } + @endcode + */ + t_max_err atom_arg_getlong(t_atom_long *c, long idx, long ac, const t_atom *av); + + + /** + Retrieves the floating point value of a particular t_atom from an atom list, if the atom exists. + @ingroup atom + @param c Pointer to a float variable to receive the atom's data if the function is successful. Otherwise, the value is left unchanged. + @param idx Offset into the atom list of the atom of interest, starting from 0. + For instance, if you want data from the 3rd atom in the atom list, idx should be set to 2. + @param ac Count of av. + @param av Pointer to the first t_atom of an atom list. + @return This function returns the error code #MAX_ERR_NONE if successful, + or one of the other error codes defined in #e_max_errorcodes if unsuccessful. + */ + long atom_arg_getfloat(float *c, long idx, long ac, const t_atom *av); + + + /** + Retrieves the floating point value, as a double, of a particular t_atom from an atom list, if the atom exists. + @ingroup atom + @param c Pointer to a double variable to receive the atom's data if the function is successful. Otherwise the value is left unchanged. + @param idx Offset into the atom list of the atom of interest, starting from 0. + For instance, if you want data from the 3rd atom in the atom list, idx should be set to 2. + @param ac Count of av. + @param av Pointer to the first t_atom of an atom list. + @return This function returns the error code #MAX_ERR_NONE if successful, + or one of the other error codes defined in #e_max_errorcodes if unsuccessful. + */ + long atom_arg_getdouble(double *c, long idx, long ac, const t_atom *av); + + + /** + Retrieves the t_symbol * value of a particular t_atom from an atom list, if the atom exists. + @ingroup atom + @param c Pointer to a t_symbol * variable to receive the atom's data if the function is successful. Otherwise, the value is left unchanged. + @param idx Offset into the atom list of the atom of interest, starting from 0. + For instance, if you want data from the 3rd atom in the atom list, idx should be set to 2. + @param ac Count of av. + @param av Pointer to the first t_atom of an atom list. + @return This function returns the error code #MAX_ERR_NONE if successful, + or one of the other error codes defined in #e_max_errorcodes if unsuccessful. + @remark The atom_arg_getsym() function only changes the value of c if the function is successful. + For instance, the following code snippet illustrates a simple, but typical use: + @code + void myobject_open(t_myobject *x, t_symbol *s, long ac, t_atom *av) + { + t_symbol *filename = _sym_nothing; + // here, we are expecting a file name. + // if we don't get it, open a dialog box + atom_arg_getsym(&filename, 0, ac, av); + if (filename == _sym_nothing) { // i.e. unchanged + // open the file dialog box, + // get a value for filename + } + // do something with the filename + } + @endcode + */ + long atom_arg_getsym(t_symbol **c, long idx, long ac, const t_atom *av); /** Determine if a class is a user interface object.