maemo-gtk-2-6 to GTK+ >= 2.10 API Migration Guide

This page discusses necessary changes to port applications which are based on maemo-gtk-2-6 to the API provided by Gtk+ >= 2.10.


NOTE: If you are linking directly to Maemo GTK+ 2.10 without using the Hildon library you'll need to add MAEMO_CHANGES to your CFLAGS if you want to use any of the maemo additions to GTK+ (if you are reading this you most likely want to do it, see Maemo/Gtk210Overview for a high level view of those additions).

M01: gtkprogressbar.c style properties obsoleted by GTK+ 2.11

Maemo-gtk-2-6 introduced additional style properties on GtkProgressBar, in particular:

int        ::text-spacing         // The amount of pixels between the trough and text
int        ::width-increment      // The amount of pixels to add to the width size request
int        ::height-increment     // The amount of pixels to add to the height size request
int        ::text-xnudge          // Amount of pixels to move the text x position
int        ::text-ynudge          // Amount of pixels to move the text y position

Applications or themes (i.e. gtkrc files) that make use of these properties need to be modified to use GtkProgressBar::xspacing and GtkProgressBar::yspacing instead, introduced in Gtk+-2.11.0.

M02: Timeout/Animation properties name change (since GTK+ 2.10)

The following properties have been renamed in GTK+ upstream:

GtkSettings::gtk-update-timeout is now GtkSettings::gtk-timeout-repeat
GtkSettings::gtk-initial-timeout is now GtkSettings::gtk-timeout-initial
GtkSettings::gtk-toolbar-animation is now GtkSettings::gtk-enable-animations

M03: Truncate multiline paste in GtkEntry (since GTK+ 2.10)

The property GtkEntry::truncate-multiline was introduced in GtkEntry with default value FALSE. maemo-gtk-2-6 GtkEntry is hardcoded to act as if it had this property set to TRUE. Possible migration plans are: change the default from FALSE to TRUE in maemo-gtk-2-10, create ad-hoc constructors (hildon_gtk_entry_new (), etc) which set the property to TRUE, document the behaviour change and let the applications deal with it ...

M04: Show last char in GtkEntry property (since GTK+ 2.10)

The show-last-char style property has been changed to GtkSettings::gtk-entry-password-hint-timeout, its value being the ammount of time the last character in hidden entries is shown (0 being the default value, which will disable the feature). The migration plan is to enable the property with a value of 600 (0.6 seconds).

M05: GtkTreeView Rubber Banding (since GTK+ 2.10)

Maemo-gtk-2-6 adds the ability to create selections by dragging the stylus. This is really similar to the ability of GtkCList and GtkCTree to do "drag selections". This can at times look awkward, so "rubber banding" has been introduced on modern GUI systems. Because GtkIconList already used rubber banding for its drag selections, it was decided to also implement this as rubber banding in GtkTreeView. Rubber banding is in fact not more special than drag selection extended by drawing the translucent rectangle.

In upstream this feature can be enabled by setting the "rubber-banding" property to TRUE. The property is FALSE by default, since it can conflict with any custom TreeView drag and drop code currently in use. In the future this might be changed by only starting rubber banding on "empty" areas of a tree view. In upstream support for keyboard modifiers was added to allow creating complex selections.

In the current trunk of maemo-gtk there is suppor for creation of discontinuous selections. This is not supported in upstream. In order to fix this, an approach could be to change the behaviour of the drag selection code in GtkTreeView when touchscreen-mode is enabled. However, it does not always hold that a machine does not have modifier keys if touchscreen-mode is enabled.

M06: GtkEntry inner border (since GTK+ 2.10)

maemo-gtk-2-6 has GtkEntry::horizontal-border and GtkEntry::vertical-border style properties to set the inner borders of a GtkEntry. Upstream has changed this to a unique GtkBorder style property called GtkEntry::inner-border plus an ordinary property of the same name and type that can be used to override the style property (useful when pixel-perfect positioning of the entry is needed).

M07: GtkMenu horizontal padding property (since GTK+ 2.10)

(Removed this migration entry since the property has been merged upstream with the same default value of 0. No action needs to be taken here)

M08: Themeable separators (since GTK+ 2.10)

Upstream has added the following style properties to GtkWidget:

bool        ::wide-separators       //Whether separators have configurable width and should be drawn using a box instead of a line
int         ::separator-height      //The height of separators if wide-separators is TRUE
int         ::separator-width       //The width of separators if wide-separators is TRUE

Users of old style properties like GtkSeparator::hildonlike-drawing should be updated to use the new ones.

M09: GtkTreeView Dotted/Grid Lines (since GTK+ 2.10)

Maemo-gtk-2-6 adds the GtkTreeView::dotted-lines property (FALSE by default), but apparently is not used anywhere at this moment. When enabled the tree view will draw dotted "helper" lines connecting child nodes with their parents.

In upstream the following properties have been added to GtkTreeView:

bool        ::enable-tree-lines // Whether tree lines should be drawn in the tree view (regular property)

int         ::tree-line-width   // Width, in pixels, of the tree view tree lines (style property)
string      ::tree-line-pattern // Dash pattern used to draw the tree view tree lines (style property)

Enabling this feature will draw grid lines slightly different from what is seen in maemo, but similar to what is seen in, for example, the GtkCTree and Windows. The width and "dash style" of the lines can be controlled with tree-line-width and tree-line-pattern respectively.

Also added is the ability to draw "grid lines". When enabled lines will be drawn between columns and/or between rows.

enum        ::enable-grid-lines // Which kinds of grid lines should be drawn in the tree view (regular property)

int         ::grid-line-width   // Width, in pixels, of the tree view grid lines (style property)
string      ::grid-line-pattern // Dash pattern used to draw the tree view grid lines (style property)

The enable-grid-lines property expects a value of the type GtkTreeViewGridLines. A value indicating "none", "vertical" grid lines, "horizontal" grid lines or "both" kinds of grid lines can be chosen. The width and pattern properties work like their tree-line counterparts.

M10: GtkHashTable (since GLib 2.10)

GtkHashTable was introduced in maemo-gtk-2-6 for the logical colors work. When the patch was ported to GTK+ upstream GtkHashTable was replaced with the following API additions to GHashTable:

GHashTable*        g_hash_table_ref (GHashTable *hash_table);
void               g_hash_table_unref (GHashTable *hash_table);

If you happen to be using GtkHashTable because you need reference counting with hash tables, please port your code to this new API.

M11: GtkNotebook style properties (since GTK+ 2.10)

Maemo-gtk added the following style properties to GtkNotebook:

int        ::arrow-spacing // Spacing arround the scroll arrow
int        ::tab-overlap  // How much tabs overlap, the greater the value the closer the tabs appear to be
int        ::tab-curvature // Defines the size of the tab curvature

Upstream now has exactly the same style properties with the same default values, so in theory no porting action is needed.

M12: GtkMenu scroll on click (since GTK+ 2.10)

M13: GtkMenu double arrows style property (since GTK+ 2.10)

This style property was added to GTK+ upstream with the same name but a deafult value of TRUE.

M14: GtkCalendar

The widget previously known as GtkCalendar was moved to hildon-1 (old hildon-widgets) as HildonCalendar.

M15: GtkComboBox arrow-{height, width} (obsoleted by GTK+ 2.11)

Upstream has introduced the following style property to control the size of combobox arrows:

int        ::arrow-size //The minimum size of the arrow in the combo box

It has a default value of 15, but the arrow size will grow from there depending on the font size set for the combobox. Usage of GtkComboBox::arrow-{width, height} should be deprecated in favour of the new style property.

M16: GtkMenuShell::close

The newly added ::close signal does not offer any new functionality (R04). After removing the ::close signal, any current use should be reviewed and one of the following already existing GtkMenuShell signals should be used instead:

void (*deactivate)     (GtkMenuShell *menu_shell);
void (*selection_done) (GtkMenuShell *menu_shell);
void (*cancel)         (GtkMenuShell *menu_shell);

Note that M62 adresses a related rc-file TODO.

M17: GtkWidget Hildon Focus Handling

The behaviour controlled by the style property GtkWidget::hildon-focus-handling was unimplemented on GTK+. This property is deprecated and useless, just stop using it.

M18: GtkNotebook scrollable

The default value for GtkNotebook::scrollable in maemo-gtk-2-6 was TRUE, but it has now changed to FALSE to be in sync with upstream. If you'd like to mantain the old behaviour of GtkNotebook please add the following code to your application:

gtk_notebook_set_scrollable (notebook, TRUE);

M19: GtkViewport shadow-type

Default value changed from SHADOW_IN to SHADOW_NONE.

M20: GtkTreeView passive-focus

According to Maemo/Gtk26Rationales#R18 GtkTreeView::passive-focus will be deprecated and its functionality will be implemented by the theme engine.

M21: GtkWidget tap-and-hold

No changes for maemo-gtk-2.10

M22: GtkWidget insensitive press (Gtk+-2.11)

The "insensitive-press" signal is deprecated in maemo-gtk-2.10. For the common use case of displaying a message when a widget is activated being insensitive, please see the proposed alternative/helper function in hildon. This signal should not be used for any other purpose.

M23: GtkWindow {get,set}_prev_focus_widget

The following functions are deprecated since IT2006 and do nothing, stop using them.

GtkWidget*  gtk_window_get_prev_focus_widget (GtkWindow* window)
void               gtk_window_set_prev_focus_widget (GtkWindow* window, GtkWidget* widget)

M24: GtkTextView, GtkEntry autocap property

The autocap property of GtkTextView and GtkEntry is deprecated. Use HildonGtkInputMode instead. For GtkTextView:

void               hildon_gtk_text_view_set_input_mode (GtkTextView *text_view, HildonGtkInputMode mode)
HildonGtkInputMode hildon_gtk_text_view_get_input_mode (GtkTextView       *text_view)

For GtkEntry:

void               hildon_gtk_entry_set_input_mode (GtkEntry* entry, HildonGtkInputMode input_mode)
HildonGtkInputMode hildon_gtk_entry_get_input_mode (GtkEntry* entry)

The values for HildonGtkInputMode are defined in gtkenums.h, the autocap value is HILDON_GTK_INPUT_MODE_AUTOCAP.

M25: HildonGtkInputMode

M26: GtkButton ::child-offset-y style property

The ::child-offset-y property is deprecated and has no effect in maemo-gtk, it should not be used. More details are provided in the rationale: R30.

M27: gtk_style_lookup_logical_color (since GTK+ 2.10)

The following function was introduced in maemo-gtk-2-6 to lookup logical colors by their name:

gboolean        gtk_style_lookup_logical_color (GtkStyle *style, const gchar *color_name, GdkColor *color)

When this functionality was merged in upstream its name was changed to gtk_style_lookup_color.

M28: GTK_RC_TOKEN_LOGICAL_COLOR / gtkrc logical color syntax (since GTK+ 2.10)

The "Styles" section of the Gtk+ reference documentation on rc-files describes how logical colors are now supported in upstream and how they can be mixed and shaded. Existing rc-files need to be ported to use the new scheme.

M29: GtkScrolledWindow scrollbar-dislocation

From Maemo/Gtk26Rationales#R29: This boolean property, when set to TRUE, causes the scrollbars to be rendered outside the container's border. If this change was folded upstream, GtkScrolledWindow would be the only container that draws something in the area that's supposed to be an empty area that's always outside the widget. The change is unmergable because it breaks this assumption about a container's border. The same visual appearance can be acheived by setting the scrolled window's "scrollbar-spacing" style property and packing the widget so it has different borders on different sides. If style-controlled individual borders around widgets are absolutely needed, a new container class should be created in hildon libs that allows to specify the borders on all four sides separately via style properties, and the scrolled window should be packed in such a container.

M30: Rich Text Copy & Paste (since GTK+ 2.10)

The API to enable rich text copy and paste between GtkTextViews (actually between GtkTextBuffers) was comitted upstream but has changed completely. In maemo-gtk-2-6, enabling rich text transfer between two buffers with compatible tagset worked like this:

/* API to be used for both the source and target buffers */
gtk_text_buffer_set_can_paste_rich_text (buffer, TRUE);
gtk_text_buffer_set_rich_text_format (buffer, "my-rich-text-tagset");

In GTK+ 2.10 it has to be done like this:

/* API to be used on the source buffer */
gtk_text_buffer_register_serialize_tagset (buffer, "my-rich-text-tagset");

/* API to be used on the destination buffer */
gtk_text_buffer_register_deserialize_tagset (buffer, "my-rich-text-tagset");

If deserialization is supposed to be allowed to create new tags in the target buffer, this must be enabled by calling gtk_text_buffer_deserialize_set_can_create_tags() on the target buffer, passing the GdkAtom returned by gtk_text_buffer_register_deserialize_tagset().

The new upstream API allows much better control of rich text handling, for details see the GtkTextBuffer API docs.

M31: GtkRange Stream API (since GTK+ 2.11)

Maemo-gtk-2-6 added the following API to the GtkRange widget to allow applications to show a buffering indicator which can be used, for example, when the range is used to display the position in a streamed media file.

Properties:

gboolean        ::stream-indicator // Whether to display a stream indicator graphics on trough
gdouble         ::stream-position //The position of the streaming.

Functions:

void           osso_gtk_range_set_stream_indicator (GtkRange *range, gboolean stream_indicator)
gboolean       osso_gtk_range_get_stream_indicator (GtkRange *range)
void           osso_gtk_range_set_stream_position (GtkRange *range, gdouble position)
gdouble        osso_gtk_range_get_stream_position (GtkRange *range)

This functionality has been commited to GTK+ upstream with a nomenclature change: stream-position is now fill-level and stream-indicator is now show-fill-level. Thus, the new API is:

Properties:

gboolean        ::show-fill-level // Whether to display a fill level indicator graphics on trough.
gdouble         ::fill-level //The fill level.

Functions:

void            gtk_range_set_show_fill_level (GtkRange *range, gboolean show_fill_level)
gboolean        gtk_range_get_show_fill_level (GtkRange *range)
void            gtk_range_set_fill_level (GtkRange *range, gdouble fill_level)
gdouble         gtk_range_get_fill_level (GtkRange *range)

Additional API has been added that permits the application to restrict the reachable range values to those present in the fill level (so, for example, you can't seek past the actually downloaded part of a currently being downloaded file):

Properties:

gboolean        ::restrict-to-fill-level //Whether to restrict the upper boundary to the fill level.

Functions:

void            gtk_range_set_restrict_to_fill_level (GtkRange *range, gboolean restrict_to_fill_level)
gboolean        gtk_range_get_restrict_to_fill_level (GtkRange *range)

This property is TRUE by default, and ::fill-level has a default value of G_MAXDOUBLE (from 0.0 in maemo-gtk-2-6) to work consistently in the default case (::show-fill-level FALSE, ::restrict-to-fill-level TRUE, ::fill-level G_MAX_DOUBLE).

Maemo-gtk-2-6 also introduces a GtkRange::stream-indicator-padding style property which allows padding adjustments to compensate for certain drawing artefacts. This is not neccessary in maemo-gtk-2-10, fill-level indicator can be implemented by special handling of the "trough-fill-level" and "trough-fill-level-full" drawing details passed in to the gtk_paint_box() function.

The relevant reference documentation: * http://developer.gnome.org/doc/API/2.0/gtk/GtkRange.html#gtk-range-set-fill-level

M32: GtkRange arrow sensitivity (since GTK+ 2.10)

GtkRange::autodimmed-steppers style property is deprecated. GTK+ now acts by default as if that property was enabled. For fine-grain control of this behaviour, the following API has been introduced in GtkRange:

Properties:
enum       ::lower-stepper-sensitivity //Lower stepper sensitivity
enum       ::upper-stepper-sensitivity //Upper stepper sensitivity

Functions:

void               gtk_range_set_lower_stepper_sensitivity (GtkRange *range, GtkSensitivityType sensitivity)
GtkSensitivityType gtk_range_get_lower_stepper_sensitivity (GtkRange *range)
void               gtk_range_set_upper_stepper_sensitivity (GtkRange *range, GtkSensitivityType sensitivity)
GtkSensitivityType gtk_range_get_upper_stepper_sensitivity (GtkRange *range)

Enum:

typedef enum
{
  GTK_SENSITIVITY_AUTO,
  GTK_SENSITIVITY_ON,
  GTK_SENSITIVITY_OFF
} GtkSensitivityType;

AUTO is the the new defaul behaviour (same as ::autodimmed-steppers set to TRUE).

  • The relevant reference documentation:

* http://developer.gnome.org/doc/API/2.0/gtk/GtkRange.html#gtk-range-set-lower-stepper-sensitivity * http://developer.gnome.org/doc/API/2.0/gtk/GtkRange.html#gtk-range-set-upper-stepper-sensitivity

M33: gtk_cell_view_set_data

This internal function was made public in maemo-gtk. However there are no real use cases for this function outside of GTK+ itself and nothing in the current maemo platform seems to use this function. R25 suggests to make this symbol private again.

M34: hildon_gtk_file_system_create (obsoleted by GTK+ 2.10)

Current gtk-2-10 exports the gtk_file_system_create symbol, so there is no need for hildon_gtk_file_system_create to exist anymore. (Note that current upstream HEAD does not seem to have this change).

M35: GtkDialog style properties

The content-area-spacing style property has been merged upstream and backfolded into maemo-gtk-2.10 with the same name, so no changes here.

M36: GDK_WINDOW_TYPE_HINT_MESSAGE

GDK_WINDOW_TYPE_HINT_MESSAGE has been removed in maemo-gtk-2.10. If you are using it please change it to GDK_WINDOW_TYPE_HINT_NOTIFICATION.

M37: View buttons

OssoGtkButtonAttachFlags
osso_gtk_button_set_detail_from_attach_flags
GtkButton::detail
GtkButton::automatic-detail

This is all gone, specially themed arbitrary view buttons are no longer supported.

For dialog buttons we now use stock GtkDialog with just one change: the default ButtonBox mode has been changed from END to CENTER. This should be completely transparent to application developers, so no code changes here.

M38: GtkCheckButton focus-x-padding

Removed from maemo-gtk-2.10.

M39: GtkCheckButton indicator-size

Removed from maemo-gtk-2.10.

M40: Hildon Icon Sizes

The following enums are to be removed. Use one of the following replacements instead, depending on context

  • Instead of HILDON_ICON_SIZE_26 use:
    • HILDON_ICON_SIZE_NOTE
    • HILDON_ICON_SIZE_SMALL
    • HILDON_ICON_SIZE_TOOLBAR
    • HILDON_ICON_SIZE_WIDG
  • Instead of HILDON_ICON_SIZE_40 use:
    • HILDON_ICON_SIZE_STATUSBAR
  • Instead of HILDON_ICON_SIZE_50 use:
    • HILDON_ICON_SIZE_BIG_NOTE
    • HILDON_ICON_SIZE_INDI_KEY_PAD_LOCK
    • HILDON_ICON_SIZE_INDI_OFFMODE_CHARGING
    • HILDON_ICON_SIZE_WIDG_WIZARD
  • Instead of HILDON_ICON_SIZE_64 use:
    • HILDON_ICON_SIZE_GRID
    • HILDON_ICON_SIZE_LIST

More information about the icon sizes is provided in the Hildon Migration Overview.

M41: GtkTreeView expander-indent (since GTK+ 2.10)

In maemo-gtk there exists an expander-indent style property which increases the indentation of items in all levels (except for the first level) by a certain amount of pixels. Upstream chose to turn this into a regular property and name it "level-indentation":

int        ::level-indentation //Extra indentation for each level

Because some applications want to tweak the look of their tree views (for example IM clients), it was decided to make this a regular property and not a style property. Another difference is that upstream adds the "extra" indentation to *all* levels, including the first one. In GtkTreeView each level is indented in case of a tree and so each level should receive the extra indentation.

M42: GtkTreeView checkbox mode

Checkbox mode is a special mode of operation (with regards to selection) in GtkTreeView introduced by maemo-gtk. When the allow-checkbox-mode is set to TRUE (which it is by default), the checkbox mode will automatically enable once you create a tree view with a column with a toggle renderer. In this case the maemo-introduced checkbox-mode property on the toggle renderers will be set -- this property only affects the drawing behaviour of the toggle renderer.

The checkbox mode modifies the selection behaviour in such a way that when dragging the stylus will set all checkboxes hit by the stylus to the same state of the first selected checkbox. Rows with a checked checkbox are drawn with a slightly different background.

R23 suggests to move this out of GtkTreeView and implement this in application space. This change will also hugely improve the maintainability of tree view in maemo-gtk.

M43: (hildon)_gtk_button_set_depressed

  • _gtk_button_set_depressed was unintentionally exported and should not be used outside GTK+.
  • hildon_gtk_button_set_depressed is apparently only used by hildon-time-editor. Its use of this functionality seems to be bogus, so this API can be safely removed from maemo GTK+.

M44: GtkButton inner border (since GTK+ 2.10)

maemo-gtk-2-6 has a GtkButton::child-spacing style property to set the spacing between button and child. Upstream has changed this to a unique GtkBorder style property which is documented here: GtkButton::inner-border.

M45: GtkTreeView row ending details (since GTK+ 2.10)

The main drawing/rendering code of GtkTreeView has been changed in maemo-gtk to draw a different row background for a cell/column depending on the position of that cell/column (left, middle, right). Upstream has added the following style property to GtkTreeView:

gboolean     ::row-ending-details = FALSE;  // Whether extended row background theming is enabled or not.

Upstream has also changed the names of the detail strings passed to the theme engine. Where maemo-gtk currently uses "full", "left", "right", "middle"; upstream uses the details already in use ("cell_odd", "cell_even_ruled", etc) suffixed by nothing, "_start", "_end" and "_middle" respectively.

For example "full" in maemo-gtk could become "cell_even" in upstream. "left" could become "cell_even_left".

The themes need to be updated to set the row-ending-details style property to TRUE and use the new detail strings.

M46: GtkComboBox cursor navigation (since GTK+ 2.11)

maemk-gtk-2-6 has a change that makes the combo box navigate its items on left/right and leave the widget on up/down. In GTK+ 2.11 this is no longer needed since the combo box got keybindings and it's possible to unbind keybindings. The following gtkrc snippet will do the trick:

binding "b"
{
  bind "Left"  { "move-active" (step-up) }
  bind "Right" { "move-active" (step-down) }
  unbind "Up"
  unbind "Down"
}

class "GtkComboBox" binding "b"

The rc-file syntax and binding features used here are described in the rc-file documentation and the GtkBinding documentation.

M47: Don't wrap around when doing keyboard navigation (since GTK+ 2.11)

maemo-gtk-2-6 has changes in gtkmenushell.c and gtknotebook.c which change keyboard navigation and affect wrap-around behavior. In GTK+ 2.11 this can be controlled with the new keyboard navigation properties:

M48: GtkRange:two-part-trough style property (since GTK+ 2.10)

In maemo-gtk-2-6, GtkRange has the "two-part-trough" boolean style property that causes the parts on both sided of the slider to be rendered differently. This change has been merged to GTK+ 2.10 but the property has been renamed to ::trough-side-details. When enabled, the parts of the trough on the lower and upper sides are rendered with the "trough-lower" and "trough-upper" details.

M49: Changes to default value of properties

There are several instances in maemo-gtk where the default values of properties have been changed (hard coded). R08 says that upstream cannot take these changes and suggests to derive a new object and set the property to the new value in the instance _init() function.

A list of properties whose default values changes:

GtkCellRendererText::xpad
GtkCellRendererText::ypad
GtkCellRendererToggle::indicator-size /* used to be hard coded, but gtk+ 2.10 introduces indicator-size property */
GtkCellRendererToggle::xpad
GtkCellRendererToggle::ypad
GtkTreeView::headers-visible

M50: GtkCellRendererToggle indicator-size property (since GTK+ 2.10)

Previously it was not possible to change the size of the toggle, radio or check button through a property, since this size was hard coded in gtk+. Maemo-gtk changed the default size by changing the hard coded value. GTK+ 2.10 introduces an indicator-size property on GtkCellRendererToggle, with a default size of 12. Maemo-gtk can take advantage of this change by deriving a new object and change the value of the property there.

M51: GtkRange:draw-trough-under-steppers style property (since GTK+ 2.10)

In maemo-gtk-2-6, GtkRange has the "draw-trough-under-steppers" boolean style property that causes the trough to be drawn in between the steppers instead of below it. This change has been merged to GTK+ 2.10 but the property has been renamed to ::trough-under-steppers.

M52: GtkCellRendererText rendering changes

Maemo-gtk has a modified GtkCellRendererText which uses GTK_STATE_NORMAL instead of GTK_STATE_PRELIGHT when rendering in prelight state. R07 suggests to move this to the theme engine instead.

M53: GtkComboBox arrow sensitivity

The GtkComboBox in maemo-gtk automatically dims the arrow button when the model containing the contents of the popup is empty. This modification cannot go upstream because we feel that the application should control this instead. As R34 points out, there are multiple valid use cases where you would want to popup the combobox when the model is still empty.

M54: GtkRadioButton: don't select button on cursor navigation (since GTK+ 2.11)

The GtkRadioButton in maemo-gtk doesn't select the focussed item when doing keyboard navigation, and it leaves the radio button group when it reached the first/last button instead of wrapping around. To get the same effect with upstream GTK+ 2.11, the new "gtk-keynav-cursor-only" settings property needs to be set to TRUE.

M55: GtkTreeView focus and key navigation changes

GtkTreeView has a large number of possible interactions and a complicated selection and focus system; therefore the amount of keybindings is large. In maemo-gtk a good amount of changes have been made in this area, including:

  • Empty views cannot gain focus;
  • Cursor can not move left/right;
  • Curcor follows selection changes;
  • Blocking movement to insensitive rows;
  • maemo-gtk does not allow for focussing a single cell.

As pointed out in R09, R10, R11, R12 and R13, most of these changes cannot go upstream because they are specific to this embedded platform. Also, the intention of some of the changes is not fully clear.

Our suggestion for migration is to have a new look at the interaction requirements, see what can be done with the current code base outside of GtkTreeView and find proper solutions for the problematic interactions.

M56: GtkTreeView horizontal scrolling

Maemo-gtk has two small changes which affect horizontal scrolling in GtkTreeview:

  • Columns are truncated when a tree view is not in a scrolled window with hscroll. As said in R15, this should be backed out;

  • The code in gkt_tree_view_clamp_column_visible() has been commented out; this breaks all code trying to scroll to a specific column or cell.

Both changes should be backed out. If horizontal scrolling is not wished, applications should control the maximum sizes of the columns to not exceed the available horizontal space.

M57: GtkTreeView::force_list_kludge

M58: Modification of GtkTreeView behavior which can be done outside of GTK+

There are quite a number of modifications in GtkTreeView, focussed on its behavior and not always acceptable by upstream, which can also be done outside of GTK+:

  • Tap on row activates that row; send row-activated for all rows in multiple selection mode;
  • Only a single node in a level can be in expanded state at a time;
  • Scroll to expanding row;
  • Disable double clicks.

To minimize the number of differences between maemo-gtk and upstream gtk+, it is advisable to move these changes out of GTK+. Having the applications handle this, or deriving a new object from GtkTreeView implementing these behavioral changes are both viable options.

M59: GtkEntry: don't select all on focus-in

As described in R17 the maemo-gtk change to GtkEntry is not needed. The same effect can be achieved by setting the "gtk-entry-select-on-focus" settings property to FALSE.

M60: GtkTreeView hide expanders (since GTK+ 2.10)

Maemo does not use the expander arrows of GtkTreeView, instead they are hidden by setting expander-size to zero in the style properties and two patches to GtkTreeView. One of those changes the arrow drawing code to get rid of the constant 2 which is always added to the expander-size; unfortunately this is something which we can't remove in upstream at this point. Another comments out the code disabling button presses on expander arrows.

Upstream has added the following property:

gboolean ::show-expanders   // View has expanders

The best solution is to remove the above described patches from maemo-gtk and use the property instead.

M61: Remove gtk_check_button_clicked, gtk_check_button_update_state

As pointed out in R14, the maemo-added gtk_check_button_clicked() and gtk_check_button_update_state() should be backed out. Instead, the following functions can be used:

void       gtk_button_clicked           (GtkButton       *button);
void       gtk_toggle_button_set_active (GtkToggleButton *toggle_button,
                                         gboolean         is_active);

M62: RC-File: F4 cancels menus

Maemo-gtk-2-6 adds a GtkMenuShell::close signal and binds it to F4 programatically to close menus. GtkMenuShell::cancel should be used instead, and the key binding should be set up in an RCfile. Note that M16 adresses the removal of GtkMenuShell::close. The rc-file syntax and binding features are described in the rc-file documentation and the GtkBinding documentation.

binding "ms"
{
  bind "F4" { "cancel" () }
}

class "GtkMenuShell" binding "ms"

M63: propagate-lr-keys

This property has been removed from maemo-gtk. This behaviour can be re-implemented by applications by connecting to the signal "key-press-event".

M64: Deprecated symbols since 2.6

The following symbols have been deprecated in 2.8 and 2.10 upstream GTK+ releases.

  • gtk_calendar_freeze: Does nothing, just remove.
  • gtk_calendar_thaw: Does nothing, just remove.
  • gtk_cell_renderer_editing_canceled: Use gtk_cell_renderer_stop_editing ()
  • GTK_OBJECT_FLOATING: Use g_object_is_floating instead.
  • gtk_object_sink: Use g_object_ref_sink instead. Please note that this function will transform the floating reference into a normal reference, so if you were doing something like: g_object_ref (o); gtk_object_sink (o); you can change both calls for a call to g_object_ref_sink instead. See GtkObject documentation for more details.

  • gtk_selection_clear: Instead of calling this function, chain up from your selection_clear_event handler. Calling this function from any other context is illegal.

M65: Keynav in dialog action areas

maemo-gtk-2-6 changes GtkDialog so that Up/Down work as forward and backward TAB in the dialog's action area. The same effect can be acheived without any code change by simply changing the keybindings for GtkDialog:

binding "d"
{
  bind "Up"    { "move-focus" (tab-backward) }
  bind "Down"  { "move-focus" (tab-forward)  }
}

class "GtkDialog" binding "d"

M66: Separator between column headers (buttons) and GtkTreeView

Maemo-gtk adds a style property named "separator-height" to GtkButton, which allows for reserving extra space for drawing a separator below the button. Note that this is an integer property and not a boolean like the property's "blurb" suggests. Also note that this property does not control the height of the separator, since that height will always be 1px, but only controls the extra space to the reserved so the actual button and separator do not overlap. Previously, this property only had effect when GtkButton::listboxheader was set to be TRUE. In maemo-gtk-2-10 the listboxheader property has been backed out, and GtkButton::seperator-height has been renamed to:

GtkButton::tree-view-separator-area

This property will only have effect when its value != 0. Just like before, this property will reserve the specified extra space in pixels for drawing a slim 1px separator below the button.

M67: GtkComboBox is not fixed height anymore

In maemo-gtk-2.6 GtkComboBox would never request and would never be allocated more height than the height of its GtkToggleButton image (30px). maemo-gtk-2.10 has reverted this change to the original behaviour of the widget, which is to request and be given as much height as available. If you *really* want to make the widget to be fixed height, you could use GtkAlignment + setting a custom size request to it. Something like this:

GtkWidget *alignment, *combo;

alignment = gtk_alignment_new (0.5, 0.5, 1, 0); /* Never expand vertically */
combo = gtk_combo_box_new ();
gtk_widget_set_size_request (combo, -1, 30); /* Request 30px height */
gtk_container_add (GTK_CONTAINER (alignment), combo);

This kind of design should be generally avoided though, as it won't scale properly to different screen sizes or font size changes. As a general rule you should be only concerned about the relative sizes of your widgets and the distance between them being ok, not about their absolute size.

M68: gtk-buttons-image

As part of the GTK+ 2.10 migration process the gtk-button-images property has been set to FALSE by default in the default rc files of the platform. This means images on GtkButtons won't be shown. This has been implemented to enforce the Maemo UI specification rule that all buttons with text should have no images. If you wish to make a button which has only an image, consider packing a GtkImage inside an empty GtkButton.

M69: Auto-ellipsization

One of the Gtk 2.6 modifications was about turning on (forcing) the auto-ellipsization of GtkLabels. By default all GtkLabels would request their natural size but turn on ellipsizing and truncate content (if the size given was smaller). In Gtk 2.10 the default behaviour is back (labels don't ellipsize unless specifically enabled to ellipsize).

Attic/Maemo/Gtk210Migration (last edited 2013-11-23 01:26:52 by WilliamJonMcCann)