libgda-5.0-doc 5.2.2-1 / usr / share / gtk-doc / html / libgda-5.0 / gda-data-model-writing.html

This file is indexed.

/usr/share/gtk-doc/html/libgda-5.0/gda-data-model-writing.html is in libgda-5.0-doc 5.2.2-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>GNOME Data Access 5 manual: Implementing your own data model</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="GNOME Data Access 5 manual">
<link rel="up" href="data_models.html" title="Data handling">
<link rel="prev" href="libgda-5.0-GdaDataComparator.html" title="GdaDataComparator">
<link rel="next" href="trees.html" title="Trees">
<meta name="generator" content="GTK-Doc V1.20 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="data_models.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="libgda-5.0-GdaDataComparator.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="trees.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="gda-data-model-writing"></a>Implementing your own data model</h2></div></div></div>
<p>
    You may need at some point to implement your own data model because the implementations in
    <span class="application">Libgda</span> don't suit your needs. This section is dedicated to explaining to you how this can be done.
  </p>
<p>
    Implementing a new <a class="link" href="GdaDataModel.html" title="GdaDataModel">GdaDataModel</a> is simply a matter of
    creating a new GObject which implements the <a class="link" href="GdaDataModel.html" title="GdaDataModel">GdaDataModel</a>
    interface, which is described below. Thos new class needs to inherit GObject, but needs not
    be direct descendant of it. The way to subclass an object using GLib
    is not covered in this documentation, for this matter reref to
    GObject's documentation, or
    <a class="ulink" href="http://developer.gnome.org/gobject/stable/howto-gobject.html" target="_top">online</a>.
  </p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="gda-data-model-writing-virtual-methods"></a>Virtual methods</h3></div></div></div>
<p>
      The interface's methods which can and/or need to be implemented are defined below.
    </p>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_n_rows"></a>i_get_n_rows() - optional</h4></div></div></div>
<p>This method, if implemented, returns the total number of rows in the data model, or -1 if
      unknown. If it's not implemented, then it is assumed that -1 is returned in all cases.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_n_columns"></a>i_get_n_columns() - required</h4></div></div></div>
<p>This method, returns the total number of columns in the data model, or -1 if unknown.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_describe_column"></a>i_describe_column() - required</h4></div></div></div>
<p>This method describes a column; it returns (without any ownership to the caller) a
      <a class="link" href="GdaColumn.html" title="GdaDataModel columns">GdaColumn</a> for each existing column, or NULL otherwise.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_access_flags"></a>i_get_access_flags() - required</h4></div></div></div>
<p>This method defines how the data model may be accessed (randomly, only using a cursor, ...)</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_value_at"></a>i_get_value_at() - required for random access</h4></div></div></div>
<p>This method is used to access the contents of a data model, specifically
      a <a href="/usr/share/gtk-doc/html/gobject/gobject-Generic-values.html#GValue">GValue</a> is returned for each (column,row) position.
      It must return NULL if the data model experienced an error for the specific (column,row)
      position. See <a class="link" href="GdaDataModel.html#gda-data-model-get-value-at" title="gda_data_model_get_value_at ()">gda_data_model_get_value_at()</a>
      for more information about the lifetime of the returned GValue.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_attributes_at"></a>i_get_attributes_at() - optional</h4></div></div></div>
<p>This method returns, for a (column,row) position in the data model, the attributes
      of the adressed "cell".</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_create_iter"></a>i_create_iter() - optional</h4></div></div></div>
<p>This method can be implemented to create specific
      <a class="link" href="GdaDataModelIter.html" title="GdaDataModelIter">GdaDataModelIter</a> or to customize them.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_iter_at_row"></a>i_iter_at_row() - optional</h4></div></div></div>
<p>This method can be implemented if a specific implementation allows an iterator
      to be moved quickly to a specific row (faster than iterating from row to row to the
      requested row).</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_iter_next"></a>i_iter_next() - required for cursor based access</h4></div></div></div>
<p>This method is called to move an iterator to the next row; it's not necessary to
      implement it if the data models supports random access.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_iter_prev"></a>i_iter_prev() - optional for cursor based access</h4></div></div></div>
<p>This method is called to move an iterator to the previous row. It is only necessary to
      implement it if the data model does not support random access and supports moving the
      cursor backward.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_set_value_at"></a>i_set_value_at() - optional</h4></div></div></div>
<p>This method needs to be defined if the data model allows each value in a (column,row) position
      to be modified individually.
      </p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_iter_set_value"></a>i_iter_set_value() - optional</h4></div></div></div>
<p>This method can be defined if a specific treatment is required when a modification made
      to a <a class="link" href="GdaDataModelIter.html" title="GdaDataModelIter">GdaDataModelIter</a> is propagated to the data model.
      It should seldom, if ever, be necessary to implement it.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_set_values"></a>i_set_values() - optional</h4></div></div></div>
<p>This method needs to be defined if the data model allows modifications to be made for
      one complete row at a time. See the
      <a class="link" href="GdaDataModel.html#gda-data-model-set-values" title="gda_data_model_set_values ()">gda_data_model_set_values()</a> method for
      more information about the arguments</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_append_values"></a>i_append_values() - optional</h4></div></div></div>
<p>This method can be implemented if the data model needs to support adding a row and defining the
      values to be added in the same operation.
      See <a class="link" href="GdaDataModel.html#gda-data-model-append-values" title="gda_data_model_append_values ()">gda_data_model_append_values()</a> for
      more information.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_append_row"></a>i_append_row() - optional</h4></div></div></div>
<p>This method needs to be defined if the data model needs to support adding an empty row (i.e.
      without any value specified in the new row).</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_remove_row"></a>i_remove_row() - optional</h4></div></div></div>
<p>This method should be implemented if the data model needs to support row removal.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_find_row"></a>i_find_row() - optional</h4></div></div></div>
<p>This method can be implemented if the data model implements an indexing scheme which
      allows it to find rows from values quickly than by analysing each row after another to
      find the requested values.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_set_notify"></a>i_set_notify() - optional</h4></div></div></div>
<p>This method should be implemented if the data model needs to honor the
      <a class="link" href="GdaDataModel.html#gda-data-model-freeze" title="gda_data_model_freeze ()">gda_data_model_freeze()</a> and
      <a class="link" href="GdaDataModel.html#gda-data-model-thaw" title="gda_data_model_thaw ()">gda_data_model_thaw()</a> methods. If
      this method is not implemented, then these two methods will have no effect.
      </p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_notify"></a>i_get_notify() - optional</h4></div></div></div>
<p>This method should be implemented if the data model needs to honor the
      <a class="link" href="GdaDataModel.html#gda-data-model-freeze" title="gda_data_model_freeze ()">gda_data_model_freeze()</a> and
      <a class="link" href="GdaDataModel.html#gda-data-model-thaw" title="gda_data_model_thaw ()">gda_data_model_thaw()</a> methods. If
      this method is not implemented, then these two methods will have no effect.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_send_hint"></a>i_send_hint() - optional</h4></div></div></div>
<p>This method should be implemented if the data model needs to be able to treat
      hints, see <a class="link" href="GdaDataModel.html#gda-data-model-send-hint" title="gda_data_model_send_hint ()">gda_data_model_send_hint()</a> for
      more information</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_exceptions"></a>i_get_exceptions() - optional</h4></div></div></div>
<p>This method needs to be implemented if the data model keeps exceptions about the errors
      it has encountered and may "export" these exceptions using the
      <a class="link" href="GdaDataModel.html#gda-data-model-get-exceptions" title="gda_data_model_get_exceptions ()">gda_data_model_get_exceptions()</a> method.</p>
</div>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="gda-data-model-writing-signalling"></a>Signalling changes</h3></div></div></div>
<p>
      When the data model changes, it needs to signal its changes. However, only the changes from
      the initial state need to be notified, in situations such as:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>a row which has already been accessed is modified or removed</p></li>
<li class="listitem"><p>the total number of rows changes, and that number has already been obtained and
	was known (i.e. different than -1)</p></li>
</ul></div>
<p>
    </p>
<p>
      To signal changes, one of the following methods has to be used:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><a class="link" href="GdaDataModel.html#gda-data-model-row-inserted" title="gda_data_model_row_inserted ()">gda_data_model_row_inserted()</a>: to be called after a row has been inserted</p></li>
<li class="listitem"><p><a class="link" href="GdaDataModel.html#gda-data-model-row-updated" title="gda_data_model_row_updated ()">gda_data_model_row_updated()</a>: to be called after a row has been updated</p></li>
<li class="listitem"><p><a class="link" href="GdaDataModel.html#gda-data-model-row-removed" title="gda_data_model_row_removed ()">gda_data_model_row_removed()</a>: to be called after a row has been removed</p></li>
<li class="listitem"><p><a class="link" href="GdaDataModel.html#gda-data-model-reset" title="gda_data_model_reset ()">gda_data_model_reset()</a>: to be called
	when the data model has changed in a way it's not possible or desirable to signal all the changes
	using any combination of the above methods (for example when the whole contents has changed, or
	when the number and/or types of columns has changed)</p></li>
</ul></div>
<p>
    </p>
<p>
      Moreover, when the data model's access flags have changed, the implementation should signal it by
      emitting the <a class="link" href="GdaDataModel.html#GdaDataModel-access-changed" title="The “access-changed” signal">"access-changed"</a> signal.
    </p>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.20</div>
</body>
</html>

APT Browse - Built by Thomas Orozco.