![]() |
![]() |
![]() |
GNOME Data Access 3.0 manual | ![]() |
---|---|---|---|---|
GdaParameter; GdaParameter* gda_parameter_new (GType type); GdaParameter* gda_parameter_new_copy (GdaParameter *orig); GdaParameter* gda_parameter_new_string (const gchar *name, const gchar *str); GdaParameter* gda_parameter_new_boolean (const gchar *name, gboolean value); GType gda_parameter_get_g_type (GdaParameter *param); const GValue* gda_parameter_get_value (GdaParameter *param); gchar* gda_parameter_get_value_str (GdaParameter *param); void gda_parameter_set_value (GdaParameter *param, const GValue *value); gboolean gda_parameter_set_value_str (GdaParameter *param, const gchar *value); gchar* gda_parameter_get_alphanum_name (GdaParameter *param); void gda_parameter_declare_invalid (GdaParameter *param); gboolean gda_parameter_is_valid (GdaParameter *param); const GValue* gda_parameter_get_default_value (GdaParameter *param); void gda_parameter_set_default_value (GdaParameter *param, const GValue *value); gboolean gda_parameter_get_exists_default_value (GdaParameter *param); void gda_parameter_set_exists_default_value (GdaParameter *param, gboolean default_value_exists); void gda_parameter_set_not_null (GdaParameter *param, gboolean not_null); gboolean gda_parameter_get_not_null (GdaParameter *param); gboolean gda_parameter_restrict_values (GdaParameter *param, GdaDataModel *model, gint col, GError **error); gboolean gda_parameter_has_restrict_values (GdaParameter *param, GdaDataModel **model, gint *col); void gda_parameter_bind_to_param (GdaParameter *param, GdaParameter *bind_to); GdaParameter* gda_parameter_get_bind_param (GdaParameter *param);
"entry-plugin" gchararray : Read / Write "full-bind" GdaParameter : Read / Write "g-type" gulong : Read / Write / Construct Only "not-null" gboolean : Read / Write "restrict-column" gint : Read / Write "restrict-model" GdaDataModel : Read / Write "simple-bind" GdaParameter : Read / Write "use-default-value" gboolean : Read / Write
A GdaParameter object basically is a specification for a value and can convey a value once one has been set.
The GdaParameter object offers other features such as:
keeping a list of objects which "are interested" (mentioned as "users" in the API) in the value placed in the parameter: this feature is usefull when parameters are created by objects and when these objects want to be reminded that the parameter has been created by them at a later time
aliasing (binding) to another parameter: this is an easy way to keep several parameters synchronized. There are two modes: one where parameters A and B will always have the same value and where parameter B will update itself whan A changes to mirror tha change but will be allowed to have its own changes afterwards.
values restrictions: a parameter can be told to choose a value among the values in a colmun in a GdaDataModel (beware that this is a declarative feature only and that no policy is enforced regarding values changes)
GdaParameter* gda_parameter_new (GType type);
Creates a new parameter of type type
type : |
the GType requested |
Returns : | a new GdaParameter object |
GdaParameter* gda_parameter_new_copy (GdaParameter *orig);
Copy constructor.
orig : |
a GdaParameter object to copy |
Returns : | a new GdaParameter object |
GdaParameter* gda_parameter_new_string (const gchar *name, const gchar *str);
Creates a new GdaParameter object of type G_TYPE_STRING
name : |
the name of the parameter to create |
str : |
the contents of the parameter to create |
Returns : | a new GdaParameter object |
GdaParameter* gda_parameter_new_boolean (const gchar *name, gboolean value);
Creates a new GdaParameter object of type G_TYPE_BOOLEAN
name : |
the name of the parameter to create |
value : |
the value to give to the new parameter |
Returns : | a new GdaParameter object |
GType gda_parameter_get_g_type (GdaParameter *param);
Get the requested data type for param
.
param : |
a GdaParameter object |
Returns : | the data type |
const GValue* gda_parameter_get_value (GdaParameter *param);
Get the value held into the parameter
param : |
a GdaParameter object |
Returns : | the value (a NULL value returns a GDA_TYPE_NULL GValue) |
gchar* gda_parameter_get_value_str (GdaParameter *param);
Get a string representation of the value stored in param
. Calling
gda_parameter_set_value_str()
with this value will restore param
's current
state.
param : |
a GdaParameter object |
Returns : | a new string, or NULL if param 's value is NULL
|
void gda_parameter_set_value (GdaParameter *param, const GValue *value);
param : |
|
value : |
gboolean gda_parameter_set_value_str (GdaParameter *param, const gchar *value);
Same function as gda_parameter_set_value()
except that the value
is provided as a string, and may return FALSE if the string did not
represent a correct value for the data type of the parameter.
param : |
a GdaParameter object |
value : |
a value to set the parameter to, as a string |
Returns : | TRUE if no error occurred |
gchar* gda_parameter_get_alphanum_name (GdaParameter *param);
Get an "encoded" version of param
's name. The "encoding" consists in replacing non
alphanumeric character with the string "__gdaXX" where XX is the hex. representation
of the non alphanumeric char.
This method is just a wrapper around the gda_text_to_alphanum()
function.
param : |
a GdaParameter object |
Returns : | a new string |
void gda_parameter_declare_invalid (GdaParameter *param);
Forces a parameter to be invalid; to set it valid again, a new value must be assigned
to it using gda_parameter_set_value()
.
param : |
a GdaParameter object |
gboolean gda_parameter_is_valid (GdaParameter *param);
Get the validity of param
(that is, of the value held by param
)
param : |
a GdaParameter object |
Returns : | TRUE if param 's value can safely be used
|
const GValue* gda_parameter_get_default_value (GdaParameter *param);
Get the default value held into the parameter. WARNING: the default value does not need to be of
the same type as the one required by param
.
param : |
a GdaParameter object |
Returns : | the default value |
void gda_parameter_set_default_value (GdaParameter *param, const GValue *value);
param : |
|
value : |
gboolean gda_parameter_get_exists_default_value (GdaParameter *param);
param : |
a GdaParameter object |
Returns : | TRUE if param has a default value (which may be unspecified)
|
void gda_parameter_set_exists_default_value (GdaParameter *param, gboolean default_value_exists);
Tells if param
has default unspecified value. This function is usefull
if one wants to inform that param
has a default value but does not know
what that default value actually is.
param : |
|
default_value_exists : |
void gda_parameter_set_not_null (GdaParameter *param, gboolean not_null);
Sets if the parameter can have a NULL value. If not_null
is TRUE, then that won't be allowed
param : |
a GdaParameter object |
not_null : |
gboolean gda_parameter_get_not_null (GdaParameter *param);
Get wether the parameter can be NULL or not
param : |
a GdaParameter object |
Returns : | TRUE if the parameter cannot be NULL |
gboolean gda_parameter_restrict_values (GdaParameter *param, GdaDataModel *model, gint col, GError **error);
Sets a limit on the possible values for the param
parameter: the value must be among the values
contained in the col
column of the model
data model.
param : |
a GdaParameter object |
model : |
a GdaDataModel object or NULL |
col : |
the reference column in model
|
error : |
location to store error, or NULL
|
Returns : | TRUE if no error occurred |
gboolean gda_parameter_has_restrict_values (GdaParameter *param, GdaDataModel **model, gint *col);
Tells if param
has its values restricted by a GdaDataModel, and optionnaly
allows to fetch the resteictions.
param : |
a GdaParameter |
model : |
a place to store a pointer to the model restricting the parameter, or NULL
|
col : |
a place to store the column in the model restricting the parameter, or NULL
|
Returns : | TRUE if param has its values restricted.
|
void gda_parameter_bind_to_param (GdaParameter *param, GdaParameter *bind_to);
Sets param
to change when bind_to
changes (and does not make bind_to
change when param
changes)
param : |
a GdaParameter |
bind_to : |
a GdaParameter or NULL
|
GdaParameter* gda_parameter_get_bind_param (GdaParameter *param);
Get the parameter which makes param
change its value when the param's value is changed.
param : |
a GdaParameter |
Returns : | the GdaParameter or NULL
|
restrict-column
" property"restrict-column" gint : Read / Write
Allowed values: >= 0
Default value: 0
void user_function (GdaParameter *gdaparameter, gpointer user_data) : Run First
gdaparameter : |
the object which received the signal. |
user_data : |
user data set when the signal handler was connected. |