enum HildonPannableAreaMode

typedef enum {
  HILDON_PANNABLE_AREA_MODE_PUSH,
  HILDON_PANNABLE_AREA_MODE_ACCEL,
  HILDON_PANNABLE_AREA_MODE_AUTO
} HildonPannableAreaMode;

Used to change the behaviour of the pannable areaing

enum HildonMovementMode

typedef enum {
  HILDON_MOVEMENT_MODE_HORIZ = 1 << 1,
  HILDON_MOVEMENT_MODE_VERT = 1 << 2,
  HILDON_MOVEMENT_MODE_BOTH = 0x000006
} HildonMovementMode;

Used to control the movement of the pannable, we can allow or disallow horizontal or vertical movement. This way the applications can control the movement using scroll_to and jump_to functions

enum HildonMovementDirection

typedef enum {
  HILDON_MOVEMENT_UP,
  HILDON_MOVEMENT_DOWN,
  HILDON_MOVEMENT_LEFT,
  HILDON_MOVEMENT_RIGHT
} HildonMovementDirection;

Used to point out the direction of the movement

enum HildonSizeRequestPolicy

typedef enum {
  HILDON_SIZE_REQUEST_MINIMUM,
  HILDON_SIZE_REQUEST_CHILDREN
} HildonSizeRequestPolicy;

Used to control the size request policy of the widget

HildonPannableArea

typedef struct _HildonPannableArea HildonPannableArea;

HildonPannableArea has no publicly accessible fields

hildon_pannable_area_new ()

GtkWidget*          hildon_pannable_area_new            (void);

Create a new pannable area widget

Since 2.2

hildon_pannable_area_new_full ()

GtkWidget*          hildon_pannable_area_new_full       (gint mode,
                                                         gboolean enabled,
                                                         gdouble vel_min,
                                                         gdouble vel_max,
                                                         gdouble decel,
                                                         guint sps);

Create a new HildonPannableArea widget and set various properties

Since 2.2

hildon_pannable_area_add_with_viewport ()

void                hildon_pannable_area_add_with_viewport
                                                        (HildonPannableArea *area,
                                                         GtkWidget *child);

Convenience function used to add a child to a GtkViewport, and add the viewport to the scrolled window for childreen without native scrolling capabilities.

See gtk_scrolled_window_add_with_viewport() for more information.

Since 2.2

hildon_pannable_area_scroll_to ()

void                hildon_pannable_area_scroll_to      (HildonPannableArea *area,
                                                         const gint x,
                                                         const gint y);

Smoothly scrolls area to ensure that (x, y) is a visible point on the widget. To move in only one coordinate, you must set the other one to -1. Notice that, in HILDON_PANNABLE_AREA_MODE_PUSH mode, this function works just like hildon_pannable_area_jump_to().

This function is useful if you need to present the user with a particular element inside a scrollable widget, like GtkTreeView. For instance, the following example shows how to scroll inside a GtkTreeView to make visible an item, indicated by the GtkTreeIter iter.

 GtkTreePath *path;
 GdkRectangle rect;
 gint y;
 
 path = gtk_tree_model_get_path (model, &iter);
 gtk_tree_view_get_background_area (GTK_TREE_VIEW (treeview),
                                    path, NULL, &rect);
 gtk_tree_view_convert_bin_window_to_tree_coords (GTK_TREE_VIEW (treeview),
                                                  0, rect.y, NULL, &y);
 hildon_pannable_area_scroll_to (panarea, -1, y);
 gtk_tree_path_free (path);

If you want to present a child widget in simpler scenarios, use hildon_pannable_area_scroll_to_child() instead.

There is a precondition to this function: the widget must be already realized. Check the hildon_pannable_area_jump_to_child() for more tips regarding how to call this function during initialization.

Since 2.2

hildon_pannable_area_jump_to ()

void                hildon_pannable_area_jump_to        (HildonPannableArea *area,
                                                         const gint x,
                                                         const gint y);

Jumps the position of area to ensure that (x, y) is a visible point in the widget. In order to move in only one coordinate, you must set the other one to -1. See hildon_pannable_area_scroll_to() function for an example of how to calculate the position of children in scrollable widgets like GtkTreeview.

There is a precondition to this function: the widget must be already realized. Check the hildon_pannable_area_jump_to_child() for more tips regarding how to call this function during initialization.

Since 2.2

hildon_pannable_area_scroll_to_child ()

void                hildon_pannable_area_scroll_to_child
                                                        (HildonPannableArea *area,
                                                         GtkWidget *child);

Smoothly scrolls until child is visible inside area. child must be a descendant of area. If you need to scroll inside a scrollable widget, e.g., GtkTreeview, see hildon_pannable_area_scroll_to().

There is a precondition to this function: the widget must be already realized. Check the hildon_pannable_area_jump_to_child() for more tips regarding how to call this function during initialization.

Since 2.2

hildon_pannable_area_jump_to_child ()

void                hildon_pannable_area_jump_to_child  (HildonPannableArea *area,
                                                         GtkWidget *child);

Jumps to make sure child is visible inside area. child must be a descendant of area. If you want to move inside a scrollable widget, like, GtkTreeview, see hildon_pannable_area_scroll_to().

There is a precondition to this function: the widget must be already realized. You can control if the widget is ready with the GTK_WIDGET_REALIZED macro. If you want to call this function during the initialization process of the widget do it inside a callback to the ::realize signal, using g_signal_connect_after() function.

Since 2.2

hildon_pannable_get_child_widget_at ()

GtkWidget*          hildon_pannable_get_child_widget_at (HildonPannableArea *area,
                                                         gdouble x,
                                                         gdouble y);

Get the widget at the point (x, y) inside the pannable area. In case no widget found it returns NULL.

Since 2.2

hildon_pannable_area_get_center_on_child_focus ()

gboolean            hildon_pannable_area_get_center_on_child_focus
                                                        (HildonPannableArea *area);

Gets the area "center-on-child-focus" property value.

See "center-on-child-focus" for more information.

Since 2.2

hildon_pannable_area_set_center_on_child_focus ()

void                hildon_pannable_area_set_center_on_child_focus
                                                        (HildonPannableArea *area,
                                                         gboolean value);

Sets the area "center-on-child-focus" property to value.

See "center-on-child-focus" for more information.

Since 2.2

hildon_pannable_area_get_size_request_policy ()

HildonSizeRequestPolicy hildon_pannable_area_get_size_request_policy
                                                        (HildonPannableArea *area);

This function returns the current size request policy of the widget. That policy controls the way the size_request is done in the pannable area. Check hildon_pannable_area_set_size_request_policy() for a more detailed explanation.

Since 2.2

hildon_pannable_area_set_size_request_policy ()

void                hildon_pannable_area_set_size_request_policy
                                                        (HildonPannableArea *area,
                                                         HildonSizeRequestPolicy size_request_policy);

This function sets the pannable area size request policy. That policy controls the way the size_request is done in the pannable area. Pannable can use the size request of its children (HILDON_SIZE_REQUEST_CHILDREN) or the minimum size required for the area itself (HILDON_SIZE_REQUEST_MINIMUM), the latter is the default. Recall this size depends on the scrolling policy you are requesting to the pannable area, if you set GTK_POLICY_NEVER this parameter will not have any effect with HILDON_SIZE_REQUEST_MINIMUM set.

Since 2.2

hildon_pannable_area_get_hadjustment ()

GtkAdjustment*      hildon_pannable_area_get_hadjustment
                                                        (HildonPannableArea *area);

Returns the horizontal adjustment. This adjustment is the internal widget adjustment used to control the animations. Do not modify it directly to change the position of the pannable, to do that use the pannable API. If you modify the object directly it could cause artifacts in the animations.

Since 2.2

hildon_pannable_area_get_vadjustment ()

GtkAdjustment*      hildon_pannable_area_get_vadjustment
                                                        (HildonPannableArea *area);

Returns the vertical adjustment. This adjustment is the internal widget adjustment used to control the animations. Do not modify it directly to change the position of the pannable, to do that use the pannable API. If you modify the object directly it could cause artifacts in the animations.

Since 2.2

The "bounce-steps" property

  "bounce-steps"             guint                 : Read / Write / Construct

Number of steps that is going to be used to bounce when hitting the edge, the rubberband effect depends on it.

Default value: 3

The "center-on-child-focus" property

  "center-on-child-focus"    gboolean              : Read / Write / Construct

Whether to center the pannable on the child that receives the focus.

Default value: FALSE

The "deceleration" property

  "deceleration"             gdouble               : Read / Write / Construct

The multiplier used when decelerating when in acceleration scrolling mode.

Allowed values: [0,1]

Default value: 0.85

The "direction-error-margin" property

  "direction-error-margin"   guint                 : Read / Write / Construct

After detecting the direction of the movement (horizontal or vertical), we can add this margin of error to allow the movement in the other direction even apparently it is not.

Default value: 10

The "drag-inertia" property

  "drag-inertia"             gdouble               : Read / Write / Construct

Percentage of the calculated speed in each moment we are are going to use to calculate the launch speed, the other part would be the speed calculated previously.

Allowed values: [0,1]

Default value: 0.85

The "enabled" property

  "enabled"                  gboolean              : Read / Write / Construct

Enable or disable finger-scroll.

Default value: TRUE

The "force" property

  "force"                    guint                 : Read / Write / Construct

Force applied to the movement, multiplies the calculated speed of the user movement the cursor in the screen.

Default value: 50

The "hadjustment" property

  "hadjustment"              GtkAdjustment*        : Read

The GtkAdjustment for the horizontal position.

The "hovershoot-max" property

  "hovershoot-max"           gint                  : Read / Write / Construct

Space we allow the widget to pass over its horizontal limits when hitting the edges, set 0 in order to deactivate overshooting.

Allowed values: >= 0

Default value: 150

The "hscrollbar-policy" property

  "hscrollbar-policy"        GtkPolicyType         : Read / Write / Construct

Visual policy of the horizontal scrollbar.

Default value: GTK_POLICY_AUTOMATIC

The "initial-hint" property

  "initial-hint"             gboolean              : Read / Write / Construct

Whether to hint the user about the pannability of the container.

Default value: TRUE

The "low-friction-mode" property

  "low-friction-mode"        gboolean              : Read / Write / Construct

Avoid decelerating the panning movement, like no friction, the widget will stop in the edges or if the user clicks.

Default value: FALSE

The "mode" property

  "mode"                     HildonPannableAreaMode  : Read / Write / Construct

Change the finger-scrolling mode.

Default value: HILDON_PANNABLE_AREA_MODE_AUTO

The "mov-mode" property

  "mov-mode"                 HildonMovementMode    : Read / Write / Construct

Controls if the widget can scroll vertically, horizontally or both.

Default value: HILDON_MOVEMENT_MODE_VERT

The "panning-threshold" property

  "panning-threshold"        guint                 : Read / Write / Construct

Amount of pixels to consider a motion event an scroll, if it is less it is a click detected incorrectly by the touch screen.

Default value: 25

The "scroll-time" property

  "scroll-time"              gdouble               : Read / Write / Construct

The time to scroll to a position when calling the hildon_pannable_scroll_to() function.

Allowed values: [0,20]

Default value: 1

The "scrollbar-fade-delay" property

  "scrollbar-fade-delay"     guint                 : Read / Write / Construct

Time the scrollbar is going to be visible if the widget is not in action in miliseconds.

Default value: 1000

The "size-request-policy" property

  "size-request-policy"      HildonSizeRequestPolicy  : Read / Write / Construct

Controls the size request policy of the widget.

Default value: HILDON_SIZE_REQUEST_MINIMUM

The "sps" property

  "sps"                      guint                 : Read / Write / Construct

Amount of scroll events to generate per second.

Default value: 20

The "vadjustment" property

  "vadjustment"              GtkAdjustment*        : Read

The GtkAdjustment for the vertical position.

The "velocity-fast-factor" property

  "velocity-fast-factor"     gdouble               : Read / Write / Construct

Minimum velocity that is considered 'fast': children widgets won't receive button presses. Expressed as a fraction of the maximum velocity.

Allowed values: [0,1]

Default value: 0.01

The "velocity-max" property

  "velocity-max"             gdouble               : Read / Write / Construct

Maximum distance the child widget should scroll per 'frame', in pixels per frame.

Allowed values: >= 0

Default value: 3500

The "velocity-min" property

  "velocity-min"             gdouble               : Read / Write / Construct

Minimum distance the child widget should scroll per 'frame', in pixels per frame.

Allowed values: >= 0

Default value: 10

The "velocity-overshooting-max" property

  "velocity-overshooting-max" gdouble               : Read / Write / Construct

Maximum distance the child widget should scroll per 'frame', in pixels per frame when it overshoots after hitting the edge.

Allowed values: >= 0

Default value: 130

The "vovershoot-max" property

  "vovershoot-max"           gint                  : Read / Write / Construct

Space we allow the widget to pass over its vertical limits when hitting the edges, set 0 in order to deactivate overshooting.

Allowed values: >= 0

Default value: 150

The "vscrollbar-policy" property

  "vscrollbar-policy"        GtkPolicyType         : Read / Write / Construct

Visual policy of the vertical scrollbar.

Default value: GTK_POLICY_AUTOMATIC

The "indicator-width" style property

  "indicator-width"          guint                 : Read / Write

Pixel width used to draw the scroll indicators.

Default value: 8

The "horizontal-movement" signal

void                user_function                      (HildonPannableArea *hildonpannable,
                                                        gint                direction,
                                                        gdouble             initial_x,
                                                        gdouble             initial_y,
                                                        gpointer            user_data)           : Run Last / Action

The horizontal-movement signal is emitted when the pannable area detects a horizontal movement. The detection does not mean the widget is going to move (i.e. maybe the children are smaller horizontally than the screen).

Since 2.2

The "panning-finished" signal

void                user_function                      (HildonPannableArea *hildonpannable,
                                                        gpointer            user_data)

This signal is emitted after the kinetic panning has finished.

Since 2.2

The "panning-started" signal

gboolean            user_function                      (HildonPannableArea *hildonpannable,
                                                        gpointer            user_data)

This signal is emitted before the panning starts. Applications can return TRUE to avoid the panning. The main difference with the vertical-movement and horizontal-movement signals is those gesture signals are launched no matter if the widget is going to move, this signal means the widget is going to start moving. It could even happen that the widget moves and there was no gesture (i.e. click meanwhile the pannable is overshooting).

Since 2.2

The "vertical-movement" signal

void                user_function                      (HildonPannableArea *hildonpannable,
                                                        gint                direction,
                                                        gdouble             initial_x,
                                                        gdouble             initial_y,
                                                        gpointer            user_data)           : Run Last / Action

The vertical-movement signal is emitted when the pannable area detects a vertical movement. The detection does not mean the widget is going to move (i.e. maybe the children are smaller vertically than the screen).

Since 2.2