1 // -*- c++ -*-
2 // Generated by gmmproc 2.46.1 -- DO NOT MODIFY!
3 #ifndef _LIBGDAMM_HOLDER_H
4 #define _LIBGDAMM_HOLDER_H
5
6
7 #include <glibmm/ustring.h>
8 #include <sigc++/sigc++.h>
9
10 // -*- C++ -*- //
11
12 /* set.h
13 *
14 * Copyright 2006 libgdamm Development Team
15 *
16 * This library is free software; you can redistribute it and/or
17 * modify it under the terms of the GNU Lesser General Public
18 * License as published by the Free Software Foundation; either
19 * version 2.1 of the License, or(at your option) any later version.
20 *
21 * This library is distributed in the hope that it will be useful,
22 * but WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
24 * Lesser General Public License for more details.
25 *
26 * You should have received a copy of the GNU Lesser General Public
27 * License along with this library; if not, write to the Free
28 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
29 */
30
31 #include <libgdamm/datahandler.h>
32 #include <libgdamm/value.h>
33 #include <glibmm/object.h>
34 #include <glibmm/error.h>
35
36
37 #ifndef DOXYGEN_SHOULD_SKIP_THIS
38 typedef struct _GdaHolder GdaHolder;
39 typedef struct _GdaHolderClass GdaHolderClass;
40 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
41
42
43 #ifndef DOXYGEN_SHOULD_SKIP_THIS
44 namespace Gnome
45 {
46
47 namespace Gda
48 { class Holder_Class; } // namespace Gda
49
50 } // namespace Gnome
51 #endif //DOXYGEN_SHOULD_SKIP_THIS
52
53 namespace Gnome
54 {
55
56 namespace Gda
57 {
58
59 class DataModel;
60
61 class HolderError : public Glib::Error
62 {
63 public:
64 /**
65 */
66 enum Code
67 {
68 HOLDER_STRING_CONVERSION_ERROR,
69 HOLDER_VALUE_TYPE_ERROR,
70 HOLDER_VALUE_NULL_ERROR
71 };
72
73 HolderError(Code error_code, const Glib::ustring& error_message);
74 explicit HolderError(GError* gobject);
75 Code code() const;
76
77 #ifndef DOXYGEN_SHOULD_SKIP_THIS
78 private:
79
80 static void throw_func(GError* gobject);
81
82 friend void wrap_init(); // uses throw_func()
83
84 #endif //DOXYGEN_SHOULD_SKIP_THIS
85 };
86
87 } // namespace Gda
88
89 } // namespace Gnome
90
91 #ifndef DOXYGEN_SHOULD_SKIP_THIS
92 namespace Glib
93 {
94
95 template <>
96 class Value<Gnome::Gda::HolderError::Code> : public Glib::Value_Enum<Gnome::Gda::HolderError::Code>
97 {
98 public:
99 static GType value_type() G_GNUC_CONST;
100 };
101
102 } // namespace Glib
103 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
104
105
106 namespace Gnome
107 {
108
109 namespace Gda
110 {
111
112
113 /** Container for a single Gda::Value.
114 *
115 * The GdaHolder is a container for a single Gda::Value value. It also specifies
116 * various attributes of the contained value (default value, ...)
117 *
118 * @ingroup DataHandlers
119 */
120
121 class Holder : public Glib::Object
122 {
123
124 #ifndef DOXYGEN_SHOULD_SKIP_THIS
125
126 public:
127 typedef Holder CppObjectType;
128 typedef Holder_Class CppClassType;
129 typedef GdaHolder BaseObjectType;
130 typedef GdaHolderClass BaseClassType;
131
132 // noncopyable
133 Holder(const Holder&) = delete;
134 Holder& operator=(const Holder&) = delete;
135
136 private: friend class Holder_Class;
137 static CppClassType holder_class_;
138
139 protected:
140 explicit Holder(const Glib::ConstructParams& construct_params);
141 explicit Holder(GdaHolder* castitem);
142
143 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
144
145 public:
146
147 Holder(Holder&& src) noexcept;
148 Holder& operator=(Holder&& src) noexcept;
149
150 virtual ~Holder() noexcept;
151
152 /** Get the GType for this class, for use with the underlying GObject type system.
153 */
154 static GType get_type() G_GNUC_CONST;
155
156 #ifndef DOXYGEN_SHOULD_SKIP_THIS
157
158
159 static GType get_base_type() G_GNUC_CONST;
160 #endif
161
162 ///Provides access to the underlying C GObject.
gobj()163 GdaHolder* gobj() { return reinterpret_cast<GdaHolder*>(gobject_); }
164
165 ///Provides access to the underlying C GObject.
gobj()166 const GdaHolder* gobj() const { return reinterpret_cast<GdaHolder*>(gobject_); }
167
168 ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
169 GdaHolder* gobj_copy();
170
171 private:
172
173 protected:
174 Holder(GType g_type, const Glib::ustring& id);
175 public:
176
177 static Glib::RefPtr<Holder> create(GType g_type, const Glib::ustring& id);
178
179
180 /** Copy constructor.
181 *
182 * @note if @a orig is set with a static value (see take_static_value())
183 * its copy will have a fresh new allocated GValue, so that user should free it when done.
184 *
185 * @return A new Gda::Holder object.
186 */
187 Glib::RefPtr<Holder> copy() const;
188
189
190 /** Get @a holder's type
191 *
192 * @return The data type.
193 */
194 GType get_g_type() const;
195
196 /** Get the ID of @a holder. The ID can be set using @a holder's "id" property
197 *
198 * @return The ID (don't modify the string).
199 */
200 Glib::ustring get_id() const;
201
202
203 /** Get the value held into the holder. If @a holder is set to use its default value
204 * and that default value is not of the same type as @a holder, then <tt>0</tt> is returned.
205 *
206 * If @a holder is set to <tt>0</tt>, then the returned value is a Gda::TYPE_NULL GValue.
207 *
208 * @return The value, or <tt>0</tt>.
209 */
210 Value get_value() const;
211
212
213 /** Same functionality as get_value() except that it returns the value as a string
214 * (the conversion is done using @a dh if not <tt>0</tt>, or the default data handler otherwise).
215 *
216 * @param dh A Gda::DataHandler to use, or <tt>0</tt>.
217 * @return The value, or <tt>0</tt>.
218 */
219 Glib::ustring get_value_str(const Glib::RefPtr<DataHandler>& dh) const;
220
221
222 /** Sets the value within the holder. If @a holder is an alias for another
223 * holder, then the value is also set for that other holder.
224 *
225 * On success, the action of any call to force_invalid() is cancelled
226 * as soon as this method is called (even if @a holder's value does not actually change)
227 *
228 * If the value is not different from the one already contained within @a holder,
229 * then @a holder is not changed and no signal is emitted.
230 *
231 * @note the @a value argument is treated the same way if it is <tt>0</tt> or if it is a Gda::TYPE_NULL value
232 *
233 * @note if @a holder can't accept the @a value value, then this method returns <tt>false</tt>, and @a holder will be left
234 * in an invalid state.
235 *
236 * @note before the change is accepted by @a holder, the "validate-change" signal will be emitted (the value
237 * of which can prevent the change from happening) which can be connected to to have a greater control
238 * of which values @a holder can have, or implement some business rules.
239 *
240 * @param value A value to set the holder to, or <tt>0</tt>.
241 * @return <tt>true</tt> if value has been set.
242 */
243 bool set_value_as_value(const Value& value);
244
245 //TODO: Documentation:
246 template <class ValueType>
247 bool set_value(const ValueType& value);
248
249
250 /** Same functionality as set_value() except that it uses a string representation
251 * of the value to set, which will be converted into a GValue first (using default data handler if
252 * @a dh is <tt>0</tt>).
253 *
254 * @note if @a value is <tt>0</tt> or is the "<tt>0</tt>" string, then @a holder's value is set to <tt>0</tt>.
255 * @note if @a holder can't accept the @a value value, then this method returns <tt>false</tt>, and @a holder will be left
256 * in an invalid state.
257 *
258 * @param dh A Gda::DataHandler to use, or <tt>0</tt>.
259 * @param value A value to set the holder to, as a string.
260 * @return <tt>true</tt> if value has been set.
261 */
262 bool set_value_str(const Glib::RefPtr<DataHandler>& dh, const Glib::ustring& value);
263
264 /** Sets the value within the holder. If @a holder is an alias for another
265 * holder, then the value is also set for that other holder.
266 *
267 * On success, the action of any call to force_invalid() is cancelled
268 * as soon as this method is called (even if @a holder's value does not actually change).
269 *
270 * If the value is not different from the one already contained within @a holder,
271 * then @a holder is not changed and no signal is emitted.
272 *
273 * @note if @a holder can't accept the @a value value, then this method returns <tt>false</tt>, and @a holder will be left
274 * in an invalid state.
275 *
276 * @note before the change is accepted by @a holder, the "validate-change" signal will be emitted (the value
277 * of which can prevent the change from happening) which can be connected to to have a greater control
278 * of which values @a holder can have, or implement some business rules.
279 *
280 * @note if user previously set this holder with take_static_value() the GValue
281 * stored internally will be forgiven and replaced by the @a value. User should then
282 * take care of the 'old' static GValue.
283 *
284 * @param value A value to set the holder to.
285 * @return <tt>true</tt> if value has been set.
286 */
287 bool take_value(const Value& value);
288
289 /** Sets the const value within the holder. If @a holder is an alias for another
290 * holder, then the value is also set for that other holder.
291 *
292 * The value will not be freed, and user should take care of it, either for its
293 * freeing or for its correct value at the moment of query.
294 *
295 * If the value is not different from the one already contained within @a holder,
296 * then @a holder is not changed and no signal is emitted.
297 *
298 * @note if @a holder can't accept the @a value value, then this method returns <tt>0</tt>, and @a holder will be left
299 * in an invalid state.
300 *
301 * @note before the change is accepted by @a holder, the "validate-change" signal will be emitted (the value
302 * of which can prevent the change from happening) which can be connected to to have a greater control
303 * of which values @a holder can have, or implement some business rules.
304 *
305 * @param value A const value to set the holder to.
306 * @param value_changed A boolean set with <tt>true</tt> if the value changes, <tt>false</tt> elsewhere.
307 * @return <tt>0</tt> if an error occurred or if the previous GValue was <tt>0</tt> itself. It returns
308 * the static GValue user set previously, so that he can free it.
309 */
310 Value take_static_value(const Value& value, bool& value_changed);
311
312 void set_attribute(const Glib::ustring& attribute, const Value& value);
313
314 //TODO: gda_holder_set_attribute() has stupid memory management: _WRAP_METHOD(void set_attribute(const Glib::ustring& attribute, const Value& value), gda_holder_set_attribute)
315
316
317 /** Get the value associated to a named attribute.
318 *
319 * Attributes can have any name, but Libgda proposes some default names, see this section.
320 *
321 * @param attribute Attribute name as a string.
322 * @return A read-only Value, or <tt>0</tt> if not attribute named @a attribute has been set for @a holder.
323 */
324 Value get_attribute(const Glib::ustring& attribute) const;
325
326
327 /** Get the default value held into the holder. WARNING: the default value does not need to be of
328 * the same type as the one required by @a holder.
329 *
330 * @return The default value.
331 */
332 Value get_default_value() const;
333
334 /** Sets the default value within the holder. If @a value is <tt>0</tt> then @a holder won't have a
335 * default value anymore. To set a default value to <tt>0</tt>, then pass a Value created using
336 * gda_value_new_null().
337 *
338 * NOTE: the default value does not need to be of the same type as the one required by @a holder.
339 *
340 * @param value A value to set the holder's default value, or <tt>0</tt>.
341 */
342 void set_default_value(const Value& value);
343
344 /** Set @a holder's value to its default value.
345 *
346 * @return <tt>true</tt> if @a holder has got a default value.
347 */
348 bool set_value_to_default();
349
350 /** Tells if @a holder's current value is the default one.
351 *
352 * @return <tt>true</tt> if @a holder @a holder's current value is the default one.
353 */
354 bool value_is_default() const;
355
356
357 /** Forces a holder to be invalid; to set it valid again, a new value must be assigned
358 * to it using set_value() or take_value().
359 *
360 * @a holder's value is set to <tt>0</tt>.
361 */
362 void force_invalid();
363
364 //TODO: gda_holder_force_invalid_e() is a way to _set_ an error, not throw an error.
365 //The error is later returned by gda_holder_is_valid_e(). We can probably ignore it.
366
367
368 /** Get the validity of @a holder (that is, of the value held by @a holder)
369 *
370 * @return <tt>true</tt> if @a holder's value can safely be used.
371 */
372 bool is_valid() const;
373
374 //Ignore gda_holder_is_valid_e() because throwing an exception would be odd for an is_*() method.
375
376
377 /** Sets if the holder can have a <tt>0</tt> value. If @a not_null is <tt>true</tt>, then that won't be allowed
378 *
379 * @param not_null <tt>true</tt> if @a holder should not accept <tt>0</tt> values.
380 */
381 void set_not_null(bool not_null = true);
382
383 /** Get wether the holder can be <tt>0</tt> or not
384 *
385 * @return <tt>true</tt> if the holder cannot be <tt>0</tt>.
386 */
387 bool get_not_null() const;
388
389
390 /** If set_source_model() has been used to provide a hint that @a holder's value
391 * should be among the values contained in a column of a data model, then this method
392 * returns which data model, and if @a col is not <tt>0</tt>, then it is set to the restricting column
393 * as well.
394 *
395 * Otherwise, this method returns <tt>0</tt>, and if @a col is not <tt>0</tt>, then it is set to 0.
396 *
397 * @param col A place to store the column in the model sourcing the holder, or <tt>0</tt>.
398 * @return A pointer to a Gda::DataModel, or <tt>0</tt>.
399 */
400 Glib::RefPtr<DataModel> get_source_model(int& col);
401
402 /** If set_source_model() has been used to provide a hint that @a holder's value
403 * should be among the values contained in a column of a data model, then this method
404 * returns which data model, and if @a col is not <tt>0</tt>, then it is set to the restricting column
405 * as well.
406 *
407 * Otherwise, this method returns <tt>0</tt>, and if @a col is not <tt>0</tt>, then it is set to 0.
408 *
409 * @param col A place to store the column in the model sourcing the holder, or <tt>0</tt>.
410 * @return A pointer to a Gda::DataModel, or <tt>0</tt>.
411 */
412 Glib::RefPtr<const DataModel> get_source_model(int& col) const;
413
414
415 /** Sets an hint that @a holder's values should be restricted among the values
416 * contained in the @a col column of the @a model data model. Note that this is just a hint,
417 * meaning this policy is not enforced by @a holder's implementation.
418 *
419 * @param model A Gda::DataModel object or <tt>0</tt>.
420 * @param col The reference column in @a model.
421 * @return <tt>true</tt> if no error occurred.
422 */
423 bool set_source_model(const Glib::RefPtr<DataModel>& model, int col);
424
425
426 /** Sets @a holder to change when @a bind_to changes (and does not make @a bind_to change when @a holder changes).
427 * For the operation to succeed, the GType of @a holder and @a bind_to must be the same, with the exception that
428 * any of them can have a Gda::TYPE_NULL type (in this situation, the GType of the two Gda::Holder objects
429 * involved is set to match the other when any of them sets its type to something different than GDA_TYPE_NULL).
430 *
431 * If @a bind_to is <tt>0</tt>, then @a holder will not be bound anymore.
432 *
433 * @param bind_to A Gda::Holder or <tt>0</tt>.
434 * @return <tt>true</tt> if no error occurred.
435 */
436 void set_bind(const Glib::RefPtr<Holder>& bind_to);
437
438 /** Get the holder which makes @a holder change its value when the holder's value is changed.
439 *
440 * @return The Gda::Holder or <tt>0</tt>.
441 */
442 Glib::RefPtr<Holder> get_bind();
443
444 /** Get the holder which makes @a holder change its value when the holder's value is changed.
445 *
446 * @return The Gda::Holder or <tt>0</tt>.
447 */
448 Glib::RefPtr<const Holder> get_bind() const;
449
450 /** Holder's description.
451 *
452 * @return A PropertyProxy that allows you to get or set the value of the property,
453 * or receive notification when the value of the property changes.
454 */
455 Glib::PropertyProxy< Glib::ustring > property_description() ;
456
457 /** Holder's description.
458 *
459 * @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
460 * or receive notification when the value of the property changes.
461 */
462 Glib::PropertyProxy_ReadOnly< Glib::ustring > property_description() const;
463
464 /** Make value holder follow other GdaHolder's changes and the other way around.
465 *
466 * @return A PropertyProxy that allows you to get or set the value of the property,
467 * or receive notification when the value of the property changes.
468 */
469 Glib::PropertyProxy< Glib::RefPtr<Holder> > property_full_bind() ;
470
471 /** Make value holder follow other GdaHolder's changes and the other way around.
472 *
473 * @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
474 * or receive notification when the value of the property changes.
475 */
476 Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Holder> > property_full_bind() const;
477
478 /** Holder's GType.
479 *
480 * @return A PropertyProxy that allows you to get or set the value of the property,
481 * or receive notification when the value of the property changes.
482 */
483 Glib::PropertyProxy< gulong > property_g_type() ;
484
485 /** Holder's GType.
486 *
487 * @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
488 * or receive notification when the value of the property changes.
489 */
490 Glib::PropertyProxy_ReadOnly< gulong > property_g_type() const;
491
492 /** Holder's ID.
493 *
494 * @return A PropertyProxy that allows you to get or set the value of the property,
495 * or receive notification when the value of the property changes.
496 */
497 Glib::PropertyProxy< Glib::ustring > property_id() ;
498
499 /** Holder's ID.
500 *
501 * @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
502 * or receive notification when the value of the property changes.
503 */
504 Glib::PropertyProxy_ReadOnly< Glib::ustring > property_id() const;
505
506 /** Holder's name.
507 *
508 * @return A PropertyProxy that allows you to get or set the value of the property,
509 * or receive notification when the value of the property changes.
510 */
511 Glib::PropertyProxy< Glib::ustring > property_name() ;
512
513 /** Holder's name.
514 *
515 * @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
516 * or receive notification when the value of the property changes.
517 */
518 Glib::PropertyProxy_ReadOnly< Glib::ustring > property_name() const;
519
520 /** Can the value holder be NULL?.
521 *
522 * @return A PropertyProxy that allows you to get or set the value of the property,
523 * or receive notification when the value of the property changes.
524 */
525 Glib::PropertyProxy< bool > property_not_null() ;
526
527 /** Can the value holder be NULL?.
528 *
529 * @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
530 * or receive notification when the value of the property changes.
531 */
532 Glib::PropertyProxy_ReadOnly< bool > property_not_null() const;
533
534 /** Make value holder follow other GdaHolder's changes.
535 *
536 * @return A PropertyProxy that allows you to get or set the value of the property,
537 * or receive notification when the value of the property changes.
538 */
539 Glib::PropertyProxy< Glib::RefPtr<Holder> > property_simple_bind() ;
540
541 /** Make value holder follow other GdaHolder's changes.
542 *
543 * @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
544 * or receive notification when the value of the property changes.
545 */
546 Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Holder> > property_simple_bind() const;
547
548 /** Column number to use in coordination with the source-model property.
549 *
550 * @return A PropertyProxy that allows you to get or set the value of the property,
551 * or receive notification when the value of the property changes.
552 */
553 Glib::PropertyProxy< int > property_source_column() ;
554
555 /** Column number to use in coordination with the source-model property.
556 *
557 * @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
558 * or receive notification when the value of the property changes.
559 */
560 Glib::PropertyProxy_ReadOnly< int > property_source_column() const;
561
562 /** Data model among which the holder's value should be.
563 *
564 * @return A PropertyProxy that allows you to get or set the value of the property,
565 * or receive notification when the value of the property changes.
566 */
567 Glib::PropertyProxy< Glib::RefPtr<DataModel> > property_source_model() ;
568
569 /** Data model among which the holder's value should be.
570 *
571 * @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
572 * or receive notification when the value of the property changes.
573 */
574 Glib::PropertyProxy_ReadOnly< Glib::RefPtr<DataModel> > property_source_model() const;
575
576
577 /**
578 * @par Slot Prototype:
579 * <tt>void on_my_%changed()</tt>
580 *
581 */
582
583 Glib::SignalProxy0< void > signal_changed();
584
585
586 /**
587 * @par Slot Prototype:
588 * <tt>void on_my_%source_changed()</tt>
589 *
590 */
591
592 Glib::SignalProxy0< void > signal_source_changed();
593
594
595 /**
596 * @par Slot Prototype:
597 * <tt>Glib::Error on_my_%validate_change(const Value& value)</tt>
598 *
599 */
600
601 Glib::SignalProxy1< Glib::Error,const Value& > signal_validate_change();
602
603
604 /**
605 * @par Slot Prototype:
606 * <tt>void on_my_%attribute_changed(const Glib::ustring& attr_name, const Value& value)</tt>
607 *
608 */
609
610 Glib::SignalProxy2< void,const Glib::ustring&,const Value& > signal_attribute_changed();
611
612
613 public:
614
615 public:
616 //C++ methods used to invoke GTK+ virtual functions:
617
618 protected:
619 //GTK+ Virtual Functions (override these to change behaviour):
620
621 //Default Signal Handlers::
622 /// This is a default handler for the signal signal_changed().
623 virtual void on_changed();
624 /// This is a default handler for the signal signal_source_changed().
625 virtual void on_source_changed();
626
627
628 };
629
630 #ifndef DOXYGEN_SHOULD_SKIP_THIS
631 template <class ValueType> inline
set_value(const ValueType & value)632 bool Holder::set_value(const ValueType& value)
633 {
634 Gnome::Gda::Value gdavalue(value);
635 return this->set_value_as_value(gdavalue);
636 }
637 #endif //DOXYGEN_SHOULD_SKIP_THIS
638
639 } // namespace Gda
640 } // namespace Gnome
641
642
643 namespace Glib
644 {
645 /** A Glib::wrap() method for this object.
646 *
647 * @param object The C instance.
648 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
649 * @result A C++ instance that wraps this C instance.
650 *
651 * @relates Gnome::Gda::Holder
652 */
653 Glib::RefPtr<Gnome::Gda::Holder> wrap(GdaHolder* object, bool take_copy = false);
654 }
655
656
657 #endif /* _LIBGDAMM_HOLDER_H */
658
659