1 /* 2 * Copyright (C) 2006 - 2007 Murray Cumming <murrayc@murrayc.com> 3 * Copyright (C) 2006 - 2012 Vivien Malerba <malerba@gnome-db.org> 4 * Copyright (C) 2012 Daniel Espinosa <despinosa@src.gnome.org> 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library; if not, write to the 18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 19 * Boston, MA 02110-1301, USA. 20 */ 21 22 23 #ifndef __GDA_DATA_PROXY_H_ 24 #define __GDA_DATA_PROXY_H_ 25 26 #include "gda-decl.h" 27 #include <glib-object.h> 28 #include <libgda/gda-value.h> 29 #include <libgda/gda-enums.h> add(std::unique_ptr<Pass> pass)30 31 32 G_BEGIN_DECLS 33 34 #define GDA_TYPE_DATA_PROXY (gda_data_proxy_get_type()) 35 #define GDA_DATA_PROXY(obj) G_TYPE_CHECK_INSTANCE_CAST (obj, gda_data_proxy_get_type(), GdaDataProxy) 36 #define GDA_DATA_PROXY_CLASS(klass) G_TYPE_CHECK_CLASS_CAST (klass, gda_data_proxy_get_type (), GdaDataProxyClass) 37 #define GDA_IS_DATA_PROXY(obj) G_TYPE_CHECK_INSTANCE_TYPE (obj, gda_data_proxy_get_type ()) 38 39 /* error reporting */ 40 extern GQuark gda_data_proxy_error_quark (void); 41 #define GDA_DATA_PROXY_ERROR gda_data_proxy_error_quark () 42 43 typedef enum { 44 GDA_DATA_PROXY_COMMIT_ERROR, 45 GDA_DATA_PROXY_COMMIT_CANCELLED, 46 GDA_DATA_PROXY_READ_ONLY_VALUE, 47 GDA_DATA_PROXY_READ_ONLY_ROW, 48 GDA_DATA_PROXY_FILTER_ERROR 49 } GdaDataProxyError; 50 51 /* struct for the object's data */ 52 struct _GdaDataProxy 53 { 54 GObject object; 55 GdaDataProxyPrivate *priv; 56 }; 57 58 59 /* struct for the object's class */ 60 struct _GdaDataProxyClass 61 { 62 GObjectClass parent_class; 63 64 void (* row_delete_changed) (GdaDataProxy *proxy, gint row, gboolean to_be_deleted); 65 66 void (* sample_size_changed) (GdaDataProxy *proxy, gint sample_size); 67 void (* sample_changed) (GdaDataProxy *proxy, gint sample_start, gint sample_end); 68 69 GError *(* validate_row_changes) (GdaDataProxy *proxy, gint row, gint proxied_row); 70 void (* row_changes_applied) (GdaDataProxy *proxy, gint row, gint proxied_row); 71 72 void (* filter_changed) (GdaDataProxy *proxy); 73 74 /*< private >*/ 75 /* Padding for future expansion */ 76 void (*_gda_reserved1) (void); 77 void (*_gda_reserved2) (void); 78 void (*_gda_reserved3) (void); 79 void (*_gda_reserved4) (void); 80 }; 81 82 /** 83 * SECTION:gda-data-proxy 84 * @short_description: Proxy to hold modifications for any #GdaDataModel, providing the #GdaDataModel interface itself 85 * @title: GdaDataProxy 86 * @stability: Stable 87 * @see_also: #GdaDataModel 88 * 89 * This object stores modifications to be made to a #GdaDataModel object which is proxied until the modifications are actually 90 * written to the #GdaDataModel, it can also filter the proxied data model to show only a subset (a defined number of continuous 91 * rows or by a filter to apply). 92 * 93 * Specifically, for a proxied data model having <varname>nb_cols</varname> columns and <varname>nb_rows</varname> rows, 94 * the #GdaDataProxy object has the following attributes: 95 * <itemizedlist> 96 * <listitem> 97 * <para><varname>2 * nb_cols</varname> columns: 98 * <itemizedlist> 99 * <listitem><para>the first (>= 0) <varname>nb_cols</varname> columns are the current values stored in the 100 * proxy (which correspond to the values of the proxied data model if the considered row has not been 101 * changed). The associated values are writable.</para></listitem> 102 * <listitem><para>the last <varname>nb_cols</varname> columns are the values stored in the proxied data model, 103 * at column <varname>col - nb_cols</varname></para></listitem> 104 * </itemizedlist> 105 * </para> 106 * </listitem> 107 * <listitem><para>a variable number of rows depending on the following attributes: 108 * <itemizedlist> 109 * <listitem><para>if the proxy is configured to have an empty row as the first row</para></listitem> 110 * <listitem><para>if the proxy only displays parts of the proxied data model</para></listitem> 111 * <listitem><para>if new rows have been added to the proxy</para></listitem> 112 * </itemizedlist> 113 * </para></listitem> 114 * <listitem><para>Any #GdaDataModelIter iterator created will only make appear the colmuns as present in the proxied 115 * data model, not any of the other columns</para></listitem> 116 * </itemizedlist> 117 * This situation is illustrated in the following schema, where there is a direct mapping between the proxy's 118 * rows and the proxied data model's rows: 119 * <mediaobject> 120 * <imageobject role="html"> 121 * <imagedata fileref="data_proxy1.png" format="PNG" contentwidth="170mm"/> 122 * </imageobject> 123 * <textobject> 124 * <phrase>GdaDataProxy's values mapping regarding the proxied data model</phrase> 125 * </textobject> 126 * </mediaobject> 127 * 128 * Note that unless explicitly mentioned, the columns are read-only. 129 * 130 * The following figures illustrate row mappings between the data proxy and the proxied data model in 131 * several situations (which can be combined, but are shown alone for simplicity): 132 * <itemizedlist> 133 * <listitem><para>situation where rows 1 and 5 have been marked as deleted from the data proxy, using 134 * <link linkend="gda-data-proxy-delete">gda_data_proxy_delete()</link> method, the data 135 * proxy has 2 rows less than the proxied data model: 136 * <mediaobject> 137 * <imageobject role="html"> 138 * <imagedata fileref="data_proxy2.png" format="PNG" contentwidth="100mm"/> 139 * </imageobject> 140 * <textobject> 141 * <phrase>GdaDataProxy with 2 rows marked as deleted</phrase> 142 * </textobject> 143 * </mediaobject> 144 * </para></listitem> 145 * <listitem><para>situation where the data proxy only shows a sample of the proxied data model 146 * at any given time, using the 147 * <link linkend="gda-data-proxy-set-sample-size">gda_data_proxy_set_sample_size()</link> method 148 * (the sample here is 4 rows wide, and starts at row 3): 149 * <mediaobject> 150 * <imageobject role="html"> 151 * <imagedata fileref="data_proxy3.png" format="PNG" contentwidth="100mm"/> 152 * </imageobject> 153 * <textobject> 154 * <phrase>GdaDataProxy with a sample size of 4</phrase> 155 * </textobject> 156 * </mediaobject> 157 * </para></listitem> 158 * <listitem><para>situation where the data proxy shows a row of NULL values, using the 159 * <link linkend="GdaDataproxy-prepend-null-entry">"prepend-null-entry"</link> property: 160 * <mediaobject> 161 * <imageobject role="html"> 162 * <imagedata fileref="data_proxy4.png" format="PNG" contentwidth="100mm"/> 163 * </imageobject> 164 * <textobject> 165 * <phrase>GdaDataProxy with an extra row of NULL values</phrase> 166 * </textobject> 167 * </mediaobject> 168 * </para></listitem> 169 * <listitem><para>situation where a row has been added to the data proxy, using for example the 170 * <link linkend="gda-data-model-append-row">gda_data_model_append_row()</link> method: 171 * <mediaobject> 172 * <imageobject role="html"> 173 * <imagedata fileref="data_proxy5.png" format="PNG" contentwidth="100mm"/> 174 * </imageobject> 175 * <textobject> 176 * <phrase>GdaDataProxy where a row has been added</phrase> 177 * </textobject> 178 * </mediaobject> 179 * </para></listitem> 180 * </itemizedlist> 181 * 182 * The #GdaDataProxy objects are thread safe, which means any proxy object can be used from 183 * any thread at the same time as they implement their own locking mechanisms. 184 */ 185 186 GType gda_data_proxy_get_type (void) G_GNUC_CONST; 187 GObject *gda_data_proxy_new (GdaDataModel *model); 188 GdaDataProxy *gda_data_proxy_new_with_data_model (GdaDataModel *model); 189 190 GdaDataModel *gda_data_proxy_get_proxied_model (GdaDataProxy *proxy); 191 gint gda_data_proxy_get_proxied_model_n_cols (GdaDataProxy *proxy); 192 gint gda_data_proxy_get_proxied_model_n_rows (GdaDataProxy *proxy); 193 gboolean gda_data_proxy_is_read_only (GdaDataProxy *proxy); 194 GSList *gda_data_proxy_get_values (GdaDataProxy *proxy, gint proxy_row, 195 gint *cols_index, gint n_cols); 196 GdaValueAttribute gda_data_proxy_get_value_attributes (GdaDataProxy *proxy, gint proxy_row, gint col); 197 void gda_data_proxy_alter_value_attributes (GdaDataProxy *proxy, gint proxy_row, gint col, GdaValueAttribute alter_flags); 198 gint gda_data_proxy_get_proxied_model_row (GdaDataProxy *proxy, gint proxy_row); 199 200 void gda_data_proxy_delete (GdaDataProxy *proxy, gint proxy_row); 201 void gda_data_proxy_undelete (GdaDataProxy *proxy, gint proxy_row); 202 gboolean gda_data_proxy_row_is_deleted (GdaDataProxy *proxy, gint proxy_row); 203 gboolean gda_data_proxy_row_is_inserted (GdaDataProxy *proxy, gint proxy_row); 204 205 gboolean gda_data_proxy_row_has_changed (GdaDataProxy *proxy, gint proxy_row); 206 gboolean gda_data_proxy_has_changed (GdaDataProxy *proxy); 207 gint gda_data_proxy_get_n_new_rows (GdaDataProxy *proxy); 208 gint gda_data_proxy_get_n_modified_rows (GdaDataProxy *proxy); 209 210 gboolean gda_data_proxy_apply_row_changes (GdaDataProxy *proxy, gint proxy_row, GError **error); 211 void gda_data_proxy_cancel_row_changes (GdaDataProxy *proxy, gint proxy_row, gint col); 212 213 gboolean gda_data_proxy_apply_all_changes (GdaDataProxy *proxy, GError **error); 214 gboolean gda_data_proxy_cancel_all_changes (GdaDataProxy *proxy); 215 216 void gda_data_proxy_set_sample_size (GdaDataProxy *proxy, gint sample_size); 217 gint gda_data_proxy_get_sample_size (GdaDataProxy *proxy); 218 void gda_data_proxy_set_sample_start (GdaDataProxy *proxy, gint sample_start); 219 gint gda_data_proxy_get_sample_start (GdaDataProxy *proxy); 220 gint gda_data_proxy_get_sample_end (GdaDataProxy *proxy); 221 222 gboolean gda_data_proxy_set_filter_expr (GdaDataProxy *proxy, const gchar *filter_expr, GError **error); 223 const gchar *gda_data_proxy_get_filter_expr (GdaDataProxy *proxy); 224 gboolean gda_data_proxy_set_ordering_column (GdaDataProxy *proxy, gint col, GError **error); 225 gint gda_data_proxy_get_filtered_n_rows (GdaDataProxy *proxy); 226 227 G_END_DECLS 228 229 #endif 230