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:

attribute (str) – attribute name
value (GObject.Value) – a GObject.Value, or None
destroy (GLib.DestroyNotify) – a function to be called when attribute is not needed anymore, or None

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:

model (Gda.DataModel) – a Gda.DataModel object or None
col (int) – the reference column in model

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:

dh (Gda.DataHandler) – a Gda.DataHandler to use, or None
value (str) – a value to set the holder to, as a string

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:

att_name (str) –
att_value (GObject.Value) –

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>
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.