1 /* 2 * Copyright (C) 2009 - 2012 Vivien Malerba <malerba@gnome-db.org> 3 * Copyright (C) 2011 Murray Cumming <murrayc@murrayc.com> 4 * 5 * This library is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU Lesser General Public 7 * License as published by the Free Software Foundation; either 8 * version 2 of the License, or (at your option) any later version. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public 16 * License along with this library; if not, write to the 17 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 18 * Boston, MA 02110-1301, USA. 19 */ 20 21 #ifndef __GDAUI_BASIC_FORM__ 22 #define __GDAUI_BASIC_FORM__ 23 24 #include <gtk/gtk.h> 25 #include <libgda/libgda.h> 26 27 G_BEGIN_DECLS 28 29 #define GDAUI_TYPE_BASIC_FORM (gdaui_basic_form_get_type()) 30 #define GDAUI_BASIC_FORM(obj) G_TYPE_CHECK_INSTANCE_CAST (obj, gdaui_basic_form_get_type(), GdauiBasicForm) 31 #define GDAUI_BASIC_FORM_CLASS(klass) G_TYPE_CHECK_CLASS_CAST (klass, gdaui_basic_form_get_type (), GdauiBasicFormClass) 32 #define GDAUI_IS_BASIC_FORM(obj) G_TYPE_CHECK_INSTANCE_TYPE (obj, gdaui_basic_form_get_type ()) 33 #define GDAUI_IS_BASIC_FORM_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), GDAUI_TYPE_BASIC_FORM)) 34 #define GDAUI_BASIC_FORM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GDAUI_TYPE_BASIC_FORM, GdauiBasicFormClass)) 35 36 37 typedef struct _GdauiBasicForm GdauiBasicForm; 38 typedef struct _GdauiBasicFormClass GdauiBasicFormClass; 39 typedef struct _GdauiBasicFormPriv GdauiBasicFormPriv; 40 41 /* struct for the object's data */ 42 struct _GdauiBasicForm 43 { 44 GtkBox object; 45 46 GdauiBasicFormPriv *priv; 47 }; 48 49 /* struct for the object's class */ 50 struct _GdauiBasicFormClass 51 { 52 GtkBoxClass parent_class; 53 54 /* signals */ 55 void (*holder_changed) (GdauiBasicForm *form, GdaHolder *holder, gboolean is_user_action); 56 void (*activated) (GdauiBasicForm *form); 57 void (*layout_changed) (GdauiBasicForm *form); 58 }; 59 60 /** 61 * SECTION:gdaui-basic-form 62 * @short_description: Form widget mapping the values contained in a #GdaSet 63 * @title: GdauiBasicForm 64 * @stability: Stable 65 * @Image: vi-basic-form.png 66 * @see_also: 67 * 68 * The #GdauiBasicForm widget is a form containing an entry for each #GdaHolder object 69 * contained in a #GdaSet (specified when the form is created). A typical usage is when the 70 * user is requested to enter a value which will be used in a statement (without any error checking for clarity): 71 * <programlisting> 72 * GdaStatement *stmt; 73 * GdaSet *params; 74 * stmt = gda_sql_parser_parse_string (parser, "SELECT * FROM customers where name LIKE ##name::string", NULL, NULL); 75 * gda_statement_get_parameters (stmt, &params, NULL); 76 * 77 * GtkWidget *form; 78 * gint result; 79 * form = gdaui_basic_form_new_in_dialog (params, NULL, "Customer search", "Enter Customer search expression"); 80 * result = gtk_dialog_run (GTK_DIALOG (form)); 81 * gtk_widget_destroy (form); 82 * if (result == GTK_RESPONSE_ACCEPT) { 83 * // execute statement 84 * GdaDataModel *model; 85 * model = gda_connection_statement_execute_select (cnc, stmt, params, NULL); 86 * [...] 87 * } 88 * g_object_unref (params); 89 * g_object_unref (stmt); 90 * </programlisting> 91 * 92 * The default layout within a #GdauiBasicForm is a vertical column: all the data entry widgets are aligned 93 * in a single column. This behaviour can be changed using the gdaui_basic_form_set_layout_from_file() method or 94 * setting the <link linkend="GdauiBasicForm--xml-layout">xml-layout</link> property. 95 * 96 * <anchor id="GdauiBasicFormXMLLayout"/> 97 * The #GdauiBasicForm class parses textual descriptions of XML layout which 98 * which can be described by the following DTD. 99 * 100 * <programlisting><![CDATA[ 101 * <!ELEMENT gdaui_layouts (gdaui_form | gdaui_grid)> 102 * 103 * <!ELEMENT gdaui_form (gdaui_section | gdaui_column | gdaui_notebook)*> 104 * <!ATTLIST gdaui_form 105 * name CDATA #REQUIRED 106 * container (columns|rows|hpaned|vpaned) #IMPLIED> 107 * 108 * <!ELEMENT gdaui_section (gdaui_section | gdaui_column | gdaui_notebook)*> 109 * <!ATTLIST gdaui_section 110 * title CDATA #IMPLIED > 111 * 112 * <!ELEMENT gdaui_notebook (gdaui_section | gdaui_column | gdaui_notebook)*> 113 * 114 * <!ELEMENT gdaui_column (gdaui_entry | gdaui_placeholder)*> 115 * 116 * <!ELEMENT gdaui_entry EMPTY> 117 * <!ATTLIST gdaui_entry 118 * name CDATA #REQUIRED 119 * editable (true|false) #IMPLIED 120 * label CDATA #IMPLIED 121 * plugin CDATA #IMPLIED> 122 * 123 * <!ELEMENT gdaui_placeholder EMPTY> 124 * <!ATTLIST gdaui_placeholder 125 * id CDATA #REQUIRED 126 * label CDATA #IMPLIED> 127 * ]]></programlisting> 128 * 129 * <example> 130 * <title>A GdauiBasicForm layout example</title> 131 * <programlisting><![CDATA[ 132 * <?xml version="1.0" encoding="UTF-8"?> 133 * <gdaui_layouts> 134 * <gdaui_form name="customers" container="hpaned"> 135 * <gdaui_section title="Summary"> 136 * <gdaui_column> 137 * <gdaui_entry name="id" editable="no"/> 138 * <gdaui_entry name="name"/> 139 * <gdaui_entry name="comments" plugin="text"/> 140 * <gdaui_entry name="total_orders" label="Total ordered" plugin="number:NB_DECIMALS=2;CURRENCY=€"/> 141 * </gdaui_column> 142 * </gdaui_section> 143 * <gdaui_section title="Photo"> 144 * <gdaui_column> 145 * <gdaui_entry name="photo" plugin="picture"/> 146 * </gdaui_column> 147 * </gdaui_section> 148 * </gdaui_form> 149 * </gdaui_layouts> 150 * ]]></programlisting> 151 * </example> 152 */ 153 154 GType gdaui_basic_form_get_type (void) G_GNUC_CONST; 155 GtkWidget *gdaui_basic_form_new (GdaSet *data_set); 156 GtkWidget *gdaui_basic_form_new_in_dialog (GdaSet *data_set, GtkWindow *parent, 157 const gchar *title, const gchar *header); 158 GdaSet *gdaui_basic_form_get_data_set (GdauiBasicForm *form); 159 gboolean gdaui_basic_form_is_valid (GdauiBasicForm *form); 160 gboolean gdaui_basic_form_has_changed (GdauiBasicForm *form); 161 void gdaui_basic_form_reset (GdauiBasicForm *form); 162 void gdaui_basic_form_set_as_reference (GdauiBasicForm *form); 163 164 void gdaui_basic_form_entry_set_visible (GdauiBasicForm *form, 165 GdaHolder *holder, gboolean show); 166 void gdaui_basic_form_entry_grab_focus (GdauiBasicForm *form, GdaHolder *holder); 167 void gdaui_basic_form_entry_set_editable (GdauiBasicForm *form, GdaHolder *holder, 168 gboolean editable); 169 void gdaui_basic_form_set_entries_to_default (GdauiBasicForm *form); 170 171 GtkWidget *gdaui_basic_form_get_entry_widget (GdauiBasicForm *form, GdaHolder *holder); 172 GtkWidget *gdaui_basic_form_get_label_widget (GdauiBasicForm *form, GdaHolder *holder); 173 174 void gdaui_basic_form_set_layout_from_file (GdauiBasicForm *form, const gchar *file_name, 175 const gchar *form_name); 176 GtkWidget *gdaui_basic_form_get_place_holder (GdauiBasicForm *form, const gchar *placeholder_id); 177 178 typedef enum { 179 GDAUI_BASIC_FORM_LABELS, 180 GDAUI_BASIC_FORM_ENTRIES 181 } GdauiBasicFormPart; 182 void gdaui_basic_form_add_to_size_group (GdauiBasicForm *form, GtkSizeGroup *size_group, 183 GdauiBasicFormPart part); 184 void gdaui_basic_form_remove_from_size_group (GdauiBasicForm *form, GtkSizeGroup *size_group, 185 GdauiBasicFormPart part); 186 187 void gdaui_basic_form_set_unknown_color (GdauiBasicForm *form, gdouble red, gdouble green, 188 gdouble blue, gdouble alpha); 189 190 G_END_DECLS 191 192 #endif 193