From 8992434c4f19c19d81478322fe38bed4864c39cc Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 5 Jun 2003 00:41:28 +0000 Subject: [PATCH] Add some questions. --- docs/reference/ChangeLog | 4 + docs/reference/gtk/question_index.sgml | 297 +++++++++++++++++++++++++ 2 files changed, 301 insertions(+) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 3acb314bb..e23620465 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2003-06-05 Matthias Clasen + + * gtk/question_index.sgml: Add a couple of questions. + 2003-06-01 Matthias Clasen * gtk/gtk-sections.txt: Add gtk_alignment_[gs]et_padding(). diff --git a/docs/reference/gtk/question_index.sgml b/docs/reference/gtk/question_index.sgml index 64fd1c64d..27d40fb93 100644 --- a/docs/reference/gtk/question_index.sgml +++ b/docs/reference/gtk/question_index.sgml @@ -197,6 +197,114 @@ can be defined as: + + + +How do I use non-ASCII characters in GTK+ programs ? + + + + + +GTK+ uses Unicode (more exactly +UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a + sequence of one to six bytes and has a number of nice + properties which make it a good choice for working with Unicode + text in C programs: + + +ASCII characters are encoded by their familiar ASCII codepoints. + + +ASCII characters never appear as part of any other character. + + +The zero byte doesn't occur as part of a character, so that UTF-8 strings can + be manipulated with the usual C library functions for + handling zero-terminated strings. + + +More information about Unicode and UTF-8 can be found in the +UTF-8 and Unicode FAQ for Unix/Linux. +GLib provides functions for converting strings between UTF-8 and other + encodings, see +g_locale_to_utf8() and g_convert(). + + +Text coming from external sources (e.g. files or user input), has to be + converted to UTF-8 before being handed over to GTK+. The + following example writes the content of a IS0-8859-1 encoded text + file to stdout: + +gchar *text, *utf8_text; +gsize length; +GError *error = NULL; + +if (g_file_get_contents (filename, &text, &length, NULL)) + { + utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1", + NULL, NULL, &error); + if (error != NULL) + { + fprintf ("Couldn't convert file %s to UTF-8\n", filename); + g_error_free (error); + } + else + g_print (utf8_text); + } +else + fprintf (stderr, "Unable to read file %percnt;s\n", filename); + + + +For string literals in the source code, there are several alternatives for + handling non-ASCII content: + +direct UTF-8 + +If your editor and compiler are capable of handling UTF-8 encoded sources, +it is very convenient to simply use UTF-8 for string literals, since it allows +you to edit the strings in "wysiwyg". Note that choosing this option may +reduce the portability of your code. + + + +escaped UTF-8 + +Even if your toolchain can't handle UTF-8 directly, you can still encode string +literals in UTF-8 by using octal or hexadecimal escapes like +\212 or \xa8 to +encode each byte. This is portable, but modifying the escaped strings is not +very convenient. Be careful when mixing hexadecimal escapes with ordinary text; +"\xa8abcd" is a string of length 1 ! + + + +runtime conversion + +If the string literals can be represented in an encoding which your toolchain +can handle (e.g. IS0-8859-1), you can write your source files in that encoding +and use g_convert() to convert the strings to +UTF-8 at runtime. Note that this has some runtime overhead, so you may want to +move the conversion out of inner loops. + + + +Here is an example showing the three approaches using the copyright sign +© which has Unicode and ISO-8859-1 codepoint 169 and is represented in +UTF-8 by the two bytes 194, 169: + +g_print ("direct UTF-8: ©"); +g_print ("escaped UTF-8: \302\251"); +text = g_convert ("runtime conversion: ©", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL); +g_print(text); +g_free (text); + + + + + How do I use GTK+ with C++? @@ -290,7 +398,100 @@ To load an image or animation file asynchronously (without blocking), use + + +How do I draw text ? + + + + +To draw a piece of text, use a Pango layout and +gdk_draw_layout(), +using code like the following: + + + layout = gtk_widget_create_pango_layout (widget, text); + fontdesc = pango_font_description_from_string ("Luxi Mono 12"); + pango_layout_set_font_description (layout, fontdesc); + gdk_draw_layout (..., layout); + pango_font_description_free (fontdesc); + g_object_unref (layout); + + +Do not use the deprecated GdkFont and gdk_draw_text(). + + + +See also the "Text Handling in GTK 2" section of +Porting applications +to the GNOME 2.0 platform. + + + + + + + + +How do I measure the size of a piece of text ? + + + + +To obtain the size of a piece of text, use a Pango layout and +pango_layout_get_pixel_size(), +using code like the following: + + + layout = gtk_widget_create_pango_layout (widget, text); + fontdesc = pango_font_description_from_string ("Luxi Mono 12"); + pango_layout_set_font_description (layout, fontdesc); + pango_layout_get_pixel_size (layout, &width, &height); + pango_font_description_free (fontdesc); + g_object_unref (layout); + + +Do not use the deprecated function gdk_text_width(). + + + +See also the "Text Handling in GTK 2" section of +Porting applications +to the GNOME 2.0 platform. + + + + + + + +How do I make a text view scroll to the end of the buffer automatically ? + + + + + +The "insert" mark marks the insertion point +where gtk_text_buffer_insert() +inserts new text into the buffer. The text is inserted +before the "insert" mark, so that it generally stays +at the end of the buffer. If it gets explicitly moved to some other position, +e.g. when the user selects some text, +use gtk_text_buffer_move_mark() +to set it to the desired location before inserting more text. +The "insert" mark of a buffer can be obtained with gtk_text_buffer_get_insert(). + + + +To ensure that the end of the buffer remains visible, use +gtk_text_view_scroll_to_mark() to scroll to the "insert" mark after inserting new text. + + + Which widget should I use... @@ -459,6 +660,20 @@ or + + +How do I make a text widget display its complete contents in a specific font? + + + +If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select the font, the inserted text will have the desired appearance, but text typed in by the user before or after the tagged block will appear in the default style. + + +To ensure that all text has the desired appearance, use gtk_widget_modify_font() to change the default font for the widget. + + @@ -543,6 +758,88 @@ linkend="gtk-tree-model-get">gtk_tree_model_get(). + + +How do I change the way that numbers are formatted by GtkTreeView? + + +Use gtk_tree_view_insert_column_with_data_func() +or gtk_tree_view_column_set_cell_data_func() +and do the conversion from number to string yourself (with, say, +g_strdup_printf()). + + + +The following example demonstrates this: + +enum +{ + DOUBLE_COLUMN, + N_COLUMNS +}; + +GtkListStore *mycolumns; +GtkTreeView *treeview; + +void +my_cell_double_to_text (GtkTreeViewColumn *tree_column, + GtkCellRenderer *cell, + GtkTreeModel *tree_model, + GtkTreeIter *iter, + gpointer data) +{ + GtkCellRendererText *cell_text = (GtkCellRendererText *)cell; + gdouble d; + gchar *text; + + /* Get the double value from the model. */ + gtk_tree_model_get (tree_model, iter, (gint)data, &d, -1); + /* Now we can format the value ourselves. */ + text = g_strdup_printf ("%.2f", d); + g_object_set (cell, "text", text, NULL); + g_free (text); +} + +void +set_up_new_columns (GtkTreeView *myview) +{ + GtkCellRendererText *renderer; + GtkTreeViewColumn *column; + GtkListStore *mycolumns; + + /* Create the data model and associate it with the given TreeView */ + mycolumns = gtk_list_store_new (N_COLUMNS, G_TYPE_DOUBLE); + gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns)); + + /* Create a GtkCellRendererText */ + renderer = gtk_cell_renderer_text_new (); + + /* Create a new column that has a title ("Example column"), + * uses the above created renderer that will render the double + * value into text from the associated model's rows. + */ + column = gtk_tree_view_column_new (); + gtk_tree_view_column_set_title (column, "Example column"); + renderer = gtk_cell_renderer_text_new (); + gtk_tree_view_column_pack_start (column, renderer, TRUE); + + /* Append the new column after the GtkTreeView's previous columns. */ + gtk_tree_view_append_column (GTK_TREE_VIEW (myview), column); + /* Since we created the column by hand, we can set it up for our + * needs, e.g. set its minimum and maximum width, etc. + */ + /* Set up a custom function that will be called when the column content + * is rendered. We use the func_data pointer as an index into our + * model. This is convenient when using multi column lists. + */ + gtk_tree_view_column_set_cell_data_func (column, renderer, + my_cell_double_to_text, + (gpointer)DOUBLE_COLUMN, NULL); +} + + + + -- 2.43.2