diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 98955f5232..cd2896737a 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -111,7 +111,17 @@ content_files = \ visual_index.xml expand_content_files = \ - tree_widget.sgml + glossary.xml \ + migrating-checklist.sgml \ + migrating-GtkAction.sgml \ + migrating-GtkComboBox.sgml \ + migrating-GtkFileChooser.sgml \ + migrating-GtkIconView.sgml \ + migrating-GtkAboutDialog.sgml \ + migrating-GtkColorButton.sgml \ + tree_widget.sgml \ + text_widget.sgml \ + question_index.sgml # Images to copy into HTML directory HTML_IMAGES = \ diff --git a/docs/reference/gtk/glossary.xml b/docs/reference/gtk/glossary.xml index 716424882d..b7a9998256 100644 --- a/docs/reference/gtk/glossary.xml +++ b/docs/reference/gtk/glossary.xml @@ -24,7 +24,7 @@ A container that can hold at most one child widget. The base class for bins is - GtkBin. + #GtkBin. container @@ -48,10 +48,9 @@ GTK+ contains several widgets which display data in columns, - e.g. the GtkTreeView. + e.g. the #GtkTreeView. These view columns in - the tree view are represented by - GtkTreeViewColumn + the tree view are represented by #GtkTreeViewColumn objects inside GTK+. They should not be confused with model columns which are used to organize the data in tree models. @@ -69,14 +68,11 @@ parent of the child widgets. Some containers don't draw anything on their own, but rather just organize their children's geometry; for example, GtkVBox lays out its children - vertically without painting anything on its own. Other - containers include decorative elements; for example, GtkFrame contains the frame's child - and a label in addition to the shaded frame it draws. The - base class for containers is GtkContainer. + linkend="geometry">geometry; for example, #GtkVBox lays out + its children vertically without painting anything on its own. Other + containers include decorative elements; for example, #GtkFrame contains + the frame's child and a label in addition to the shaded frame it draws. + The base class for containers is #GtkContainer. widget @@ -94,8 +90,7 @@ of a keyboard, a pointing device and one or more screens. Applications open a display to show windows and interact with the user. - In GDK, a display is represented by a - GdkDisplay. + In GDK, a display is represented by a #GdkDisplay. @@ -130,15 +125,13 @@ actually shows the GdkWindows it created when it was realized. When a widget is mapped, it must turn on its - GTK_MAPPED flag. + %GTK_MAPPED flag. Note that due to the asynchronous nature of the X window system, a widget's window may not appear on the screen - immediatly after one calls gdk_window_show(): + immediatly after one calls gdk_window_show(): you must wait for the corresponding map event to be received. You can do this with the gtk_list_store_new(). + e.g. gtk_list_store_new(). view column @@ -170,17 +163,13 @@ These widgets follow the well-known model-view pattern, which separates the data (the model) to be displayed from the component which does the actual visualization (the view). Examples of this pattern in GTK+ are - the GtkTreeView/GtkTreeModel - and - GtkTextView/GtkTextBuffer + the #GtkTreeView/#GtkTreeModel and #GtkTextView/#GtkTextBuffer One important advantage of this pattern is that it is possible to display the same model in multiple views; another one that the separation of the model allows a great deal of flexibility, as - demonstrated by e.g. - GtkTreeModelSort or - GtkTreeModelFilter. + demonstrated by e.g. #GtkTreeModelSort or #GtkTreeModelFilter. @@ -192,11 +181,8 @@ A widget that does not have a GdkWindow of its own on which to draw its contents, but rather shares its parent's. Such a widget has the - GTK_NO_WINDOW flag set, and can be tested - with the GTK_WIDGET_NO_WINDOW() - macro. + %GTK_NO_WINDOW flag set, and + can be tested with the GTK_WIDGET_NO_WINDOW() macro. @@ -224,17 +210,14 @@ also attach a style to it. A widget becomes unrealized by destroying its associated GdkWindow. When a widget is realized, it must turn on its - GTK_REALIZED flag. + %GTK_REALIZED flag. Widgets that don't own the GdkWindow on which they draw are - called no-window - widgets. This can be tested with the GTK_WIDGET_NO_WINDOW() - macro. Normally, these widgets draw on their parent's - GdkWindow. + called no-window widgets. + This can be tested with the GTK_WIDGET_NO_WINDOW() macro. Normally, + these widgets draw on their parent's GdkWindow. @@ -276,8 +259,7 @@ Each screen can stretch across multiple physical monitors. - In GDK, screens are represented by - GdkScreen objects. + In GDK, screens are represented by #GdkScreen objects. @@ -298,9 +280,8 @@ A widget that does not - require a parent - container. The only toplevel widgets in GTK+ are GtkWindow and widgets derived from it. + require a parent container. + The only toplevel widgets in GTK+ are #GtkWindow and widgets derived from it. container @@ -323,7 +304,7 @@ A displayed column in a tree view, represented by a - GtkTreeViewColumn object. + #GtkTreeViewColumn object. model column @@ -362,8 +343,7 @@ linkend="geometry">geometry of the widgets: every widget thus has a parent except those widgets which are toplevels. The base - class for widgets is GtkWidget. + class for widgets is #GtkWidget. container diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 5903ee2dc3..4b4ae88d2f 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -175,7 +175,7 @@ - + @@ -184,20 +184,20 @@ - + - - - - - - - + + + + + + + - + ]> diff --git a/docs/reference/gtk/migrating-GtkAboutDialog.sgml b/docs/reference/gtk/migrating-GtkAboutDialog.sgml index 129b844fc0..0aac9b315f 100644 --- a/docs/reference/gtk/migrating-GtkAboutDialog.sgml +++ b/docs/reference/gtk/migrating-GtkAboutDialog.sgml @@ -3,15 +3,13 @@ Migrating from GnomeAbout to GtkAboutDialog - Since version 2.6, GTK+ provides the GtkAboutDialog widget as a replacement for + Since version 2.6, GTK+ provides the #GtkAboutDialog widget as a replacement for the GnomeAbout dialog in the libgnomeui library. - GtkAboutDialog supports all features - found in GnomeAbout. The - GtkAboutDialog API is bigger, since it follows + #GtkAboutDialog supports all features found in GnomeAbout. + The GtkAboutDialog API is bigger, since it follows the GTK+ policy to have getters and setters for all widget properties, but it isn't much more complex than GnomeAbout. @@ -56,9 +54,9 @@ NULL); g_object_unref (pixbuf); - If the g_object_new() construction scares you, - you can also use gtk_about_dialog_new() to - construct the dialog and then use the setters for the individual properties. + If the g_object_new() construction scares you, you can also use + gtk_about_dialog_new() to construct the dialog and then use the setters for + the individual properties. @@ -82,9 +80,8 @@ If your credits contain email addresses or URLs, you can turn them - into clickable links using - gtk_about_dialog_set_email_hook() and - gtk_about_dialog_set_url_hook(). + into clickable links using gtk_about_dialog_set_email_hook() and + gtk_about_dialog_set_url_hook(). diff --git a/docs/reference/gtk/migrating-GtkAction.sgml b/docs/reference/gtk/migrating-GtkAction.sgml index bb45d4fb8a..73164266a1 100644 --- a/docs/reference/gtk/migrating-GtkAction.sgml +++ b/docs/reference/gtk/migrating-GtkAction.sgml @@ -15,40 +15,35 @@ Prior to GTK+ 2.4, there were several APIs in use to create menus - and toolbars. GTK+ itself included GtkItemFactory, which was + and toolbars. GTK+ itself included #GtkItemFactory, which was historically used in the GIMP; libgnomeui provided the gnome-ui set of macros; libbonoboui provided a complex mechanism to do menu merging across embedded components. GTK+ 2.4 includes a system for creating menus and toolbars, with merging of items, based - around the GtkAction mechanism. + around the #GtkAction mechanism.
Actions and Action Groups - A GtkAction represents an - operation that the user can perform from the menus and toolbars - of an application. It is similar to "verbs" in other menu - systems. A GtkAction has a - name, which is its identifier, and it can have several widgets - that represent it in the user interface. For example, an action - for EditCopy can have a menu item as well as a - toolbar button associated to it. If there is nothing selected + A #GtkAction represents an operation that the user can perform from + the menus and toolbars of an application. It is similar to "verbs" + in other menu systems. A #GtkAction has a name, which is its identifier, + and it can have several widgets that represent it in the user interface. + For example, an action for EditCopy can have a menu item + as well as a toolbar button associated to it. If there is nothing selected in the document, the application can simply de-sensitize the EditCopy action; this will cause both the menu item and the toolbar button to be de-sensitized automatically. Similarly, whenever the user selects the menu item or the toolbar button associated to the EditCopy - action, the corresponding GtkAction object will emit an + action, the corresponding #GtkAction object will emit an "activate" signal. - GtkActionGroup is simply a - group of GtkAction objects. An + #GtkActionGroup is simply a group of #GtkAction objects. An application may want to have several groups: one for global actions such as "new document", "about", and "exit"; then one group for each open document with actions specific to the @@ -72,22 +67,20 @@ User Interface Manager Object - GtkUIManager is an object - that can construct menu and toolbar widgets from an XML - description. These widgets are in turn associated to + #GtkUIManager is an object that can construct menu and toolbar widgets + from an XML description. These widgets are in turn associated to corresponding actions and action groups. - GtkUIManager supports - merging of menus and toolbars for applications that have - multiple components, each with separate sets of commands. For - example, a word processor that can embed images may want to have + #GtkUIManager supports merging of menus and toolbars for applications + that have multiple components, each with separate sets of commands. + For example, a word processor that can embed images may want to have toolbar buttons for Bold and Italic when the cursor is on a text block, but Crop and Brightness/Contrast buttons when the cursor is on an image. These actions, which change depending on the state of the application, can be merged and de-merged from a - GtkUIManager as appropriate. + #GtkUIManager as appropriate.
@@ -102,8 +95,7 @@ array of GnomeUIInfo structures, which contain information for menu or toolbar items such as their label, icon, and accelerator key. Then, one calls - gnome_app_fill_menu() or - gnome_app_fill_toolbar(), or one of the + gnome_app_fill_menu() or gnome_app_fill_toolbar(), or one of the related functions, to create the appropriate widgets based on these structures. @@ -113,8 +105,7 @@ pass back pointers to the widgets that got created. This means that the structures cannot simply be kept around if the program requires multiple instances of the user interface (e.g. several - windows); each new invocation of - gnome_app_fill_menu() would overwrite the + windows); each new invocation of gnome_app_fill_menu() would overwrite the widget fields of the structures. @@ -142,11 +133,9 @@ Separate your existing GnomeUIInfo entries into normal actions, toggle actions, and radio actions, and then create - a separate array of GtkActionEntry structures + a separate array of #GtkActionEntry structures for each group. This will allow you to create the necessary - GtkActionGroup - objects. Note that this does not describe the actual + #GtkActionGroup objects. Note that this does not describe the actual "shape" that your menus and toolbars will have; it simply defines the set of commands that will appear in them. @@ -154,27 +143,22 @@ Create an XML description of your menus and toolbars for use - with GtkUIManager. This - defines the actual shape of the menus and toolbars. + with #GtkUIManager. This defines the actual shape of the menus and toolbars. Port the code that uses gnome-app and gnome-app-helper to - GtkAction and GtkUIManager. + #GtkAction and #GtkUIManager. If your GnomeUIInfo entries use GNOME_APP_PIXMAP_DATA or GNOME_APP_PIXMAP_FILENAME for pixmaps, you have to create a - GtkIconFactory, add it - to the list of default factories, then create a - GtkIconSet for each of your - own icons. Add the sets to the factory, and use the id in the - GtkActionEntry like a - regular GTK+ stock id. + #GtkIconFactory, add it to the list of default factories, then create a + #GtkIconSet for each of your own icons. Add the sets to the factory, and + use the id in the #GtkActionEntry like a regular GTK+ stock id. @@ -184,8 +168,8 @@ The following code shows a declaration of a simple menu bar to - be used with gnome_app_fill_menu() or - similar. The menu hierarchy looks like this: + be used with gnome_app_fill_menu() or similar. The menu hierarchy looks + like this: @@ -269,15 +253,12 @@ static GnomeUIInfo menubar[] = { The following code is the set of actions that are present in the previous example. Note that the toggle and radio entries are - separate from normal actions. Also, note that GtkActionEntry structures take - key names in the format of gdk_accelerator_parse() rather than - key values plus modifiers; you will have to convert these - values by hand. For example, GDK_F11 - with no modifiers is equivalent to a key name of - "F11". Likewise, "o" - with GDK_CONTROL_MASK is equivalent to - "<ontrol>O". + separate from normal actions. Also, note that #GtkActionEntry + structures take key names in the format of gdk_accelerator_parse() + rather than key values plus modifiers; you will have to convert these + values by hand. For example, %GDK_F11 with no modifiers is equivalent + to a key name of "F11". Likewise, "o" + with %GDK_CONTROL_MASK is equivalent to "<ontrol>O". @@ -311,9 +292,8 @@ static GtkRadioActionEntry radio_entries[] = { After extracting the actions, you will need to create an XML description of the actual layout of your menus and toolbars - for use with GtkUIManager. - The following code shows a simple menu bar that corresponds to - the previous + for use with #GtkUIManager. The following code shows a simple + menu bar that corresponds to the previous example. Note that the File and View menus have their names specified in the action @@ -349,16 +329,12 @@ static const char *ui_description = Creating the Menu Bar - In this last example, we will create a GtkActionGroup based on the - action - entries we created above. We will then create a GtkUIManager with the action entries + we created above. We will then create a #GtkUIManager with the XML description of the menu layout. We will also extract the accelerator group and the - widgets from the GtkUIManager put them into a - window. + widgets from the #GtkUIManager put them into a window. @@ -370,7 +346,7 @@ GtkUIManager *ui_manager; GtkAccelGroup *accel_group; GError *error; -register_my_stock_icons (); +register_my_stock_icons (); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); @@ -382,7 +358,7 @@ gtk_action_group_add_actions (action_group, entries, G_N_ELEMENTS (entries), win gtk_action_group_add_toggle_actions (action_group, toggle_entries, G_N_ELEMENTS (toggle_entries), window); gtk_action_group_add_radio_actions (action_group, radio_entries, G_N_ELEMENTS (radio_entries), 0, radio_action_callback, window); -ui_manager = gtk_ui_manager_new (); +ui_manager = gtk_ui_manager_new (); gtk_ui_manager_insert_action_group (ui_manager, action_group, 0); accel_group = gtk_ui_manager_get_accel_group (ui_manager); @@ -431,12 +407,12 @@ register_my_stock_icons (void) GtkIconSource *icon_source; gint i; - icon_factory = gtk_icon_factory_new (); + icon_factory = gtk_icon_factory_new (); for (i = 0; i < n_stock_icons; i++) { - icon_set = gtk_icon_set_new (); - icon_source = gtk_icon_source_new (); + icon_set = gtk_icon_set_new (); + icon_source = gtk_icon_source_new (); gtk_icon_source_set_filename (icon_source, stock_icons[i].filename); gtk_icon_set_add_source (icon_set, icon_source); gtk_icon_source_free (icon_source); diff --git a/docs/reference/gtk/migrating-GtkColorButton.sgml b/docs/reference/gtk/migrating-GtkColorButton.sgml index 8bc79c824b..0d1103b22c 100644 --- a/docs/reference/gtk/migrating-GtkColorButton.sgml +++ b/docs/reference/gtk/migrating-GtkColorButton.sgml @@ -3,10 +3,9 @@ Migrating from GnomeColorPicker to GtkColorButton - Since version 2.6, GTK+ provides the GtkColorButton + Since version 2.6, GTK+ provides the #GtkColorButton widget as a replacement for the GnomeColorPicker - widget in the libgnomeui - library. + widget in the libgnomeui library. diff --git a/docs/reference/gtk/migrating-GtkComboBox.sgml b/docs/reference/gtk/migrating-GtkComboBox.sgml index ac35029d09..a469b6ea3b 100644 --- a/docs/reference/gtk/migrating-GtkComboBox.sgml +++ b/docs/reference/gtk/migrating-GtkComboBox.sgml @@ -1,21 +1,18 @@ - Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and GtkComboBoxEntry + Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and + GtkComboBoxEntry Prior to 2.4, GTK+ offered two widgets for the task of selecting one - item from a list of options. - GtkOptionMenu presents the list of - options as a menu while GtkCombo presents - them in a Windows-style list popup. The only difference between the two - is that a GtkCombo allows to manually - edit the selected value, while the - GtkOptionMenu does not. + item from a list of options. #GtkOptionMenu presents the list of + options as a menu while #GtkCombo presents them in a Windows-style list + popup. The only difference between the two is that a #GtkCombo allows to + manually edit the selected value, while the #GtkOptionMenu does not. In GTK+ 2.4, a unified API for list selection was introduced, with - GtkComboBox for the non-editable case - and GtkComboBoxEntry for the + #GtkComboBox for the non-editable case and #GtkComboBoxEntry for the editable case. The selection of the display style — menu or list — is no longer done at the API level, but has been made themeable via @@ -28,12 +25,12 @@ Here is an example of a simple, but typical use of - GtkOptionMenu: + #GtkOptionMenu: GtkWidget *option_menu, *menu, *menu_item; -option_menu = gtk_option_menu_new (); -menu = gtk_menu_new (); +option_menu = gtk_option_menu_new (); +menu = gtk_menu_new (); menu_item = gtk_menu_item_new_with_label ("First Item"); gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); @@ -48,23 +45,22 @@ gtk_widget_show (menu_item); gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu); In order to react to the user's selection, connect to the "changed" - signal on the option menu and use gtk_option_menu_get_history() + signal on the option menu and use gtk_option_menu_get_history() to retrieve the index of the selected item. - And here is how it would be done with a - GtkComboBox: + And here is how it would be done with a #GtkComboBox: GtkWidget *combo_box; -combo_box = gtk_combo_box_new_text (); +combo_box = gtk_combo_box_new_text (); gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item"); gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item"); gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item"); In order to react to the user's selection, connect to the "changed" - signal on the combo box and use gtk_combo_box_get_active() + signal on the combo box and use gtk_combo_box_get_active() to retrieve the index of the selected item. @@ -73,8 +69,8 @@ gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item"); GtkWidget *option_menu, *menu, *menu_item; -option_menu = gtk_option_menu_new (); -menu = gtk_menu_new (); +option_menu = gtk_option_menu_new (); +menu = gtk_menu_new (); menu_item = gtk_image_menu_item_new_with_label ("First Item"); gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf1)); @@ -93,8 +89,7 @@ gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu); - can be done using a GtkComboBox - as follows: + can be done using a #GtkComboBox as follows: GtkListStore *store; GtkTreeIter iter; @@ -112,13 +107,13 @@ gtk_list_store_set (store, &iter, 0, pixbuf3, 1, "Third Item", -1); combo_box = gtk_combo_box_new_with_model (GTK_TREE_MODEL (store)); -renderer = gtk_cell_renderer_pixbuf_new (); +renderer = gtk_cell_renderer_pixbuf_new (); gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo_box), renderer, FALSE); gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer, "pixbuf", 0, NULL); -renderer = gtk_cell_renderer_text_new (); +renderer = gtk_cell_renderer_text_new (); gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo_box), renderer, TRUE); gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer, "text", 1, @@ -131,8 +126,7 @@ gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer, Migrating from GtkCombo to GtkComboBoxEntry - Here is an example of a simple, but typical use of a - GtkCombo: + Here is an example of a simple, but typical use of a #GtkCombo: GtkWidget *combo; GList *items = NULL; @@ -141,7 +135,7 @@ items = g_list_append (items, "First Item"); items = g_list_append (items, "Second Item"); items = g_list_append (items, "Third Item"); -combo = gtk_combo_new (); +combo = gtk_combo_new (); gtk_combo_set_popdown_strings (GTK_COMBO (combo), items); In order to react to the user's selection, connect to the "changed" @@ -150,9 +144,9 @@ gtk_combo_set_popdown_strings (GTK_COMBO (combo), items); to retrieve the selected text. - And here is how it would be done using GtkComboBoxEntry: + And here is how it would be done using #GtkComboBoxEntry: -combo_box = gtk_combo_box_entry_new_text (); +combo_box = gtk_combo_box_entry_new_text (); gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item"); gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item"); @@ -170,8 +164,7 @@ gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item"); The new widgets have more to offer than a mere combination of the - features of GtkOptionMenu and - GtkCombo. Notable new features + features of #GtkOptionMenu and #GtkCombo. Notable new features include: @@ -181,29 +174,26 @@ gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item"); would be a "color combo" where the individual items are small square color swatches. The new widgets support gridded display with the functions - gtk_combo_box_set_wrap_width(), - gtk_combo_box_set_row_span_column() and - gtk_combo_box_set_column_span_column(). + gtk_combo_box_set_wrap_width(), + gtk_combo_box_set_row_span_column() and + gtk_combo_box_set_column_span_column(). Display of icons - An often-heard complaint about - GtkOptionMenu is that the - icons which appear in the image menu items in its menu are not + An often-heard complaint about #GtkOptionMenu is that + the icons which appear in the image menu items in its menu are not displayed in the button showing the selected item. This limitation - has been removed in GtkComboBox; - the selected item appears in the same way as the options in - the popup. + has been removed in #GtkComboBox; the selected item appears in the + same way as the options in the popup. Full tree model power Since the new widgets are built around the same models that are - used for GtkTreeView, all of - the powerful machinery of tree models and cell renderers can be - used. + used for #GtkTreeView, all of the powerful machinery of tree models + and cell renderers can be used. diff --git a/docs/reference/gtk/migrating-GtkFileChooser.sgml b/docs/reference/gtk/migrating-GtkFileChooser.sgml index 8316ff6f07..67f6f62388 100644 --- a/docs/reference/gtk/migrating-GtkFileChooser.sgml +++ b/docs/reference/gtk/migrating-GtkFileChooser.sgml @@ -14,30 +14,20 @@ Migrating from GtkFileSelection to GtkFileChooser - GtkFileChooser, starting - with GTK+ 2.4, is the new set of APIs for file selection widgets - and dialogs. Previous versions of GTK+ used GtkFileSelection, which has - numerous problems. + #GtkFileChooser, starting with GTK+ 2.4, is the new set of APIs for file + selection widgets and dialogs. Previous versions of GTK+ used #GtkFileSelection, + which has numerous problems. - GtkFileChooser is an - abstract interface that can be implemented by widgets that perform - file selection tasks. Two widgets in GTK+ implement this - interface: GtkFileChooserDialog and - GtkFileChooserWidget. - Most applications simply need to use GtkFileChooserDialog, which - is a dialog box that allows the user to select existing files for - opening them, or to pick new filenames for saving documents. - GtkFileChooserWidget - is for special applications that need to embed a file selection - widget inside a larger window. In the context of GTK+, GtkFileChooserDialog is - simply a GtkDialog box with a - GtkFileChooserWidget + #GtkFileChooser is an abstract interface that can be implemented by widgets + that perform file selection tasks. Two widgets in GTK+ implement this + interface: #GtkFileChooserDialog and #GtkFileChooserWidget. Most applications + simply need to use #GtkFileChooserDialog, which is a dialog box that allows the + user to select existing files for opening them, or to pick new filenames for + saving documents. #GtkFileChooserWidget is for special applications that need to + embed a file selection widget inside a larger window. In the context of GTK+, + #GtkFileChooserDialog is simply a #GtkDialog box with a #GtkFileChooserWidget. inside. @@ -45,10 +35,8 @@ Creating a GtkFileChooserDialog - To create a GtkFileChooserDialog, you - simply call gtk_file_chooser_dialog_new(). This function is - similar to gtk_dialog_new() in that it takes parameters for the + To create a #GtkFileChooserDialog, you simply call gtk_file_chooser_dialog_new(). + This function is similar to gtk_dialog_new() in that it takes parameters for the title of the dialog box and its transient parent, as well as its buttons. In addition, it takes in an argument that determines whether the file chooser dialog will be used for opening @@ -66,25 +54,21 @@ Selection Modes - GtkFileChooser can be used - in two modes, to select a single file at a time or to select a - set of more than one file. To set this, use + #GtkFileChooser can be used in two modes, to select a single file at a + time or to select a set of more than one file. To set this, use gtk_file_chooser_set_select_multiple(). In single-selection mode, you can use gtk_file_chooser_get_filename() to get a file name from the local file system or gtk_file_chooser_get_uri() to get a full-formed URI. In multiple-selection mode, you can use - gtk_file_chooser_get_filenames() to get a GSList of filename strings, or + gtk_file_chooser_get_filenames() to get a #GSList of filename strings, or gtk_file_chooser_get_uris() to get a list of URI strings. - Also, you can configure GtkFileChooser to select files + Also, you can configure #GtkFileChooser to select files or folders. Consider a backup program that needs to let the user select a folder that will be backed up along with its - subfolders. To configure whether GtkFileChooser is used to select + subfolders. To configure whether #GtkFileChooser is used to select files or folders, use gtk_file_chooser_set_action(). In addition, this lets you configure whether the file chooser will be used to select existing files or folders (e.g. for @@ -99,10 +83,8 @@ Many applications need to have a preview facility within their file chooser dialogs. Previous to GTK+ 2.4, one needed to - access the GtkFileSelection widget - hierarchy directly to hook in a preview widget. With GtkFileChooser, there is a + access the #GtkFileSelection widget hierarchy directly to hook in + a preview widget. With #GtkFileChooser, there is a dedicated API to do this. @@ -132,18 +114,15 @@ New features - New features in GtkFileChooser include the - following: + New features in #GtkFileChooser include the following: Ability to select URIs rather than just local files. You - must use a GtkFileSystem implementation - that supports this, for example the gnome-vfs backend. + must use a #GtkFileSystem implementation that supports this, + for example the gnome-vfs backend. @@ -166,9 +145,8 @@ - To see how to use these features, please consult the GtkFileChooser reference - documentation. + To see how to use these features, please consult the #GtkFileChooser + reference documentation. diff --git a/docs/reference/gtk/migrating-GtkIconView.sgml b/docs/reference/gtk/migrating-GtkIconView.sgml index bff63ae26d..5f307126b5 100644 --- a/docs/reference/gtk/migrating-GtkIconView.sgml +++ b/docs/reference/gtk/migrating-GtkIconView.sgml @@ -3,10 +3,8 @@ Migrating from GnomeIconList to GtkIconView - Since version 2.6, GTK+ provides the GtkIconView - widget. It is similar in functionality to the - GnomeIconList widget in the + Since version 2.6, GTK+ provides the #GtkIconView widget. It is similar in + functionality to the GnomeIconList widget in the libgnomeui library, both widgets provide a way to lay out named icons in a grid. The distinctive feature of the GTK+ widget is that it follows the model-view pattern, allowing it to share the actual data (i.e. the names @@ -14,19 +12,17 @@ - GtkIconView currently doesn't support - some features found in GnomeIconList. Icons can - not be positioned freely, the spacing is not customizable, and it is not - possible to edit the names of icons. + #GtkIconView currently doesn't support some features found in + GnomeIconList. Icons can not be positioned freely, + the spacing is not customizable, and it is not possible to edit the names of + icons. To convert an application that uses GnomeIconList - to GtkIconView, the first step is to - organize your data in a GtkTreeModel. + to #GtkIconView, the first step is to organize your data in a #GtkTreeModel. GnomeIconList lets you directly insert data with - gnome_icon_list_insert() and - gnome_icon_list_insert_pixbuf() and their + gnome_icon_list_insert() and gnome_icon_list_insert_pixbuf() and their append variants. So, if you previously had a function to fill your icon list similar to this one: @@ -81,7 +77,7 @@ /* do other initialization... */ /* construct the GtkIconView */ - icon_view = gtk_icon_view_new (); + icon_view = gtk_icon_view_new (); model = gtk_list_store_new (3, GDK_TYPE_PIXBUF, G_TYPE_STRING, G_TYPE_POINTER); gtk_icon_view_set_pixbuf_column (GTK_ICON_VIEW (icon_view), PIXBUF_COLUMN); @@ -93,18 +89,15 @@ /* ... */ } - This example uses a GtkListStore as - model, but part of the elegance of the model-view pattern is that you can - easily use another tree model implementation, or even write your own - custom tree model. + This example uses a #GtkListStore as model, but part of the elegance of the + model-view pattern is that you can easily use another tree model implementation, + or even write your own custom tree model. Your application may make use of extra data attached to the icons in the - GnomeIconList via - gnome_icon_list_set_icon_data() and - gnome_icon_list_get_icon_data(). With - GtkIconView such data is most + GnomeIconList via gnome_icon_list_set_icon_data() and + gnome_icon_list_get_icon_data(). With #GtkIconView such data is most conveniently stored in an extra column in the tree model, so you would call a function like @@ -124,7 +117,7 @@ } assuming that your tree model has a DATA_COLUMN of type - G_TYPE_POINTER. + %G_TYPE_POINTER. @@ -140,8 +133,7 @@ GtkIconView can not be frozen in the same way as GnomeIconList can with - gnome_icon_list_freeze() and - gnome_icon_list_thaw(). Instead you can + gnome_icon_list_freeze() and gnome_icon_list_thaw(). Instead you can replace the whole model of a GtkIconView, instead of doing many small changes to the existing model. diff --git a/docs/reference/gtk/migrating-checklist.sgml b/docs/reference/gtk/migrating-checklist.sgml index 47a3fece77..8dde609b30 100644 --- a/docs/reference/gtk/migrating-checklist.sgml +++ b/docs/reference/gtk/migrating-checklist.sgml @@ -51,7 +51,7 @@ do_popup_menu (GtkWidget *my_widget, GdkEventButton *event) GtkWidget *menu; int button, event_time; - menu = gtk_menu_new (); + menu = gtk_menu_new (); g_signal_connect (menu, "deactivate", G_CALLBACK (gtk_widget_destroy), NULL); @@ -65,7 +65,7 @@ do_popup_menu (GtkWidget *my_widget, GdkEventButton *event) else { button = 0; - event_time = gtk_get_current_event_time (); + event_time = gtk_get_current_event_time (); } gtk_menu_popup (GTK_MENU (popup), NULL, NULL, NULL, NULL, @@ -127,7 +127,7 @@ my_widget_popup_menu_handler (GtkWidget *widget) in the case where the event is NULL. This function should compute the desired position for a menu when it is invoked through the - keyboard. For example, aligns the + keyboard. For example, #GtkEntry aligns the top edge of its popup menu with the bottom edge of the entry. @@ -138,9 +138,8 @@ my_widget_popup_menu_handler (GtkWidget *widget) able to take the keyboard focus. In general, widgets should be fully usable through the keyboard and not just the mouse. The very first step of this is to ensure that your widget - turns on the GTK_CAN_FOCUS - FLAG. + turns on the %GTK_CAN_FOCUS flag. @@ -218,7 +217,7 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event) Why With - gtk_accelerator_get_default_mod_mask() + gtk_accelerator_get_default_mod_mask() you can test for modifier keys reliably; this way your key event handlers will work correctly even if NumLock or CapsLock are @@ -233,8 +232,7 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event) Modifiers are keys like Control and NumLock. When implementing a GtkWidget::key_press_event - handler, you should use - gtk_accelerator_get_default_mod_mask() to + handler, you should use gtk_accelerator_get_default_mod_mask() to test against modifier keys. This function returns a bit mask which encompasses all the modifiers which the user may be actively pressing, such as Control, @@ -254,7 +252,7 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event) GDK_CONTROL_MASK | GDK_LOCK_MASK, and the simple test will fail. By taking the logical-and of event->state and - gtk_accelerator_get_default_mod_mask(), you + gtk_accelerator_get_default_mod_mask(), you can ignore the modifiers which are not actively pressed by the user at the same time as the base key. @@ -271,7 +269,7 @@ my_widget_key_press_event_handler (GtkWidget *widget, GdkEventKey *event) { guint modifiers; - modifiers = gtk_accelerator_get_default_mod_mask (); + modifiers = gtk_accelerator_get_default_mod_mask (); if (event->keysym == GDK_F10 && (event->state & modifiers) == GDK_CONTROL_MASK) diff --git a/docs/reference/gtk/question_index.sgml b/docs/reference/gtk/question_index.sgml index 2456e03ce1..da2c310fce 100644 --- a/docs/reference/gtk/question_index.sgml +++ b/docs/reference/gtk/question_index.sgml @@ -96,22 +96,17 @@ from functions? -See the documentation for GObject and -GtkObject. For GObject note specifically g_object_ref() and g_object_unref(). GtkObject is a subclass of GObject so the same points apply, except that -it has a "floating" state (explained in its documentation). +See the documentation for #GObject and #GtkObject. For #GObject note specifically +g_object_ref() and g_object_unref(). #GtkObject is a subclass of #GObject so the +same points apply, except that it has a "floating" state (explained in its +documentation). -For strings returned from functions, they will be declared "const" -(using G_CONST_RETURN) if they -should not be freed. Non-const strings should be freed with g_free(). Arrays follow the same rule. (If -you find an exception to the rules, please report a bug to http://bugzilla.gnome.org.) @@ -193,12 +188,10 @@ or Linux system with gettext installed, type info gettext to read the documentation. -The short checklist on how to use gettext is: call -bindtextdomain() so gettext can find the files -containing your translations, call textdomain() -to set the default translation domain, then call -gettext() to look up each string to be translated -in the default domain. Conventionally, people define macros as +The short checklist on how to use gettext is: call bindtextdomain() so gettext +can find the files containing your translations, call textdomain() to set the +default translation domain, then call gettext() to look up each string to be +translated in the default domain. Conventionally, people define macros as follows for convenience: @@ -206,13 +199,10 @@ follows for convenience: #define N_(x) x -You use N_() (N stands for no-op) to mark -a string for translation in a context where a function call -to gettext() is not allowed, such as in -an array initializer. You eventually have to call -gettext() on the string to actually fetch the -translation. _() both marks the string for -translation and actually translates it. +You use N_() (N stands for no-op) to mark a string for translation in a context +where a function call to gettext() is not allowed, such as in an array initializer. +You eventually have to call gettext() on the string to actually fetch the +translation. _() both marks the string for translation and actually translates it. Code using these macros ends up looking like this: @@ -238,14 +228,10 @@ Code using these macros ends up looking like this: -Libraries using gettext should use dgettext() -instead of gettext(), which allows -them to specify the translation domain each time they -ask for a translation. Libraries should also avoid calling -textdomain(), since they'll be specifying -the domain instead of using the default. -For dgettext() the _() macro -can be defined as: +Libraries using gettext should use dgettext() instead of gettext(), which allows +them to specify the translation domain each time they ask for a translation. Libraries +should also avoid calling textdomain(), since they'll be specifying the domain instead +of using the default.For dgettext() the _() macro can be defined as: #define _(x) dgettext ("MyDomain", x) @@ -285,9 +271,7 @@ The zero byte doesn't occur as part of a character, so that UTF-8 strings can 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(). + encodings, see g_locale_to_utf8() and g_convert(). Text coming from external sources (e.g. files or user input), has to be @@ -343,9 +327,8 @@ very convenient. Be careful when mixing hexadecimal escapes with ordinary text; 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. +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. @@ -429,28 +412,19 @@ How do I load an image or animation from a file? -To load an image file straight into a display widget, use gtk_image_new_from_file() - If the file load fails, gtk_image_new_from_file() -will display a "broken image" graphic — to detect a failed load -yourself, use gdk_pixbuf_new_from_file() -directly then gtk_image_new_from_pixbuf(). -. To load an image for another purpose, use gdk_pixbuf_new_from_file(). -To load an animation, use gdk_pixbuf_animation_new_from_file(). -gdk_pixbuf_animation_new_from_file() -can also load non-animated images, so use it in combination with -gdk_pixbuf_animation_is_static_image() to load a file of unknown type. +To load an image file straight into a display widget, use gtk_image_new_from_file() + If the file load fails, gtk_image_new_from_file() will display no +image graphic — to detect a failed load yourself, use gdk_pixbuf_new_from_file() +directly, then gtk_image_new_from_pixbuf().. +To load an image for another purpose, use gdk_pixbuf_new_from_file(). To load an +animation, use gdk_pixbuf_animation_new_from_file(). +gdk_pixbuf_animation_new_from_file() can also load non-animated images, so use it +in combination with gdk_pixbuf_animation_is_static_image() to load a file of unknown +type. To load an image or animation file asynchronously (without blocking), use -GdkPixbufLoader. +#GdkPixbufLoader. @@ -463,8 +437,7 @@ How do I draw text ? -To draw a piece of text, use a Pango layout and -gdk_draw_layout(), +To draw a piece of text, use a Pango layout and gdk_draw_layout(), using code like the following: @@ -476,7 +449,7 @@ using code like the following: g_object_unref (layout); -Do not use the deprecated GdkFont and gdk_draw_text(). +Do not use the deprecated #GdkFont and gdk_draw_text(). @@ -498,9 +471,7 @@ 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: +pango_layout_get_pixel_size(), using code like the following: layout = gtk_widget_create_pango_layout (widget, text); @@ -511,7 +482,7 @@ using code like the following: g_object_unref (layout); -Do not use the deprecated function gdk_text_width(). +Do not use the deprecated function gdk_text_width(). @@ -558,12 +529,9 @@ volatile GType dummy = GTK_TYPE_BLAH; See tree widget overview — you -should use the GtkTreeView widget. -(A list is just a tree with no branches, so the tree widget is used -for lists as well.) Do not use the deprecated widgets GtkTree or GtkCList/GtkCTree in newly-written code, they are +should use the #GtkTreeView widget. (A list is just a tree with no branches, +so the tree widget is used for lists as well.) Do not use the deprecated +widgets #GtkTree or #GtkCList/#GtkCTree in newly-written code, they are less flexible and result in an inferior user interface. @@ -577,17 +545,13 @@ less flexible and result in an inferior user interface. See text widget overview — you -should use the GtkTextView widget. -Do not use the deprecated widget GtkText in newly-written code, it has a -number of problems that are best avoided. +should use the #GtkTextView widget. Do not use the deprecated widget #GtkText +in newly-written code, it has a number of problems that are best avoided. -If you only have a small amount of text, GtkLabel may also be appropriate of course. -It can be made selectable with -gtk_label_set_selectable(). For a single-line text entry, -see GtkEntry. +If you only have a small amount of text, #GtkLabel may also be appropriate of course. +It can be made selectable with gtk_label_set_selectable(). For a single-line text +entry, see #GtkEntry. @@ -600,11 +564,9 @@ see GtkEntry. -GtkImage can display images -in just about any format GTK+ understands. You can also -use GtkDrawingArea if you need -to do something more complex, such as draw text or graphics over the -top of the image. +#GtkImage can display images in just about any format GTK+ understands. You can also +use #GtkDrawingArea if you need to do something more complex, such as draw text or +graphics over the top of the image. @@ -617,31 +579,16 @@ would use a combo box? -With GTK+, a GtkOptionMenu is -recommended instead of a combo box, if the user is selecting from a -fixed set of options. That is, non-editable combo boxes are not -encouraged. GtkOptionMenu is -much easier to use than GtkCombo -as well. Use GtkCombo only when you -need the editable text entry. - - -(As a future enhancement to GTK+, a new widget to replace GtkOptionMenu and GtkCombo is planned. This widget will be -themeable to look like either a combo box or the current option menu, -and will address some shortcomings in the GtkCombo API. Bug -50554 tracks this issue, if you want to check status or post -comments.) +With GTK+, a #GtkComboBox is the recommended widget to use for this use case. +This widget looks like either a combo box or the current option menu, depending +on the current theme. If you need an editable text entry, use #GtkComboBoxEntry. -<link linkend="GtkWidget">GtkWidget</link> +#GtkWidget @@ -649,23 +596,16 @@ How do I change the color of a widget? -See gtk_widget_modify_fg(), -gtk_widget_modify_bg(), -gtk_widget_modify_base(), -and gtk_widget_modify_text(). See -GTK+ resource files for more -discussion. You can also change widget color by installing a resource -file and parsing it with gtk_rc_add_default_file(). +See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(), +and gtk_widget_modify_text(). See GTK+ +resource files for more discussion. You can also change widget color by +installing a resource file and parsing it with gtk_rc_add_default_file(). The advantage of a resource file is that users can then override the color you've chosen. -To change the background color for widgets such as GtkLabel that have no background, place them -in a GtkEventBox and set the -background of the event box. +To change the background color for widgets such as #GtkLabel that have no +background, place them in a #GtkEventBox and set the background of the event box. @@ -675,36 +615,32 @@ How do I change the font of a widget? -This has several possible answers, depending on what exactly you want to -achieve. One option is gtk_widget_modify_font(). Note that this function can be used to change only the font size, as in the following example: +This has several possible answers, depending on what exactly you want to achieve. +One option is gtk_widget_modify_font(). Note that this function can be used to +change only the font size, as in the following example: - PangoFontDesc *font_desc = pango_font_description_new (); + PangoFontDesc *font_desc = pango_font_description_new (); pango_font_description_set_size (font_desc, 40); gtk_widget_modify_font (widget, font); pango_font_description_free (font_desc); -If you want to make the text of a label larger, you can use gtk_label_set_markup(): +If you want to make the text of a label larger, you can use gtk_label_set_markup(): gtk_label_set_markup (label, "<big>big text</big>"); This is preferred for many apps because it's a relative size to the -user's chosen font size. See g_markup_escape_text() -if you are constructing such strings on the fly. +user's chosen font size. See g_markup_escape_text() if you are constructing such +strings on the fly. You can also change the font of a widget by putting gtk-font-name = "Sans 30" -in a resource file and parsing it with gtk_rc_add_default_file(). -The advantage of a resource file is that users can then override the -font you've chosen. See +in a resource file and parsing it with gtk_rc_add_default_file(). The advantage of +a resource file is that users can then override the font you've chosen. See GTK+ resource files for more discussion. @@ -717,15 +653,14 @@ How do I disable/ghost/desensitize a widget? In GTK+ a disabled widget is termed "insensitive." See -gtk_widget_set_sensitive(). +gtk_widget_set_sensitive(). -<link linkend="GtkTextView">GtkTextView</link> +#GtkTextView @@ -733,13 +668,8 @@ How do I get the contents of the entire text widget as a string? - -See gtk_text_buffer_get_bounds() - and gtk_text_buffer_get_text() -or gtk_text_iter_get_text(). +See gtk_text_buffer_get_bounds() and gtk_text_buffer_get_text() +or gtk_text_iter_get_text(). @@ -762,12 +692,13 @@ 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. +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. +To ensure that all text has the desired appearance, use gtk_widget_modify_font() +to change the default font for the widget. @@ -781,21 +712,17 @@ 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 +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(). +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. +gtk_text_view_scroll_to_mark() to scroll to the "insert" mark after inserting new text. @@ -803,7 +730,7 @@ To ensure that the end of the buffer remains visible, use -<link linkend="GtkTreeView">GtkTreeView</link> +#GtkTreeView @@ -812,28 +739,25 @@ How do I associate some data with a row in the tree? -Remember that the GtkTreeModel -columns don't necessarily have to be displayed. So you can put -non-user-visible data in your model just like any other data, and -retrieve it with gtk_tree_model_get(). -See the tree widget overview. +Remember that the #GtkTreeModel columns don't necessarily have to be displayed. +So you can put non-user-visible data in your model just like any other data, and +retrieve it with gtk_tree_model_get(). See the +tree widget overview. -What's the GtkTreeView equivalent of -gtk_clist_find_row_from_data()? +What's the #GtkTreeView equivalent of gtk_clist_find_row_from_data()? -As there is no separate data column in the GtkTreeModel, there's no +As there is no separate data column in the #GtkTreeModel, there's no built in function to find the iter from data. You can write a custom searching function to walk the tree and find the data, or use -gtk_tree_model_foreach(). +gtk_tree_model_foreach(). @@ -845,53 +769,36 @@ How do I put an image and some text in the same column? -You can pack more than one GtkCellRenderer into a single -GtkTreeViewColumn using -gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). So pack both a GtkCellRendererPixbuf -and a GtkCellRendererText into the -column. +You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn using +gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). So pack both +a #GtkCellRendererPixbuf and a #GtkCellRendererText into the column. -I can set data easily on my GtkTreeStore/GtkListStore models using gtk_list_store_set() and gtk_tree_store_set(), but can't read - it back? +I can set data easily on my #GtkTreeStore/#GtkListStore models using +gtk_list_store_set() and gtk_tree_store_set(), but can't read it back? -Both the GtkTreeStore and the GtkListStore implement the - GtkTreeModel - interface. Consequentially, the can use any function - this interface implements. The easiest way to read a - set of data back is to use - gtk_tree_model_get(). +Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel +interface. Consequentially, the can use any function this interface implements. +The easiest way to read a set of data back is to use gtk_tree_model_get(). -How do I change the way that numbers are formatted by GtkTreeView? +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()). +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()). @@ -937,15 +844,15 @@ set_up_new_columns (GtkTreeView *myview) gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns)); /* Create a GtkCellRendererText */ - renderer = gtk_cell_renderer_text_new (); + 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 (); + column = gtk_tree_view_column_new (); gtk_tree_view_column_set_title (column, "Example column"); - renderer = gtk_cell_renderer_text_new (); + 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. */ @@ -972,7 +879,7 @@ How do I hide the expander arrows in my tree view ? Set the expander-column property of the tree view to a hidden column. -See gtk_tree_view_set_expander_column() and gtk_tree_view_column_set_visible(). +See gtk_tree_view_set_expander_column() and gtk_tree_view_column_set_visible(). diff --git a/docs/reference/gtk/text_widget.sgml b/docs/reference/gtk/text_widget.sgml index e89bd3666d..88a766e388 100644 --- a/docs/reference/gtk/text_widget.sgml +++ b/docs/reference/gtk/text_widget.sgml @@ -6,7 +6,8 @@ -Text Widget OverviewOverview of GtkTextBuffer, GtkTextView, and friends +Text Widget Overview +Overview of #GtkTextBuffer, #GtkTextView, and friends @@ -14,11 +15,9 @@ GTK+ has an extremely powerful framework for multiline text editing. The -primary objects involved in the process are GtkTextBuffer, which represents the text being -edited, and GtkTextView, a widget which can -display a GtkTextBuffer. Each buffer can -be displayed by any number of views. +primary objects involved in the process are #GtkTextBuffer, which represents the +text being edited, and #GtkTextView, a widget which can display a #GtkTextBuffer. +Each buffer can be displayed by any number of views. @@ -38,15 +37,12 @@ be called "bold" and make the text inside the tag bold. However, the tag concept is more general than that; tags don't have to affect appearance. They can instead affect the behavior of mouse and key presses, "lock" a range of text so the user can't edit it, or countless other things. A tag is -represented by a -GtkTextTag object. One GtkTextTag can be applied to any number of text -ranges in any number of buffers. +represented by a #GtkTextTag object. One #GtkTextTag can be applied to any number +of text ranges in any number of buffers. -Each tag is stored in a GtkTextTagTable. A tag table defines a set of +Each tag is stored in a #GtkTextTagTable. A tag table defines a set of tags that can be used together. Each buffer has one tag table associated with it; only tags from that tag table can be used with the buffer. A single tag table can be shared between multiple buffers, however. @@ -60,9 +56,8 @@ is convenient if you're creating tags on-the-fly). Most text manipulation is accomplished with iterators, -represented by a GtkTextIter. An iterator -represents a position between two characters in the text buffer. GtkTextIter is a struct designed to be allocated +represented by a #GtkTextIter. An iterator represents a position between two +characters in the text buffer. #GtkTextIter is a struct designed to be allocated on the stack; it's guaranteed to be copiable by value and never contain any heap-allocated data. Iterators are not valid indefinitely; whenever the buffer is modified in a way that affects the number of characters in the buffer, all @@ -73,11 +68,10 @@ number of characters you pass through a state with a different number). Because of this, iterators can't be used to preserve positions across buffer -modifications. To preserve a position, the GtkTextMark object is ideal. You can think of a -mark as an invisible cursor or insertion point; it floats in the buffer, saving -a position. If the text surrounding the mark is deleted, the mark remains in -the position the text once occupied; if text is inserted at the mark, the +modifications. To preserve a position, the #GtkTextMark object is ideal. You can +think of a mark as an invisible cursor or insertion point; it floats in the buffer, +saving a position. If the text surrounding the mark is deleted, the mark remains +in the position the text once occupied; if text is inserted at the mark, the mark ends up either to the left or to the right of the new text, depending on its gravity. The standard text cursor in left-to-right languages is a mark with right gravity, because it stays to the right of @@ -86,21 +80,18 @@ inserted text. Like tags, marks can be either named or anonymous. There are two marks built-in -to GtkTextBuffer; these are named -"insert" and "selection_bound" and refer -to the insertion point and the boundary of the selection which is not the -insertion point, respectively. If no text is selected, these two marks will be -in the same position. You can manipulate what is selected and where the cursor -appears by moving these marks around. +to #GtkTextBuffer; these are named "insert" and +"selection_bound" and refer to the insertion point and the +boundary of the selection which is not the insertion point, respectively. If no +text is selected, these two marks will be in the same position. You can manipulate +what is selected and where the cursor appears by moving these marks around. If you want to place the cursor in response to a user action, be sure to use -gtk_text_buffer_place_cursor(), -which moves both at once -without causing a temporary selection (moving one then the other temporarily -selects the range in between the old and new positions). +gtk_text_buffer_place_cursor(), which moves both at once without causing a +temporary selection (moving one then the other temporarily selects the range in +between the old and new positions). @@ -123,13 +114,12 @@ considered a line separator. Simple Example -The simplest usage of GtkTextView -might look like this: +The simplest usage of #GtkTextView might look like this: GtkWidget *view; GtkTextBuffer *buffer; - view = gtk_text_view_new (); + view = gtk_text_view_new (); buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view)); @@ -140,11 +130,10 @@ might look like this: * will be emitted, such as "changed", "insert_text", and so on. */ -In many cases it's also convenient to first create the buffer with gtk_text_buffer_new(), then create a -widget for that buffer with gtk_text_view_new_with_buffer(). -Or you can change the buffer the widget displays after the widget is created -with gtk_text_view_set_buffer(). +In many cases it's also convenient to first create the buffer with +gtk_text_buffer_new(), then create a widget for that buffer with +gtk_text_view_new_with_buffer(). Or you can change the buffer the widget +displays after the widget is created with gtk_text_view_set_buffer(). @@ -154,21 +143,13 @@ with gtk_text_view_set_buffer(). -There are two ways to affect text attributes in -GtkTextView. -You can change the default attributes for a given -GtkTextView, and you can -apply tags that change the attributes for a region of text. -For text features that come from the theme — such as -font and foreground color — use standard -GtkWidget -functions such as -gtk_widget_modify_font() -or -gtk_widget_modify_text(). -For other attributes there are dedicated methods on -GtkTextView such as -gtk_text_view_set_tabs(). +There are two ways to affect text attributes in #GtkTextView. +You can change the default attributes for a given #GtkTextView, and you can +apply tags that change the attributes for a region of text. For text features +that come from the theme — such as font and foreground color — use +standard #GtkWidget functions such as gtk_widget_modify_font() or +gtk_widget_modify_text(). For other attributes there are dedicated methods on +#GtkTextView such as gtk_text_view_set_tabs(). GtkWidget *view; @@ -178,7 +159,7 @@ For other attributes there are dedicated methods on GdkColor color; GtkTextTag *tag; - view = gtk_text_view_new (); + view = gtk_text_view_new (); buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view)); @@ -208,8 +189,7 @@ For other attributes there are dedicated methods on The gtk-demo application that comes with -GTK+ contains more example code for GtkTextView. +GTK+ contains more example code for #GtkTextView.