Gda.Holder

g GObject.GInterface GObject.GInterface Gda.Lockable Gda.Lockable GObject.GInterface->Gda.Lockable GObject.Object GObject.Object Gda.Holder Gda.Holder GObject.Object->Gda.Holder Gda.Lockable->Gda.Holder

Subclasses:None

Methods

Inherited:GObject.Object (37), Gda.Lockable (3)
Structs:GObject.ObjectClass (5)
class error_quark ()
class new (type)
  copy ()
  force_invalid ()
  force_invalid_e (error)
  get_alphanum_id ()
  get_attribute (attribute)
  get_bind ()
  get_default_value ()
  get_g_type ()
  get_id ()
  get_not_null ()
  get_source_model (col)
  get_value ()
  get_value_str (dh)
  is_valid ()
  is_valid_e ()
  set_attribute (attribute, value, destroy)
  set_bind (bind_to)
  set_default_value (value)
  set_not_null (not_null)
  set_source_model (model, col)
  set_value (value)
  set_value_str (dh, value)
  set_value_to_default ()
  take_static_value (value, value_changed)
  take_value (value)
  value_is_default ()

Virtual Methods

Inherited:GObject.Object (7), Gda.Lockable (3)
  do_att_changed (att_name, att_value)
  do_changed ()
  do_source_changed ()
  do_validate_change (new_value)

Properties

Name Type Flags Short Description
description str r/w Holder’s description
full-bind Gda.Holder r/w Make value holder follow other Gda.Holder’s changes and the other way around
g-type GObject.GType r/w/c Holder’s GObject.GType
id str r/w Holder’s ID
name str r/w Holder’s name
not-null bool r/w Can the value holder be None?
simple-bind Gda.Holder r/w Make value holder follow other Gda.Holder’s changes
source-column int r/w Column number to use in coordination with the source-model property
source-model Gda.DataModel r/w Data model among which the holder’s value should be
validate-changes bool r/w Defines if the validate-change signal is emitted on value change

Signals

Inherited:GObject.Object (1)
Name Short Description
attribute-changed Gets emitted when any holder’s attribute has changed
changed Gets emitted when holder’s value has changed
source-changed Gets emitted when the data model in which holder’s values should be has changed
validate-change Gets emitted when holder is going to change its value.

Fields

Inherited:GObject.Object (1)
Name Type Access Description
object GObject.Object r  

Class Details

class Gda.Holder(**kwargs)
Bases:GObject.Object, Gda.Lockable
Abstract:No
Structure:Gda.HolderClass
classmethod error_quark()
Return type:int
classmethod new(type)
Parameters:type (GObject.GType) – the GObject.GType requested
Returns:a new Gda.Holder object
Return type:Gda.Holder

Creates a new holder of type type

copy()
Returns:a new Gda.Holder object
Return type:Gda.Holder

Copy constructor.

Note1: if self is set with a static value (see Gda.Holder.take_static_value()) its copy will have a fresh new allocated GObject.Value, so that user should free it when done.

force_invalid()

Forces a holder to be invalid; to set it valid again, a new value must be assigned to it using Gda.Holder.set_value() or Gda.Holder.take_value().

self’s value is set to None.

force_invalid_e(error)
Parameters:error (GLib.Error or None) – a GLib.Error explaining why self is declared invalid, or None

Forces a holder to be invalid; to set it valid again, a new value must be assigned to it using Gda.Holder.set_value() or Gda.Holder.take_value().

self’s value is set to None.

New in version 4.2.10.

get_alphanum_id()
Returns:a new string
Return type:str

Get an “encoded” version of self’s name. The “encoding” consists in replacing non alphanumeric character with the string “__gdaXX” where XX is the hex. representation of the non alphanumeric str.

This method is just a wrapper around the Gda.text_to_alphanum() function.

get_attribute(attribute)
Parameters:attribute (str) – attribute name as a string
Returns:a read-only GObject.Value, or None if not attribute named attribute has been set for self
Return type:GObject.Value

Get the value associated to a named attribute.

Attributes can have any name, but Libgda proposes some default names, see ‘this section [libgda-40-Attributes-manager.synopsis]’.

get_bind()
Returns:the Gda.Holder or None
Return type:Gda.Holder

Get the holder which makes self change its value when the holder’s value is changed.

get_default_value()
Returns:the default value
Return type:GObject.Value

Get the default value held into the holder. WARNING: the default value does not need to be of the same type as the one required by self.

get_g_type()
Return type:GObject.GType
get_id()
Returns:the ID (don’t modify the string).
Return type:str

Get the ID of self. The ID can be set using self’s “id” property

get_not_null()
Returns:True if the holder cannot be None
Return type:bool

Get wether the holder can be None or not

get_source_model(col)
Parameters:col (int) – a place to store the column in the model sourcing the holder, or None
Returns:a pointer to a Gda.DataModel, or None
Return type:Gda.DataModel

If Gda.Holder.set_source_model() has been used to provide a hint that self’s value should be among the values contained in a column of a data model, then this method returns which data model, and if col is not None, then it is set to the restricting column as well.

Otherwise, this method returns None, and if col is not None, then it is set to 0.

get_value()
Returns:the value, or None
Return type:GObject.Value or None

Get the value held into the holder. If self is set to use its default value and that default value is not of the same type as self, then None is returned.

If self is set to None, then the returned value is a #GDA_TYPE_NULL GObject.Value.

If self is invalid, then the returned value is None.

get_value_str(dh)
Parameters:dh (Gda.DataHandler or None) – a Gda.DataHandler to use, or None
Returns:the value, or None
Return type:str

Same functionality as Gda.Holder.get_value() except that it returns the value as a string (the conversion is done using dh if not None, or the default data handler otherwise).

is_valid()
Returns:True if self’s value can safely be used
Return type:bool

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

is_valid_e()
Raises:GLib.Error
Returns:True if self’s value can safely be used
Return type:bool

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

New in version 4.2.10.

set_attribute(attribute, value, destroy)
Parameters:

Set the value associated to a named attribute. The attribute string is ‘stolen’ by this method, and the memory it uses will be freed using the destroy function when no longer needed (if destroy is None, then the string will not be freed at all).

Attributes can have any name, but Libgda proposes some default names, see ‘this section [libgda-5.0-Attributes-manager.synopsis]’.

For example one would use it as:

Gda.Holder.set_attribute (holder, GLib.strdup (my_attribute), my_value, GLib.free); Gda.Holder.set_attribute (holder, Gda.ATTRIBUTE_NAME, my_value, None); If there is already an attribute named attribute set, then its value is replaced with the new value (value is copied), except if value is None, in which case the attribute is removed.

set_bind(bind_to)
Parameters:bind_to (Gda.Holder) – a Gda.Holder or None
Raises:GLib.Error
Returns:True if no error occurred
Return type:bool

Sets self to change when bind_to changes (and does not make bind_to change when self changes). For the operation to succeed, the GObject.GType of self and bind_to must be the same, with the exception that any of them can have a %GDA_TYPE_NULL type (in this situation, the GObject.GType of the two Gda.Holder objects involved is set to match the other when any of them sets its type to something different than GDA_TYPE_NULL).

If bind_to is None, then self will not be bound anymore.

set_default_value(value)
Parameters:value (GObject.Value) – a value to set the holder’s default value, or None

Sets the default value within the holder. If value is None then self won’t have a default value anymore. To set a default value to None, then pass a GObject.Value created using gda_value_new_null().

NOTE: the default value does not need to be of the same type as the one required by self.

set_not_null(not_null)
Parameters:not_null (bool) – True if self should not accept None values

Sets if the holder can have a None value. If not_null is True, then that won’t be allowed

set_source_model(model, col)
Parameters:
Raises:

GLib.Error

Returns:

True if no error occurred

Return type:

bool

Sets an hint that self’s values should be restricted among the values contained in the col column of the model data model. Note that this is just a hint, meaning this policy is not enforced by self’s implementation.

If model is None, then the effect is to cancel ant previous call to Gda.Holder.set_source_model() where model was not None.

set_value(value)
Parameters:value (GObject.Value or None) – a value to set the holder to, or None
Raises:GLib.Error
Returns:True if value has been set
Return type:bool

Sets the value within the holder. If self is an alias for another holder, then the value is also set for that other holder.

On success, the action of any call to Gda.Holder.force_invalid() is cancelled as soon as this method is called (even if self’s value does not actually change)

If the value is not different from the one already contained within self, then self is not changed and no signal is emitted.

Note1: the value argument is treated the same way if it is None or if it is a #GDA_TYPE_NULL value

Note2: if self can’t accept the value value, then this method returns False, and self will be left in an invalid state.

Note3: before the change is accepted by self, the “validate-change” signal will be emitted (the value of which can prevent the change from happening) which can be connected to to have a greater control of which values self can have, or implement some business rules.

set_value_str(dh, value)
Parameters:
Raises:

GLib.Error

Returns:

True if value has been set

Return type:

bool

Same functionality as Gda.Holder.set_value() except that it uses a string representation of the value to set, which will be converted into a GObject.Value first (using default data handler if dh is None).

Note1: if value is None or is the “None” string, then self’s value is set to None. Note2: if self can’t accept the value value, then this method returns False, and self will be left in an invalid state.

set_value_to_default()
Returns:True if self has got a default value
Return type:bool

Set self’s value to its default value.

take_static_value(value, value_changed)
Parameters:
  • value (GObject.Value) – a const value to set the holder to
  • value_changed (bool) – a boolean set with True if the value changes, False elsewhere.
Raises:

GLib.Error

Returns:

None if an error occurred or if the previous GObject.Value was None itself. It returns the static GObject.Value user set previously, so that he can free it.

Return type:

GObject.Value

Sets the const value within the holder. If self is an alias for another holder, then the value is also set for that other holder.

The value will not be freed, and user should take care of it, either for its freeing or for its correct value at the moment of query.

If the value is not different from the one already contained within self, then self is not changed and no signal is emitted.

Note1: if self can’t accept the value value, then this method returns None, and self will be left in an invalid state.

Note2: before the change is accepted by self, the “validate-change” signal will be emitted (the value of which can prevent the change from happening) which can be connected to to have a greater control of which values self can have, or implement some business rules.

take_value(value)
Parameters:value (GObject.Value) – a value to set the holder to
Raises:GLib.Error
Returns:True if value has been set
Return type:bool

Sets the value within the holder. If self is an alias for another holder, then the value is also set for that other holder.

On success, the action of any call to Gda.Holder.force_invalid() is cancelled as soon as this method is called (even if self’s value does not actually change).

If the value is not different from the one already contained within self, then self is not changed and no signal is emitted.

Note1: if self can’t accept the value value, then this method returns False, and self will be left in an invalid state.

Note2: before the change is accepted by self, the “validate-change” signal will be emitted (the value of which can prevent the change from happening) which can be connected to to have a greater control of which values self can have, or implement some business rules.

Note3: if user previously set this holder with Gda.Holder.take_static_value () the GObject.Value stored internally will be forgiven and replaced by the value. User should then take care of the ‘old’ static GObject.Value.

value_is_default()
Returns:True if self self’s current value is the default one
Return type:bool

Tells if self’s current value is the default one.

do_att_changed(att_name, att_value) virtual
Parameters:
do_changed() virtual
do_source_changed() virtual
do_validate_change(new_value) virtual
Parameters:new_value (GObject.Value) –
Return type:GLib.Error

Signal Details

Gda.Holder.signals.attribute_changed(holder, att_name, att_value)
Signal Name:

attribute-changed

Flags:

RUN_FIRST

Parameters:
  • holder (Gda.Holder) – The object which received the signal
  • att_name (str) – attribute’s name
  • att_value (GObject.Value) – attribute’s value

Gets emitted when any holder’s attribute has changed

Gda.Holder.signals.changed(holder)
Signal Name:changed
Flags:RUN_FIRST
Parameters:holder (Gda.Holder) – The object which received the signal

Gets emitted when holder’s value has changed

Gda.Holder.signals.source_changed(holder)
Signal Name:source-changed
Flags:RUN_FIRST
Parameters:holder (Gda.Holder) – The object which received the signal

Gets emitted when the data model in which holder’s values should be has changed

Gda.Holder.signals.validate_change(holder, new_value)
Signal Name:

validate-change

Flags:

RUN_LAST

Parameters:
  • holder (Gda.Holder) – The object which received the signal
  • new_value (GObject.Value) – the proposed new value for holder
Returns:

None if holder is allowed to change its value to new_value, or a GLib.Error otherwise.

Return type:

GLib.Error

Gets emitted when holder is going to change its value. One can connect to this signal to control which values holder can have (for example to implement some business rules)

Property Details

Gda.Holder.props.description
Name:description
Type:str
Default Value:None
Flags:READABLE, WRITABLE

Holder’s description

Gda.Holder.props.full_bind
Name:full-bind
Type:Gda.Holder
Default Value:None
Flags:READABLE, WRITABLE

Make value holder follow other Gda.Holder’s changes and the other way around

Gda.Holder.props.g_type
Name:g-type
Type:GObject.GType
Default Value:<GType void (4)>
Flags:READABLE, WRITABLE, CONSTRUCT

Holder’s GObject.GType

Gda.Holder.props.id
Name:id
Type:str
Default Value:None
Flags:READABLE, WRITABLE

Holder’s ID

Gda.Holder.props.name
Name:name
Type:str
Default Value:None
Flags:READABLE, WRITABLE

Holder’s name

Gda.Holder.props.not_null
Name:not-null
Type:bool
Default Value:False
Flags:READABLE, WRITABLE

Can the value holder be None?

Gda.Holder.props.simple_bind
Name:simple-bind
Type:Gda.Holder
Default Value:None
Flags:READABLE, WRITABLE

Make value holder follow other Gda.Holder’s changes

Gda.Holder.props.source_column
Name:source-column
Type:int
Default Value:0
Flags:READABLE, WRITABLE

Column number to use in coordination with the source-model property

Gda.Holder.props.source_model
Name:source-model
Type:Gda.DataModel
Default Value:None
Flags:READABLE, WRITABLE

Data model among which the holder’s value should be

Gda.Holder.props.validate_changes
Name:validate-changes
Type:bool
Default Value:True
Flags:READABLE, WRITABLE

Defines if the “validate-change” signal gets emitted when the holder’s value changes.

New in version 5.2.0.