MgParameter

Name

MgParameter -- Represents a parameter when needed to execute a query

Synopsis



#define     MG_PARAMETER_TYPE
#define     MG_PARAMETER                    (obj)
#define     IS_MG_PARAMETER                 (obj)
#define     MG_PARAMETER_CLASS              (klass)
struct      MgParameter;
guint       mg_parameter_get_type           (void);
GObject*    mg_parameter_new                (MgConf *conf,
                                             MgServerDataType *type);
GObject*    mg_parameter_new_with_dest_field
                                            (MgQfield *field,
                                             MgServerDataType *type);
void        mg_parameter_add_dest_field     (MgParameter *param,
                                             MgQfield *field);
GSList*     mg_parameter_get_dest_fields    (MgParameter *param);
MgServerDataType* mg_parameter_get_data_type
                                            (MgParameter *param);
const GdaValue* mg_parameter_get_value      (MgParameter *param);
void        mg_parameter_set_value          (MgParameter *param,
                                             const GdaValue *value);
void        mg_parameter_declare_invalid    (MgParameter *param);
gboolean    mg_parameter_is_valid           (MgParameter *param);
const GdaValue* mg_parameter_get_default_value
                                            (MgParameter *param);
void        mg_parameter_set_default_value  (MgParameter *param,
                                             const GdaValue *value);
void        mg_parameter_set_not_null       (MgParameter *param,
                                             gboolean not_null);
gboolean    mg_parameter_get_not_null       (MgParameter *param);
gboolean    mg_parameter_set_source_field   (MgParameter *param,
                                             MgQfield *field,
                                             GError **error);
MgQfield*   mg_parameter_get_source_field   (MgParameter *param);
void        mg_parameter_add_dependency     (MgParameter *param,
                                             MgParameter *depend_on);
void        mg_parameter_del_dependency     (MgParameter *param,
                                             MgParameter *depend_on);
GSList*     mg_parameter_get_dependencies   (MgParameter *param);
void        mg_parameter_replace_ref        (MgParameter *param,
                                             GHashTable *replacements);
void        mg_parameter_bind_to_param      (MgParameter *param,
                                             MgParameter *bind_to);
MgParameter* mg_parameter_get_bind_param    (MgParameter *param);
gboolean    mg_parameter_requires_user_input
                                            (MgParameter *param);
void        mg_parameter_set_user_input_required
                                            (MgParameter *param,
                                             gboolean input_required);

Object Hierarchy


  GObject
   +----MgBase
         +----MgParameter

Properties


  "full-bind"            gpointer             : Read / Write
  "handler-plugin"       gchararray           : Read / Write
  "simple-bind"          gpointer             : Read / Write
  "use-default-value"    gboolean             : Read / Write

Description

A MgParameter object basically conveys a value (as a GdaValue) and several attributes specifying the value itself.

Parameters are usually used in conjunction with queries when they are required before the queries can be executed, but they can also be created by hand when a value is requested from the user.

Also a parameter can be set to an alias of another parameter, in which case that parameter and the one of which it is an alias will always be synchronized regarding their value and attributes. This feature is usefull when a parameter required by a query needs to be synchronized to an already existing parameter.

Details

MG_PARAMETER_TYPE

#define MG_PARAMETER_TYPE          (mg_parameter_get_type())


MG_PARAMETER()

#define MG_PARAMETER(obj)          G_TYPE_CHECK_INSTANCE_CAST (obj, mg_parameter_get_type(), MgParameter)

obj :


IS_MG_PARAMETER()

#define IS_MG_PARAMETER(obj)       G_TYPE_CHECK_INSTANCE_TYPE (obj, mg_parameter_get_type ())

obj :


MG_PARAMETER_CLASS()

#define MG_PARAMETER_CLASS(klass)  G_TYPE_CHECK_CLASS_CAST (klass, mg_parameter_get_type (), MgParameterClass)

klass :


struct MgParameter

struct MgParameter;


mg_parameter_get_type ()

guint       mg_parameter_get_type           (void);

Returns :


mg_parameter_new ()

GObject*    mg_parameter_new                (MgConf *conf,
                                             MgServerDataType *type);

Creates a new parameter of type type

conf :

a MgConf object

type :

the MgServerDataType requested

Returns :

a new MgParameter object


mg_parameter_new_with_dest_field ()

GObject*    mg_parameter_new_with_dest_field
                                            (MgQfield *field,
                                             MgServerDataType *type);

Creates a new parameter to be passed to field for the operations where a parameter is required; other MgQfield can also be added by using the mg_parameter_add_dest_field() method.

field :

the MgQfield object the parameter is for

type :

the MgServerDataType requested

Returns :

a new MgParameter object


mg_parameter_add_dest_field ()

void        mg_parameter_add_dest_field     (MgParameter *param,
                                             MgQfield *field);

Adds a MgQfield object for which the parameter is for

param :

a MgParameter object

field :

the MgQfield object the parameter is for


mg_parameter_get_dest_fields ()

GSList*     mg_parameter_get_dest_fields    (MgParameter *param);

Get the MgQfield objects which created param (and which will use its value)

param :

a MgParameter object

Returns :

the list of MgQfield object


mg_parameter_get_data_type ()

MgServerDataType* mg_parameter_get_data_type
                                            (MgParameter *param);

Get the requested data type for param.

param :

a MgParameter object

Returns :

the data type


mg_parameter_get_value ()

const GdaValue* mg_parameter_get_value      (MgParameter *param);

Get the value held into the parameter

param :

a MgParameter object

Returns :

the value


mg_parameter_set_value ()

void        mg_parameter_set_value          (MgParameter *param,
                                             const GdaValue *value);

param :

value :


mg_parameter_declare_invalid ()

void        mg_parameter_declare_invalid    (MgParameter *param);

Forces a parameter to be invalid; to set it valid again, a new value must be assigned to it using mg_parameter_set_value().

param :

a MgParameter object


mg_parameter_is_valid ()

gboolean    mg_parameter_is_valid           (MgParameter *param);

Get the validity of param (that is, of the value held by param)

param :

a MgParameter object

Returns :

TRUE if param's value can safely be used


mg_parameter_get_default_value ()

const GdaValue* mg_parameter_get_default_value
                                            (MgParameter *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 MgParameter object

Returns :

the default value


mg_parameter_set_default_value ()

void        mg_parameter_set_default_value  (MgParameter *param,
                                             const GdaValue *value);

param :

value :


mg_parameter_set_not_null ()

void        mg_parameter_set_not_null       (MgParameter *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 MgParameter object

not_null :


mg_parameter_get_not_null ()

gboolean    mg_parameter_get_not_null       (MgParameter *param);

Get wether the parameter can be NULL or not

param :

a MgParameter object

Returns :

TRUE if the parameter cannot be NULL


mg_parameter_set_source_field ()

gboolean    mg_parameter_set_source_field   (MgParameter *param,
                                             MgQfield *field,
                                             GError **error);

Sets a limit on the possible values for the param parameter: they must be among the values of field when the SELECT query to which field belongs is executed. field must be of the same type as the requested type for param.

field is not copied, just referenced (maybe it'd better to make a copy of it...)

param :

a MgParameter object

field :

a MgQfield object or NULL

error :

location to store error, or NULL

Returns :

TRUE if no error occured


mg_parameter_get_source_field ()

MgQfield*   mg_parameter_get_source_field   (MgParameter *param);

param :

Returns :


mg_parameter_add_dependency ()

void        mg_parameter_add_dependency     (MgParameter *param,
                                             MgParameter *depend_on);

Tell param that its value will depend on the value of depend_on

param :

a MgParameter object

depend_on :

a MgParameter object


mg_parameter_del_dependency ()

void        mg_parameter_del_dependency     (MgParameter *param,
                                             MgParameter *depend_on);

Remove the depend_on dependency from param

param :

a MgParameter object

depend_on :

a MgParameter object


mg_parameter_get_dependencies ()

GSList*     mg_parameter_get_dependencies   (MgParameter *param);

Get the list of MgParameter param depends on

param :

a MgParameter object

Returns :

the list of parameters


mg_parameter_replace_ref ()

void        mg_parameter_replace_ref        (MgParameter *param,
                                             GHashTable *replacements);

Replace references to some objects by references to some other objects, as listed in replacements.

param :

a MgParameter object

replacements :

the (objects to be replaced, replacing object) pairs


mg_parameter_bind_to_param ()

void        mg_parameter_bind_to_param      (MgParameter *param,
                                             MgParameter *bind_to);

Sets param to change when bind_to changes (and does not make bind_to change when param changes)

param :

a MgParameter

bind_to :

a MgParameter or NULL


mg_parameter_get_bind_param ()

MgParameter* mg_parameter_get_bind_param    (MgParameter *param);

Get the parameter which makes param change its value when the param's value is changed.

param :

a MgParameter

Returns :

the MgParameter or NULL


mg_parameter_requires_user_input ()

gboolean    mg_parameter_requires_user_input
                                            (MgParameter *param);

Tells if the parameter is configured in a way that even if there is a value, it requires that the user at least validates that value, or change it.

param :

a MgParameter

Returns :

TRUE if user input is required


mg_parameter_set_user_input_required ()

void        mg_parameter_set_user_input_required
                                            (MgParameter *param,
                                             gboolean input_required);

Sets if the user input is required for param (even though it may already have a value) and be valid.

param :

a MgParameter

input_required :

Properties

"full-bind" (gpointer : Read / Write)

"handler-plugin" (gchararray : Read / Write)

"simple-bind" (gpointer : Read / Write)

"use-default-value" (gboolean : Read / Write)