From 83f5e4868c7322ddcbb831dd72744da887e8d17f Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 2 Jan 2011 23:57:03 -0500 Subject: [PATCH] Drop no-longer-used migration docs --- .../gtk/migrating-ClientSideWindows.sgml | 64 --- .../gtk/migrating-GtkAboutDialog.sgml | 98 ---- docs/reference/gtk/migrating-GtkAction.sgml | 445 ------------------ .../reference/gtk/migrating-GtkAssistant.sgml | 178 ------- docs/reference/gtk/migrating-GtkBuilder.sgml | 102 ---- .../gtk/migrating-GtkColorButton.sgml | 54 --- docs/reference/gtk/migrating-GtkComboBox.sgml | 213 --------- .../gtk/migrating-GtkEntry-icons.sgml | 141 ------ .../gtk/migrating-GtkFileChooser.sgml | 163 ------- docs/reference/gtk/migrating-GtkIconView.sgml | 153 ------ .../gtk/migrating-GtkLabel-links.sgml | 24 - .../gtk/migrating-GtkLinkButton.sgml | 81 ---- .../gtk/migrating-GtkRecentChooser.sgml | 323 ------------- docs/reference/gtk/migrating-GtkTooltip.sgml | 66 --- 14 files changed, 2105 deletions(-) delete mode 100644 docs/reference/gtk/migrating-ClientSideWindows.sgml delete mode 100644 docs/reference/gtk/migrating-GtkAboutDialog.sgml delete mode 100644 docs/reference/gtk/migrating-GtkAction.sgml delete mode 100644 docs/reference/gtk/migrating-GtkAssistant.sgml delete mode 100644 docs/reference/gtk/migrating-GtkBuilder.sgml delete mode 100644 docs/reference/gtk/migrating-GtkColorButton.sgml delete mode 100644 docs/reference/gtk/migrating-GtkComboBox.sgml delete mode 100644 docs/reference/gtk/migrating-GtkEntry-icons.sgml delete mode 100644 docs/reference/gtk/migrating-GtkFileChooser.sgml delete mode 100644 docs/reference/gtk/migrating-GtkIconView.sgml delete mode 100644 docs/reference/gtk/migrating-GtkLabel-links.sgml delete mode 100644 docs/reference/gtk/migrating-GtkLinkButton.sgml delete mode 100644 docs/reference/gtk/migrating-GtkRecentChooser.sgml delete mode 100644 docs/reference/gtk/migrating-GtkTooltip.sgml diff --git a/docs/reference/gtk/migrating-ClientSideWindows.sgml b/docs/reference/gtk/migrating-ClientSideWindows.sgml deleted file mode 100644 index 017249c3e9..0000000000 --- a/docs/reference/gtk/migrating-ClientSideWindows.sgml +++ /dev/null @@ -1,64 +0,0 @@ - - - - - Migrating to client-side windows - - - In version 2.18, GDK has been changed to use client-side windows. This - means that there is no longer a 1-1 correspondence between #GdkWindows - and windows in the underlying window system. In particular, it is no - longer correct to assume that each window has an associated XID. - Code that makes this assumption can sometimes be fixed by calling - gdk_window_ensure_native() on the windows in question. - Calling gdk_x11_window_get_xid() (or GDK_WINDOW_XID()) from the - X11-specific API on a non-native window will explicitly call - gdk_window_ensure_native(), so old code using this will continue to - work. A small gotcha is that the GDK_WINDOW_XID() call is no longer a - trivial accessor for the XID of the window, and thus must not be called - from another thread without taking locking precautions. - - - - GDK looks for the GDK_NATIVE_WINDOWS environment variable - and makes all windows native if it is set. It also tries to be more - compatible with the way prior versions worked in some other ways. - - - - Some applications assume that they can just operate on the X windows - corresponding to their GDK windows without ever telling GDK. One - example that we've seen is changing the child window stacking order - using XRestackWindows(). Fixing this properly requires to fix the code - to use GDK functions to achieve whatever it is trying to achieve. - To make this easier in the case of stacking order changes, we've added - a gdk_window_restack() function. - - - - One change that can cause problems for some applications is that GDK - is more aggressive about optimizing away expose events. Code that does - more than just repainting exposed areas in response to expose events - may be affected by this. - - - - Problems can also occur when using cairo for drawing. One thing that can - go wrong is clip handling. You may not use cairo_reset_clip() on a - cairo_t on a cairo context created via gdk_cairo_create() or passed to - the GtkWidget::draw signal. - - - - Due to a weird API in XClearArea the gdk_window_clear_area() call handled - a specified width or height of zero to mean "to end of window" for - non-double-buffered drawing. This has been changed to be consistent with - the docs and what happens in the double-buffered case. All code in GTK+ - that relied on this has been fixed, but it is possible (although unlikely) - that third party applications rely on this. If you need to do this, just - implement it yourself using gdk_drawable_get_size(). - - - diff --git a/docs/reference/gtk/migrating-GtkAboutDialog.sgml b/docs/reference/gtk/migrating-GtkAboutDialog.sgml deleted file mode 100644 index 07c7ca1453..0000000000 --- a/docs/reference/gtk/migrating-GtkAboutDialog.sgml +++ /dev/null @@ -1,98 +0,0 @@ - - - - - Migrating from GnomeAbout to GtkAboutDialog - - - 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 - the GTK+ policy to have getters and setters for all widget properties, - but it isn't much more complex than GnomeAbout. - - - - To convert an application that uses GnomeAbout to - GtkAboutDialog, as a first step, replace calls - like - - const gchar *documentors[] = { - "Documenter 1", - "Documenter 2", - NULL - }; - - const gchar *documentors[] = { - "Author 1", - "Author 2", - NULL - }; - - GtkWidget *about = gnome_about_new ("GNOME Test Program", VERSION, - "(C) 1998-2001 The Free Software Foundation", - "Program to display GNOME functions.", - authors, - documenters, - _("translator-credits"), - "logo.png"); - - by something like - - GdkPixbuf *logo = gdk_pixbuf_new_from_file ("logo.png", NULL); - GtkWidget *about = g_object_new (GTK_TYPE_ABOUT_DIALOG, - "name", "GNOME Test Program", - "version", VERSION, - "copyright", "(C) 1998-2001 The Free Software Foundation", - "comments", "Program to display GNOME functions.", - "authors", authors, - "documenters", documenters, - "translator-credits", _("translator-credits"), - "logo", logo, - 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. - - - - Once you are done with the initial conversion, you may want to look into - using some of the features of GtkAboutDialog - which are not present in GnomeAbout. - - - You can specify license information with the - #GtkAboutDialog:license property - - - You can add separate credits for artists with the - #GtkAboutDialog:artists property - - - You can add a pointer to the website of your application, using the - #GtkAboutDialog:website and #GtkAboutDialog:website-label properties. - - - 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(). - - - - - - diff --git a/docs/reference/gtk/migrating-GtkAction.sgml b/docs/reference/gtk/migrating-GtkAction.sgml deleted file mode 100644 index 46a574805c..0000000000 --- a/docs/reference/gtk/migrating-GtkAction.sgml +++ /dev/null @@ -1,445 +0,0 @@ - - - - - - Federico - Mena-Quintero - -
- federico@ximian.com -
- - - - - Migrating from old menu and toolbar systems to GtkAction - - - Prior to GTK+ 2.4, there were several APIs in use to create menus - 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. - - -
- 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 - 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 - "activate" signal. - - - - #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 - document, such as "cut", "copy", "paste", and "print". - - - - Normal actions are simply commands, such as - FileSave or EditCopy. - Toggle actions can be active or inactive, such as - FormatBold or ViewShowRulers. - Radio actions define a set of items for which one and only one - can be active at a time, for example, { - ViewHighQuality, - ViewNormalQuality, - ViewLowQuality }. - -
- -
- 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 - 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 - 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. - -
- -
- Migrating from GnomeUIInfo - - - Prior to GTK+ 2.4, some applications used the GnomeUIInfo - mechanism from - <libgnomeui/gnome-app-helper.h> to - define their menus and toolbars. With it, a program decleres an - 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 - related functions, to create the appropriate widgets based on - these structures. - - - - A downside of this API is that the same structures are used to - 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 widget fields of the structures. - - - - Another disadvantage is that there is no automatic way to - synchronize the state of related controls. If there are toolbar - toogle buttons for "Bold", "Italic", "Underline", and also - corresponding menu items under "Format/Bold", etc., one has to - synchronize their toggled states by hand whenever the user - selects any one of them. - - - - Finally, there is no way to do menu and toolbar merging for - applications that require embedded components. - - - - To convert an application that uses GnomeUIInfo into the new - GtkAction mechanism, you need to do several things: - - - - - - Separate your existing GnomeUIInfo entries into normal - actions, toggle actions, and radio actions, and then create - 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 "shape" that your menus and toolbars will have; - it simply defines the set of commands that will appear in them. - - - - - Create an XML description of your menus and toolbars for use - 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. - - - - - 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. - - - - - - GnomeUIInfo Example - - - The following code shows a declaration of a simple menu bar to - be used with gnome_app_fill_menu() or similar. The menu hierarchy i - looks like this: - - - - - File - - Open - — - Exit - - - - - View - - Zoom In - Zoom Out - — - [ ] Full Screen - — - ( ) High Quality - ( ) Normal Quality - ( ) Low Quality - - - - - -static GnomeUIInfo file_menu_items[] = { - { GNOME_APP_UI_ITEM, "_Open", "Open a file", - open_callback, NULL, NULL, GNOME_APP_PIXMAP_STOCK, GTK_STOCK_OPEN, - 'o', GDK_CONTROL_MASK, NULL }, - { GNOME_APP_UI_SEPARATOR }, - { GNOME_APP_UI_ITEM, "E_xit", "Exit the program", - exit_callback, NULL, NULL, GNOME_APP_PIXMAP_STOCK, GTK_STOCK_QUIT, - 'q', GDK_CONTROL_MASK, NULL}, - { GNOME_APP_UI_ENDOFINFO } -}; - -static GnomeUIInfo view_radio_items[] = { - { GNOME_APP_UI_ITEM, "_High Quality", "Display images in high quality, slow mode", - high_quality_callback, NULL, NULL, GNOME_APP_PIXMAP_FILENAME, "high-quality.png", - 0, 0, NULL }, - { GNOME_APP_UI_ITEM, "_Normal Quality", "Display images in normal quality", - normal_quality_callback, NULL, NULL, GNOME_APP_PIXMAP_FILENAME, "normal-quality.png", - 0, 0, NULL }, - { GNOME_APP_UI_ITEM, "_Low Quality", "Display images in low quality, fast mode", - low_quality_callback, NULL, NULL, GNOME_APP_PIXMAP_FILENAME, "low-quality.png", - 0, 0, NULL }, - { GNOME_APP_UI_ENDOFINFO } -}; - -static GnomeUIInfo view_menu_items[] = { - { GNOME_APP_UI_ITEM, "Zoom _In", "Zoom into the image", - zoom_in_callback, NULL, NULL, GNOME_APP_PIXMAP_STOCK, GTK_STOCK_ZOOM_IN, - GDK_PLUS, 0, NULL }, - { GNOME_APP_UI_ITEM, "Zoom _Out", "Zoom away from the image", - zoom_out_callback, NULL, NULL, GNOME_APP_PIXMAP_STOCK, GTK_STOCK_ZOOM_OUT, - GDK_MINUS, 0, NULL }, - { GNOME_APP_UI_SEPARATOR }, - { GNOME_APP_UI_TOGGLEITEM, "_Full Screen", "Switch between full screen and windowed mode", - full_screen_callback, NULL, NULL, GNOME_APP_PIXMAP_NONE, NULL, - GDK_F11, 0, NULL }, - { GNOME_APP_UI_SEPARATOR }, - { GNOME_APP_UI_RADIOITEMS, NULL, NULL, view_radio_items }, - { GNOME_APP_UI_ENDOFINFO } -}; - -static GnomeUIInfo menubar[] = { - { GNOME_APP_UI_SUBTREE, "_File", NULL, file_menu_items }, - { GNOME_APP_UI_SUBTREE, "_View", NULL, view_menu_items }, - { GNOME_APP_UI_ENDOFINFO } -} - - - - - <structname>GtkActionEntry</structname> Structures - - - 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 gtk_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". - - - -/* Normal items */ -static const GtkActionEntry entries[] = { - { "FileMenu", NULL, "_File" }, - { "ViewMenu", NULL, "_View" }, - { "Open", GTK_STOCK_OPEN, "_Open", "<control>O", "Open a file", open_action_callback }, - { "Exit", GTK_STOCK_QUIT, "E_xit", "<control>Q", "Exit the program", exit_action_callback }, - { "ZoomIn", GTK_STOCK_ZOOM_IN, "Zoom _In", "plus", "Zoom into the image", zoom_in_action_callback }, - { "ZoomOut", GTK_STOCK_ZOOM_OUT, "Zoom _Out", "minus", "Zoom away from the image", zoom_out_action_callback }, -}; - -/* Toggle items */ -static const GtkToggleActionEntry toggle_entries[] = { - { "FullScreen", NULL, "_Full Screen", "F11", "Switch between full screen and windowed mode", full_screen_action_callback, FALSE } -}; - -/* Radio items */ -static const GtkRadioActionEntry radio_entries[] = { - { "HighQuality", "my-stock-high-quality", "_High Quality", NULL, "Display images in high quality, slow mode", 0 }, - { "NormalQuality", "my-stock-normal-quality", "_Normal Quality", NULL, "Display images in normal quality", 1 }, - { "LowQuality", "my-stock-low-quality", "_Low Quality", NULL, "Display images in low quality, fast mode", 2 } -}; - - - - - XML Description - - - 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 - example. Note that the File and - View menus have their names specified in - the action - entries, not in the XML itself. This is because the - XML description only contains identifiers - for the items in the GUI, rather than human-readable names. - - - -static const char *ui_description = -"<ui>" -" <menubar name='MainMenu'>" -" <menu action='FileMenu'>" -" <menuitem action='Open'/>" -" <menuitem action='Exit'/>" -" </menu>" -" <menu action='ViewMenu'>" -" <menuitem action='ZoomIn'/>" -" <menuitem action='ZoomOut'/>" -" <separator/>" -" <menuitem action='FullScreen'/>" -" <separator/>" -" <menuitem action='HighQuality'/>" -" <menuitem action='NormalQuality'/>" -" <menuitem action='LowQuality'/>" -" </menu>" -" </menubar>" -"</ui>"; - - - - - 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 XML description of the menu - layout. We will also extract the accelerator group and the - widgets from the #GtkUIManager put them into a window. - - - -GtkWidget *window; -GtkWidget *vbox; -GtkWidget *menubar; -GtkActionGroup *action_group; -GtkUIManager *ui_manager; -GtkAccelGroup *accel_group; -GError *error; - -register_my_stock_icons (); - -window = gtk_window_new (GTK_WINDOW_TOPLEVEL); - -vbox = gtk_vbox_new (FALSE, 0); -gtk_container_add (GTK_CONTAINER (window), vbox); - -action_group = gtk_action_group_new ("MenuActions"); -gtk_action_group_add_actions (action_group, entries, G_N_ELEMENTS (entries), window); -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 (); -gtk_ui_manager_insert_action_group (ui_manager, action_group, 0); - -accel_group = gtk_ui_manager_get_accel_group (ui_manager); -gtk_window_add_accel_group (GTK_WINDOW (window), accel_group); - -error = NULL; -if (!gtk_ui_manager_add_ui_from_string (ui_manager, ui_description, -1, &error)) - { - g_message ("building menus failed: %s", error->message); - g_error_free (error); - exit (EXIT_FAILURE); - } - -menubar = gtk_ui_manager_get_widget (ui_manager, "/MainMenu"); -gtk_box_pack_start (GTK_BOX (vbox), menubar, FALSE, FALSE, 0); - -gtk_widget_show_all (window); - - - - - Registering the icons - - - Here we show how the register_my_stock_icons() function - used in the previous example could look like. - - - -static struct { - gchar *filename; - gchar *stock_id; -} stock_icons[] = { - { "high-quality.png", "my-stock-high-quality" }, - { "normal-quality.png", "my-stock-normal-quality" }, - { "low-quality.png", "my-stock-low-quality" }, -}; - -static gint n_stock_icons = G_N_ELEMENTS (stock_icons); - -static void -register_my_stock_icons (void) -{ - GtkIconFactory *icon_factory; - GtkIconSet *icon_set; - GtkIconSource *icon_source; - gint i; - - 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 (); - 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); - gtk_icon_factory_add (icon_factory, stock_icons[i].stock_id, icon_set); - gtk_icon_set_unref (icon_set); - } - - gtk_icon_factory_add_default (icon_factory); - - g_object_unref (icon_factory); -} - - - -
- - - - diff --git a/docs/reference/gtk/migrating-GtkAssistant.sgml b/docs/reference/gtk/migrating-GtkAssistant.sgml deleted file mode 100644 index ef4fbfabcc..0000000000 --- a/docs/reference/gtk/migrating-GtkAssistant.sgml +++ /dev/null @@ -1,178 +0,0 @@ - - - - - - Carlos - Garnacho - -
- carlosg@gnome.org -
- - - - - Migrating from GnomeDruid to GtkAssistant - - - Since version 2.10, GTK+ provides the GtkAssistant widget as a replacement - for the GnomeDruid widget in the libgnomeui - library. - - - - Conceptually, both GtkAssistant and - GnomeDruid do the same task, but there are - several areas where the API has been completely redesigned, so this - chapter covers the main changes between both widgets. - - -
- Inserting pages - - - GnomeDruid was implemented as a container for - GnomeDruidPage abstract objects, which are - implemented by the GnomeDruidPageEdge and - GnomeDruidPageStandard widgets. Instead, - GtkAssistant allows any widget to be a page, - and implements per-page settings (such as page type or title) as - child properties. So instead of: - - - -/* Page 1 */ -page = gnome_druid_page_edge_new (GNOME_EDGE_START); -gnome_druid_page_edge_set_test (GNOME_DRUID_PAGE_EDGE (page), - "Welcome to the assistant, it will make your life easier"); -gtk_widget_show (page); -gnome_druid_append_page (GNOME_DRUID (druid), GNOME_DRUID_PAGE (page)); - -/* Page 2 */ -page = gnome_druid_page_standard_new (); -gtk_container_add (GTK_CONTAINER (GNOME_DRUID_PAGE_STANDARD (page)->vbox, - create_page1 ()); -gtk_widget_show_all (page); -gnome_druid_append_page (GNOME_DRUID (druid), GNOME_DRUID_PAGE (page)); - -/* Page 3 */ -page = gnome_druid_page_edge_new (GNOME_EDGE_FINISH); -gnome_druid_page_edge_set_test (GNOME_DRUID_PAGE_EDGE (page), - "Now you are done, your life is easier"); -gtk_widget_show (page); -gnome_druid_append_page (GNOME_DRUID (druid), GNOME_DRUID_PAGE (page)); - - - - You have to write: - - - -gtk_assistant_append_page (GTK_ASSISTANT (assistant), - gtk_label_new ("Welcome to the assistant, it will make your life easier")); -gtk_assistant_append_page (GTK_ASSISTANT (assistant), - create_page1 ()); -gtk_assistant_append_page (GTK_ASSISTANT (assistant), - gtk_label_new ("Now you are done, your life is easier"); - -
- -
- Decorating the assistant pages - - - To decorate your assistant pages, GtkAssistant provides similar functions - to GnomeDruid, so you have to transform code like this: - - - -gnome_druid_page_edge_set_title (GNOME_DRUID_PAGE_EDGE (page), "Welcome"); -gnome_druid_page_edge_set_logo (GNOME_DRUID_PAGE_EDGE (page), logo_pixbuf); -gnome_druid_page_edge_set_watermark (GNOME_DRUID_PAGE_EDGE (page), watermark_pixbuf); - - - - Into this: - - - -gtk_assistant_set_page_title (GTK_ASSISTANT (assistant), page_widget, "Welcome"); -gtk_assistant_set_page_header_image (GTK_ASSISTANT (assistant), page_widget, logo_pixbuf); -gtk_assistant_set_page_side_image (GTK_ASSISTANT (assistant), page_widget, watermark_pixbuf); - - - - Where page_widget is the widget used as a page. - -
- -
- Setting the page flow - - - Here is the area where GtkAssistant and GnomeDruid - differ the most. While GnomeDruid used the "next" and "back" signals from the - GnomeDruidPage, GtkAssistant uses the following - techniques: - - - - - gtk_assistant_set_forward_page_func (): Allows to define a GtkAssistantPageFunc to let the - assistant know which will be the following page given the current page. - - - gtk_assistant_set_page_complete (): Lets the assistant know whether the specified page is complete - or not, updating buttons state accordingly. - - - gtk_assistant_set_page_type (): Lets the assistant know the page role and update the buttons - state accordingly. Pages can have the following roles: - - Intro - Content - Progress - Confirmation - Summary - - - - - - A sample GtkAssistantPageFunc could look like this: - - - -static gint -forward_page_function (gint current_page, - gpointer data) -{ - switch (current_page) - { - case 0: - return 1; - case 1: - if (check_page1_data ()) - return 2; - else - return 3; - case 2: - return 3; - default: - return -1; - } -} - - -
- - - diff --git a/docs/reference/gtk/migrating-GtkBuilder.sgml b/docs/reference/gtk/migrating-GtkBuilder.sgml deleted file mode 100644 index 1fd843c8a6..0000000000 --- a/docs/reference/gtk/migrating-GtkBuilder.sgml +++ /dev/null @@ -1,102 +0,0 @@ - - - - - Migrating from libglade to GtkBuilder - - - Since version 2.12, GTK+ provides #GtkBuilder to construct - user interfaces from XML descriptions, similar to the functionality - provided by #GladeXML in the libglade library. - - - - A good way to start a migration from libglade to GtkBuilder is using - glade3 to convert your .glade file. - If your code uses the @root parameter of glade_xml_new(), - you can use gtk_builder_add_objects_from_file() to construct only certain - objects from a GtkBuilder file. - - - - Alternatively, GTK+ also offers the - gtk-builder-convert script you can use - to do the conversion; in which case you should be careful to inspect the output - and make sure you didn't lose any data. - - - - Step-by-step instructions for porting code from libglade to GtkBuilder - - - libgladeGtkBuilder - - - - ]]> - not needed - - - GladeXML* - GtkBuilder* - - - glade_xml_new (FILE, "first_widget", NULL) - - -GError* error = NULL; -GtkBuilder* builder = gtk_builder_new (); -if (!gtk_builder_add_from_file (builder, FILE, &error)) - { - g_warning ("Couldn't load builder file: %s", error->message); - g_error_free (error); - } - - - - - glade_xml_get_widget (gxml, “widget_name”) - GTK_WIDGET (gtk_builder_get_object (builder, “widget_name”)) - - - glade_get_widget_name (widget) - gtk_widget_get_name (widget) - - - glade_xml_get_widget_prefix (gxml, “prefix”) - can be emulated by gtk_builder_get_objects (builder) together with manual filtering. It returns a GSList* instead of a GList* though. - - - -
- - - While GtkBuilder strives to be a complete replacement for - libglade, there are a number of areas where it is currently - still behind libglade: - - - - GtkBuilder supports context information in translatable - properties in a slightly different way than libglade. - Intltool does not yet support this; see - bug - 454894 for the current status of intltool support for - GtkBuilder files. Thankfully, context in translations is a - rarely used feature, and if you are not using it, intltools - glade format support works just fine for GtkBuilder files. - - - - While libglade can often tolerate multiple widgets having the - same id in a glade file, GtkBuilder will not accept duplicate - object ids. Both gtk-builder-convert - and the GtkBuilder parser emit warnings when they see - duplicate ids. - - - - - diff --git a/docs/reference/gtk/migrating-GtkColorButton.sgml b/docs/reference/gtk/migrating-GtkColorButton.sgml deleted file mode 100644 index be0e8b1d0c..0000000000 --- a/docs/reference/gtk/migrating-GtkColorButton.sgml +++ /dev/null @@ -1,54 +0,0 @@ - - - - - Migrating from GnomeColorPicker to GtkColorButton - - - Since version 2.6, GTK+ provides the #GtkColorButton - widget as a replacement for the GnomeColorPicker - widget in the libgnomeui library. - - - - Porting an application from GnomeColorPicker to - GtkColorButton is very simple. - GtkColorButton doesn't support dithering - (since it is rarely needed on modern hardware), and it doesn't have - setters and getters to set the color from floating point or integer - components. So instead of - - guint red, green, blue, alpha; - /* ... */ - gnome_color_picker_set_i8 (color_picker, red, green, blue, alpha); - - you have to write - - GdkColor color; - - color.red = red << 8; - color.green = green << 8; - color.blue = blue << 8; - gtk_color_button_set_color (color_picker, &color); - gtk_color_button_set_alpha (color_picker, alpha << 8); - - and similarly for the setters taking other number formats. For - gnome_color_picker_set_i16() no conversion is needed, - for gnome_color_picker_set_d(), you need to convert - the color components like this: - - color.red = (guint16) (red * 65535.0 + 0.5); - color.green = (guint16) (green * 65535.0 + 0.5); - color.blue = (guint16) (blue * 65535.0 + 0.5); - - - - - diff --git a/docs/reference/gtk/migrating-GtkComboBox.sgml b/docs/reference/gtk/migrating-GtkComboBox.sgml deleted file mode 100644 index 4114bdc15a..0000000000 --- a/docs/reference/gtk/migrating-GtkComboBox.sgml +++ /dev/null @@ -1,213 +0,0 @@ - - - - - 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. - - - In GTK+ 2.4, a unified API for list selection was introduced, with - #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 - the style property #GtkComboBox:appears-as-list. - - -
- Migrating from GtkOptionMenu to GtkComboBox - - - Here is an example of a simple, but typical use of - #GtkOptionMenu: - -GtkWidget *option_menu, *menu, *menu_item; - -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); -gtk_widget_show (menu_item); -menu_item = gtk_menu_item_new_with_label ("Second Item"); -gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); -gtk_widget_show (menu_item); -menu_item = gtk_menu_item_new_with_label ("Third Item"); -gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); -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 #GtkOptionMenu::changed - 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: - -GtkWidget *combo_box; - -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 - #GtkComboBox::changed signal and use gtk_combo_box_get_active() - to retrieve the index of the selected item. - - - - A slightly more complex example involving images: - -GtkWidget *option_menu, *menu, *menu_item; - -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)); -gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); -gtk_widget_show (menu_item); -menu_item = gtk_image_menu_item_new_with_label ("Second Item"); -gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf2)); -gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); -gtk_widget_show (menu_item); -menu_item = gtk_image_menu_item_new_with_label ("Third Item"); -gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf3)); -gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item); -gtk_widget_show (menu_item); - -gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu); - - - - can be done using a #GtkComboBox as follows: - -GtkListStore *store; -GtkTreeIter iter; -GtkCellRenderer *renderer; -GtkWidget *combo_box; - -store = gtk_list_store_new (2, GDK_TYPE_PIXBUF, G_TYPE_STRING); - -gtk_list_store_append (store, &iter); -gtk_list_store_set (store, &iter, 0, pixbuf1, 1, "First Item", -1); -gtk_list_store_append (store, &iter); -gtk_list_store_set (store, &iter, 0, pixbuf2, 1, "Second Item", -1); -gtk_list_store_append (store, &iter); -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 (); -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 (); -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, - NULL); - - -
- -
- Migrating from GtkCombo to GtkComboBoxEntry - - - Here is an example of a simple, but typical use of a #GtkCombo: - -GtkWidget *combo; -GList *items = NULL; - -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 (); -gtk_combo_set_popdown_strings (GTK_COMBO (combo), items); - - In order to react to the user's selection, connect to the #GtkCombo::changed - signal on the combo and use - gtk_entry_get_text (GTK_ENTRY (combo->entry)) - to retrieve the selected text. - - - And here is how it would be done using #GtkComboBoxEntry: - -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"); -gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item"); - - In order to react to the user's selection, connect to the #GtkComboBox::changed - signal on the combo and use - gtk_entry_get_text (GTK_ENTRY (GTK_BIN (combo_box)->child)) - to retrieve the selected text. - -
- -
- New features - - - The new widgets have more to offer than a mere combination of the - features of #GtkOptionMenu and #GtkCombo. Notable new features - include: - - - Grid mode - Sometimes it is preferable to display the available - options not in a linear list, but in a grid. A typical example - 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(). - - - - 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 - 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. - - - - 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. - - - - -
- - - - diff --git a/docs/reference/gtk/migrating-GtkEntry-icons.sgml b/docs/reference/gtk/migrating-GtkEntry-icons.sgml deleted file mode 100644 index 93e21b5356..0000000000 --- a/docs/reference/gtk/migrating-GtkEntry-icons.sgml +++ /dev/null @@ -1,141 +0,0 @@ - - - - - Migrating from SexyIconEntry to GtkEntry - - - GTK+ 2.16 supports showing icons inside a #GtkEntry, similar to - SexyIconEntry. Porting from SexyIconEntry to GtkEntry is relatively - straightforward. The main difference between the two APIs is that - SexyIconEntry uses #GtkImage widgets in a somewhat awkward way as - storage vehicles for icons, while GtkEntry allows to specify icons - via pixbufs, stock ids, icon names or #GIcons. So, if your code uses - e.g.: - -image = gtk_image_new_from_stock (GTK_STOCK_NEW, GTK_ICON_SIZE_MENU); -sexy_icon_entry_set_icon (entry, SEXY_ICON_ENTRY_PRIMARY, image); - - you can get rid of the @image, and directly write: - -gtk_entry_set_icon_from_stock (entry, GTK_ENTRY_ICON_PRIMARY, GTK_STOCK_NEW); - - - - - The signals SexyIconEntry::icon-pressed and SexyIconEntry::icon-released - have been renamed to #GtkEntry::icon-press and #GtkEntry::icon-release - to avoid problems due to signal name clashes. Also, the signature of the - signals has changed from - -void (*icon_pressed) (SexyIconEntry *entry, - SexyIconEntryPosition icon_pos, - int button) - -to - -void (*icon_press) (GtkEntry *entry, - GtkEntryIconPosition icon_pos, - GdkEventButton *event) - - The new signature has the advantage that the signal handler can use - the timestamp of the event, e.g. for passing it to gtk_menu_popup(). - When adapting an existing signal handler to the new signature, you - should note that the button number is easily available as @event->button, - as shown in the following example: - -static void -icon_pressed_cb (SexyIconEntry *entry, - SexyIconEntryPosition position, - int button, - gpointer data) -{ - GtkMenu *menu = data; - - if (position == SEXY_ICON_ENTRY_PRIMARY) - gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL, - button, GDK_CURRENT_TIME); -} - - can be ported as: - -static void -icon_press_cb (GtkEntry *entry, - GtkEntryIconPosition position, - GdkEventButton *event, - gpointer data) -{ - GtkMenu *menu = data; - - if (position == GTK_ENTRY_ICON_PRIMARY) - gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL, - event->button, event->time); -} - - - - - Another difference is that SexyIconEntry offers manual control of - the icon prelighting, via sexy_icon_entry_set_icon_highlight(). - #GtkEntry prelights automatically when appropriate, depending on - whether the icon is activatable and sensitive. You should make - sure that your icons are properly marked as activatable or nonactivatable - and sensitive or insensitive: - - - Sensitive, but non-activatable icons are - good for purely informational purposes. - - - Icons should be marked as insensitive if the - function that they trigger is currently not available. - - - - - - GtkEntry has no direct equivalent of the special-purpose function - sexy_icon_entry_add_clear_button(). If you need this functionality, - the following code works: - -static void -icon_pressed_cb (GtkEntry *entry, - gint position, - GdkEventButton *event, - gpointer data) -{ - if (position == GTK_ENTRY_ICON_SECONDARY) - gtk_entry_set_text (entry, ""); -} - -static void -text_changed_cb (GtkEntry *entry, - GParamSpec *pspec, - GtkWidget *button) -{ - gboolean has_text; - - has_text = gtk_entry_get_text_length (entry) > 0; - gtk_entry_set_icon_sensitive (entry, - GTK_ENTRY_ICON_SECONDARY, - has_text); -} - - - /* ... */ - - /* Set up the clear icon */ - gtk_entry_set_icon_from_stock (GTK_ENTRY (entry), - GTK_ENTRY_ICON_SECONDARY, - GTK_STOCK_CLEAR); - g_signal_connect (entry, "icon-press", - G_CALLBACK (icon_pressed_cb), NULL); - g_signal_connect (entry, "notify::text", - G_CALLBACK (text_changed_cb), find_button); - - /* ... */ - - - diff --git a/docs/reference/gtk/migrating-GtkFileChooser.sgml b/docs/reference/gtk/migrating-GtkFileChooser.sgml deleted file mode 100644 index 731086af81..0000000000 --- a/docs/reference/gtk/migrating-GtkFileChooser.sgml +++ /dev/null @@ -1,163 +0,0 @@ - - - - - - Federico - Mena-Quintero - -
- federico@ximian.com -
- - - - - 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 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. - - -
- 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 - 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 - existing files or for saving to a possibly new file. - - - - Please see for - how to create a simple file chooser dialog and extract the - selected filename from it. - -
- -
- 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 - 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_uris() to get a list of URI strings. - - - - 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 - 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 - "File/Open"), or to type in new filenames (for - "File/Save As..."). - -
- -
- Installing a Preview widget - - - 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 - dedicated API to do this. - - - - Please see the section on - creating preview widgets for more information. - -
- -
- Installing Extra Widgets - - - Some applications need to install extra widgets in a file - chooser. For example, an application may want to provide a - toggle button to give the user the option of opening a file - read-only. - - - - Please see the section on - creating extra widgets for more information. - -
- -
- New features - - - 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. - - - - - - Present a list of application-specific shortcut folders. - For example, a paint program may want to add a shortcut for - its /usr/share/paint_program/Clipart - folder. - - - - - - Define custom filters so that not all the files in a folder - are listed. For example, you could filter out backup files, - or show only image files. - - - - - - 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 deleted file mode 100644 index f1fe85264e..0000000000 --- a/docs/reference/gtk/migrating-GtkIconView.sgml +++ /dev/null @@ -1,153 +0,0 @@ - - - - - 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 - 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 - and images of the icons) with other views. - - - - #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. - GnomeIconList lets you directly insert data with - 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: - - void - fill_icon_list (GnomeIconList *icon_list) - { - gnome_icon_list_append (icon_list, "file1.png", "Icon 1"); - gnome_icon_list_append (icon_list, "file2.png", "Icon 2"); - - /* more icons ... */ - } - - you will have to create a tree model, attach your icon view to it, and - fill the model: - - enum { - PIXBUF_COLUMN, - TEXT_COLUMN, - - /* you can have more columns here, e.g */ - - DATA_COLUMN - }; - - void - fill_model (GtkListStore *store) - { - GtkTreeIter iter; - GdkPixbuf *pixbuf; - - gtk_list_store_append (store, &iter); - pixbuf = gdk_pixbuf_new_from_file ("file1.png", NULL); - gtk_list_store_set (store, &iter, PIXBUF_COLUMN, pixbuf, TEXT_COLUMN, "Icon 1", -1); - g_object_unref (pixbuf); - - gtk_list_store_append (store, &iter); - pixbuf = gdk_pixbuf_new_from_file ("file2.png", NULL); - gtk_list_store_set (store, &iter, PIXBUF_COLUMN, pixbuf, TEXT_COLUMN, "Icon 2", -1); - g_object_unref (pixbuf); - - /* more icons ... */ - } - - int - main (int argc, char *argv[]) - { - GtkWidget *icon_view; - GtkListStore *store; - - gtk_init (&argc, &argv); - - /* do other initialization... */ - - /* construct the GtkIconView */ - icon_view = gtk_icon_view_new (); - store = 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); - gtk_icon_view_set_text_column (GTK_ICON_VIEW (icon_view), TEXT_COLUMN); - gtk_icon_view_set_model (GTK_ICON_VIEW (icon_view), GTK_TREE_MODEL (store)); - - fill_model (store); - - /* ... */ - } - - 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 - conveniently stored in an extra column in the tree model, so you would - call a function like - - void - set_icon_data (GtkIconView *icon_view, - gint idx, - gpointer data) - { - GtkTreeModel *model; - GtkTreeIter iter; - - model = gtk_icon_view_get_model (icon_view); - - if (gtk_tree_model_iter_nth_child (model, &iter, NULL, idx)) - gtk_list_store_set (GTK_LIST_STORE (model), &iter, - DATA_COLUMN, data, -1); - } - - assuming that your tree model has a DATA_COLUMN of type - %G_TYPE_POINTER. - - - - There is a number of minor API differences between - GnomeIconList and - GtkIconView: - - - GnomeIconListMode is replaced by the - orientation - property of GtkIconView - - - 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 - replace the whole model of a GtkIconView, - instead of doing many small changes to the existing model. - - - - - - diff --git a/docs/reference/gtk/migrating-GtkLabel-links.sgml b/docs/reference/gtk/migrating-GtkLabel-links.sgml deleted file mode 100644 index 350aa8fb3f..0000000000 --- a/docs/reference/gtk/migrating-GtkLabel-links.sgml +++ /dev/null @@ -1,24 +0,0 @@ - - - - - Migrating from SexyUrlLabel to GtkLabel - - - GTK+ 2.18 supports showing links inside a #GtkLabel, similar to - SexyUrlLabel. Porting from SexyUrlLabel to GtkLabel is relatively - straightforward. GtkLabel accepts links in the markup using the - same HTML a notation that SexyUrlLabel uses. In addition - to the href attribute, GtkLabel accepts a title attribute that - is displayed as a tooltip on the link. Instead of - sexy_url_label_set_markup(), just call gtk_label_set_markup(). - - - One difference between the two APIs is that the ::url-activated signal - from SexyUrlLabel has been replaced by the #GtkLabel::activate-link - signal. The need for connecting to this signal is greatly reduced, - since GtkLabel has a default handler that calls gtk_show_uri(). - - diff --git a/docs/reference/gtk/migrating-GtkLinkButton.sgml b/docs/reference/gtk/migrating-GtkLinkButton.sgml deleted file mode 100644 index a4c003e05a..0000000000 --- a/docs/reference/gtk/migrating-GtkLinkButton.sgml +++ /dev/null @@ -1,81 +0,0 @@ - - - - - Migrating from GnomeHRef to GtkLinkButton - - - Since version 2.10, GTK+ provides the #GtkLinkButton widget as a - replacement for the GnomeHRef widget - in the libgnomeui library. - - - - Porting an application from GnomeHRef to - #GtkLinkButton is very simple. #GtkLinkButton does not have a - default action for #GtkButton::clicked signal. So instead of simply - creating the widget - - GtkWidget *button; - - button = gnome_href_new (url, ""); - - you will have to handle the activation of the #GtkLinkButton, using - the ::clicked signal for instance - - static void - link_button_clicked_cb (GtkWidget *widget, - gpointer data) - { - const gchar *link; - - link = gtk_link_button_get_uri (GTK_LINK_BUTTON (widget)); - open_browser_at_url (link); - } - - /* ... */ - - GtkWidget *button; - - button = gtk_link_button_new (url); - g_signal_connect (button, "clicked", - G_CALLBACK (link_button_clicked_cb), NULL); - - If you have more than one #GtkLinkButton instead of connecting - a signal to each one, you can use a "hook function" which will be - called whenever a user activates a link button - - static void - link_button_hook (GtkLinkButton *button, - const gchar *link, - gpointer user_data) - - { - open_browser_at_url (link); - } - - /* ... */ - - GtkWidget *button1 = gtk_link_button_new (uri1); - GtkWidget *button2 = gtk_link_button_new (uri2); - - gtk_link_button_set_uri_hook (link_button_hook, NULL, NULL); - - - - - - Starting with GTK+ 2.16, it is no longer necessary to set up a uri hook - manually, since GTK+ now defaults to calling gtk_show_uri() if no uri - hook has been set. - - - - diff --git a/docs/reference/gtk/migrating-GtkRecentChooser.sgml b/docs/reference/gtk/migrating-GtkRecentChooser.sgml deleted file mode 100644 index 039c461a6c..0000000000 --- a/docs/reference/gtk/migrating-GtkRecentChooser.sgml +++ /dev/null @@ -1,323 +0,0 @@ - - - - - - Emmanuele - Bassi - -
- ebassi@gmail.com -
- - - - - Migrating from EggRecent to GtkRecentChooser - - - Since version 2.10, GTK+ provides a way of handling the recently used - documents. It is similar to the code that has lived inside the libegg - library and has been incorporated by many applications. The GTK+ version - aims to completely replace that code, and offers many distinctive features - that improve the registration and visualization of the recently used - documents, such as: - - - - - - Better performances while reading and writing the list of recently used - files - - - More meta-data available for each recent document, like the - applications that have registered a document inside the list, the last - time and the number of times the same application did register a - document inside the list, an optional user readable name and - description of the document - - - Improved the ability to sort and filter the documents, also using - custom sorting and filtering functions - - - New widgets for displaying the list, and better integration with - current #GtkFileChooser and #GtkUIManager widgets - - - - -
- Managing the Recently Used Documents - - - #GtkRecentManager is used to manage the Recently Used Documents. To - create a new #GtkRecentManager, you simply call gtk_recent_manager_new(). - Like the EggRecentModel inside EggRecent, the - #GtkRecentManager loads the list of the recent documents and notifies - you of changes inside the list. - - - - Usually, instead of creating a new #GtkRecentManager each time you - need it, you'll want to use the gtk_recent_manager_get_default() - function. - - - - To add a document to the list, you can use gtk_recent_manager_add_item(), - like: - - GtkRecentManager *manager; - - manager = gtk_recent_manager_new (); - - if (!gtk_recent_manager_add_item (manager, document_uri)) - { - /* warn about the error */ - } - - g_object_unref (manager); - - The gtk_recent_manager_add_item() function will try and guess some of the - meta-data associated to a URI. If you know some of meta-data about the - document yourself, set the desired fields of a #GtkRecentData structure - and pass it to the gtk_recent_manager_add_full() function instead: - - GtkRecentManager *manager; - GtkRecentData *recent_data; - - manager = gtk_recent_manager_new (); - - recent_data = g_new0 (GtkRecentData, 1); - /* the user visible name of the document (maybe its title); should - * be preferred when displaying the item into the list - */ - recent_data->display_name = document_name; - - /* the MIME type is mandatory */ - recent_data->mime_type = document_mime_type; - - /* the name of the application that is registering the document - * (also mandatory); usually, the same name you used with - * the g_set_application_name () function. - */ - recent_data-&app_name = APP_NAME; - - /* the command to open a file; the %u string will be automagically - * expanded to the document's URI when getting the application's - * command line from the GtkRecentInfo object with - * gtk_recent_info_get_application_info () - */ - recent_data-&app_exec = g_strjoin (" ", g_get_prgname (), "--open-file", "%u", NULL); - - if (!gtk_recent_manager_add_full (manager, document_uri, recent_data)) - { - /* warn about the error */ - } - - g_free (recent_data->app_exec); - g_free (recent_data); - g_object_unref (manager); - - - - - Getting the list of items is also similar to - EggRecentModel; the GtkRecentInfo data is - allocated at look up time in order not to waste memory keeping it - around, so you must remember to free the data inside the list and then - the list itself when you are done using it: - - GtkRecentManager *manager; - GList *recent_items, *l; - - manager = gtk_recent_manager_get_default(); - - recent_items = gtk_recent_manager_get_items (manager); - for (l = recent_items; l != NULL; l = l->next) - { - GtkRecentInfo *recent_info = l->data; - - do_something_with_the_item (recent_info); - } - - /* free everything and the list */ - g_list_foreach (recent_items, (GFunc) gtk_recent_info_unref, NULL); - g_list_free (recent_items); - - You can also look up a single item: - - GtkRecentInfo *recent_info; - GError *error = NULL; - - recent_info = gtk_recent_manager_lookup_item (manager, document_uri, &error); - if (error) - { - display_error (error); - - g_error_free (error); - } - else - { - do_something_with_the_item (recent_info); - - gtk_recent_info_unref (recent_info); - } - - The #GtkRecentInfo is a reference counted boxed type, and it holds all - the meta-data of a recently used document, like its display name, its - description, the list of each application that has registered the - document or the list of groups to which the document belong. - - -
- -
- Displaying the Recently Used Documents - - - Displaying the Recently Used Documents list is handled by any widget - implementing the #GtkRecentChooser interface. These widgets also handle - the sorting and filtering of the list; they will create their own - #GtkRecentManager objects by default: - - GtkWidget *chooser; - gint response; - - /* create a new dialog with the recently used documents list shown - * using a GtkTreeView widget - */ - chooser = gtk_recent_chooser_dialog_new ("Recent Documents", - parent_window, - GTK_STOCK_CLOSE, GTK_RESPONSE_CANCEL, - GTK_STOCK_OPEN, GTK_RESPONSE_OK, - NULL); - /* set the sorting order to "most recently used first" */ - gtk_recent_chooser_set_sort_type (GTK_RECENT_CHOOSER (chooser), GTK_RECENT_SORT_MRU); - response = gtk_dialog_run (GTK_DIALOG (chooser)); - if (response == GTK_RESPONSE_OK) - { - GtkRecentInfo *info; - - info = gtk_recent_chooser_get_current_item (GTK_RECENT_CHOOSER (chooser)); - do_something_with_the_item (info); - - gtk_recent_info_unref (info); - } - - gtk_widget_destroy (chooser); - - - -
- -
- Advanced usage - - - The #GtkRecentChooser widgets might display items sorted and filtered, - either with already supplied or custom sorting and filtering functions. - The biggest difference from the EggRecentView - widgets in EggRecent is that the #GtkRecentChooser widgets will use - their own copy of the list and will apply the sorting and filtering - functions only on the copy; this allows the creation of many viewers - with a single controller, like using many #GtkTreeView with a single - #GtkTreeModel instance. - - - - Available sorting methods are: - - /* no sorting */ - gtk_recent_chooser_set_sort_type (GTK_RECENT_CHOOSER (chooser), GTK_RECENT_SORT_NONE); - - /* most recently used first */ - gtk_recent_chooser_set_sort_type (GTK_RECENT_CHOOSER (chooser), GTK_RECENT_SORT_MRU); - - /* most recently used last */ - gtk_recent_chooser_set_sort_type (GTK_RECENT_CHOOSER (chooser), GTK_RECENT_SORT_LRU); - - You can create your own sorting function, and the use the - GTK_RECENT_SORT_CUSTOM method: - - /* custom sorting function, based on the registration count - * (most used first) - */ - static void - sort_by_usage_count (GtkRecentInfo *a, - GtkRecentInfo *b, - gpointer data) - { - gint count_a, count_b; - - count_a = count_b = 0; - - if (gtk_recent_info_has_application (a, APP_NAME)) - gtk_recent_info_get_application_info (a, APP_NAME, NULL, &count_a, NULL); - - if (gtk_recent_info_has_application (b, APP_NAME)) - gtk_recent_info_get_application_info (b, APP_NAME, NULL, &count_b, NULL); - - return count_a < count_b; - } - - ... - - /* set custom sorting and set the custom sorting function */ - gtk_recent_chooser_set_sort_type (GTK_RECENT_CHOOSER (chooser), - GTK_RECENT_SORT_CUSTOM); - gtk_recent_chooser_set_sort_func (GTK_RECENT_CHOOSER, - sort_by_usage_count, - NULL, /* sort function data */ - NULL /* destroy notify for the data */); - - - - - Filtering is done using the #GtkRecentFilter object, similar to the - #GtkFileFilter object used by the #GtkFileChooser widgets. The - #GtkRecentFilter object has a set of pre-defined options based on the - meta-data exposed by the #GtkRecentInfo object. It also allows custom - filtering function: - - GtkRecentFilter *filter; - - filter = gtk_recent_filter_new (); - - /* set the user visible name of the filter */ - gtk_recent_filter_set_name (filter, "Since Last Month"); - - /* set the maximum age of a recently used document */ - gtk_recent_filter_set_age (filter, 31); - - /* the chooser takes the ownership of the object */ - gtk_recent_chooser_add_filter (GTK_RECENT_CHOOSER (chooser), filter); - - /* set the currently used filter */ - gtk_recent_chooser_set_filter (GTK_RECENT_CHOOSER (chooser), filter); - - filter = gtk_recent_filter_new (); - gtk_recent_filter_set_name (filter, "Every text file"); - gtk_recent_filter_set_mime_type (filter, "text/plain"); - - gtk_recent_chooser_add_filter (GTK_RECENT_CHOOSER (chooser), filter); - - The #GtkRecentChooserWidget and #GtkRecentChooserDialog widgets allow - multiple filters and the selection of an appropriate one; the - #GtkRecentChooserMenu widget allows just a single filter object. - - -
- - - - diff --git a/docs/reference/gtk/migrating-GtkTooltip.sgml b/docs/reference/gtk/migrating-GtkTooltip.sgml deleted file mode 100644 index 56b2a7d18f..0000000000 --- a/docs/reference/gtk/migrating-GtkTooltip.sgml +++ /dev/null @@ -1,66 +0,0 @@ - - - - - Migrating from GtkTooltips to GtkTooltip - - - GTK+ 2.12 brings a completely new tooltip implementation which - allows many things that were not possible with the old - #GtkTooltips interface. The new possibilities are explained - in more detail in the section about #GtkTooltip. - - - - A number of complications of the old API have been removed: - - - - Tooltips can not be grouped anymore. The old tooltips - API allowed this by using multiple #GtkTooltips objects. - We believe that the timeout behaviour of the new tooltips - implementation is better and makes it unnecessary to use - grouping as a way to overcome shortcomings of the - fast-tooltips mode. - - - - Timeouts can not be set individually anymore. Instead - there are settings #GtkSettings:gtk-tooltip-timeout, - #GtkSettings:gtk-tooltip-browse-timeout and - #GtkSettings:gtk-tooltip-browse-mode-timeout to influence - the behaviour of tooltips globally. - - - - - - - Here is an example of setting a tooltip on a widget with the old API: - -GtkTooltips *tooltips = gtk_tooltips_new (); -gtk_tooltips_set_tip (tooltips, widget, "Some tips", NULL); - - - - Using the new tooltips API, it is no longer necessary to create - an object: - -gtk_widget_set_tooltip_text (widget, "Some tips"); - - - - Similarly, setting a tooltip on a #GtkToolItem gets - simplified from - -gtk_tool_item_set_tooltip (toolitem, toolbar->tooltips, "tool tip", NULL); - - to - -gtk_tool_item_set_tooltip_text (toolitem, text); - - - -