HildonPannableArea

HildonPannableArea — A scrolling widget designed for touch screens

Synopsis


#include <hildon/hildon.h>

enum                HildonPannableAreaMode;
enum                HildonMovementMode;
enum                HildonMovementDirection;
enum                HildonSizeRequestPolicy;
                    HildonPannableArea;
GtkWidget*          hildon_pannable_area_new            (void);
GtkWidget*          hildon_pannable_area_new_full       (gint mode,
                                                         gboolean enabled,
                                                         gdouble vel_min,
                                                         gdouble vel_max,
                                                         gdouble decel,
                                                         guint sps);
void                hildon_pannable_area_add_with_viewport
                                                        (HildonPannableArea *area,
                                                         GtkWidget *child);
void                hildon_pannable_area_scroll_to      (HildonPannableArea *area,
                                                         const gint x,
                                                         const gint y);
void                hildon_pannable_area_jump_to        (HildonPannableArea *area,
                                                         const gint x,
                                                         const gint y);
void                hildon_pannable_area_scroll_to_child
                                                        (HildonPannableArea *area,
                                                         GtkWidget *child);
void                hildon_pannable_area_jump_to_child  (HildonPannableArea *area,
                                                         GtkWidget *child);
GtkWidget*          hildon_pannable_get_child_widget_at (HildonPannableArea *area,
                                                         gdouble x,
                                                         gdouble y);
gboolean            hildon_pannable_area_get_center_on_child_focus
                                                        (HildonPannableArea *area);
void                hildon_pannable_area_set_center_on_child_focus
                                                        (HildonPannableArea *area,
                                                         gboolean value);
HildonSizeRequestPolicy hildon_pannable_area_get_size_request_policy
                                                        (HildonPannableArea *area);
void                hildon_pannable_area_set_size_request_policy
                                                        (HildonPannableArea *area,
                                                         HildonSizeRequestPolicy size_request_policy);
GtkAdjustment*      hildon_pannable_area_get_hadjustment
                                                        (HildonPannableArea *area);
GtkAdjustment*      hildon_pannable_area_get_vadjustment
                                                        (HildonPannableArea *area);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----HildonPannableArea

Implemented Interfaces

HildonPannableArea implements AtkImplementorIface and GtkBuildable.

Properties

  "bounce-steps"             guint                 : Read / Write / Construct
  "center-on-child-focus"    gboolean              : Read / Write / Construct
  "deceleration"             gdouble               : Read / Write / Construct
  "direction-error-margin"   guint                 : Read / Write / Construct
  "drag-inertia"             gdouble               : Read / Write / Construct
  "enabled"                  gboolean              : Read / Write / Construct
  "force"                    guint                 : Read / Write / Construct
  "hadjustment"              GtkAdjustment*        : Read
  "hovershoot-max"           gint                  : Read / Write / Construct
  "hscrollbar-policy"        GtkPolicyType         : Read / Write / Construct
  "initial-hint"             gboolean              : Read / Write / Construct
  "low-friction-mode"        gboolean              : Read / Write / Construct
  "mode"                     HildonPannableAreaMode  : Read / Write / Construct
  "mov-mode"                 HildonMovementMode    : Read / Write / Construct
  "panning-threshold"        guint                 : Read / Write / Construct
  "scroll-time"              gdouble               : Read / Write / Construct
  "scrollbar-fade-delay"     guint                 : Read / Write / Construct
  "size-request-policy"      HildonSizeRequestPolicy  : Read / Write / Construct
  "sps"                      guint                 : Read / Write / Construct
  "vadjustment"              GtkAdjustment*        : Read
  "velocity-fast-factor"     gdouble               : Read / Write / Construct
  "velocity-max"             gdouble               : Read / Write / Construct
  "velocity-min"             gdouble               : Read / Write / Construct
  "velocity-overshooting-max" gdouble               : Read / Write / Construct
  "vovershoot-max"           gint                  : Read / Write / Construct
  "vscrollbar-policy"        GtkPolicyType         : Read / Write / Construct

Style Properties

  "indicator-width"          guint                 : Read / Write

Signals

  "horizontal-movement"                            : Run Last / Action
  "panning-finished"                               
  "panning-started"                                
  "vertical-movement"                              : Run Last / Action

Description

HildonPannableArea is a container widget that can be "panned" (scrolled) up and down using the touchscreen with fingers. The widget has no scrollbars, but it rather shows small scroll indicators to give an idea of the part of the content that is visible at a time. The scroll indicators appear when a dragging motion is started on the pannable area.

The scrolling is "kinetic", meaning the motion can be "flicked" and it will continue from the initial motion by gradually slowing down to an eventual stop. The motion can also be stopped immediately by pressing the touchscreen over the pannable area.

Details

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

HILDON_PANNABLE_AREA_MODE_PUSH Areaing follows pointer
HILDON_PANNABLE_AREA_MODE_ACCEL Areaing uses physics to "spin" the widget
HILDON_PANNABLE_AREA_MODE_AUTO Automatically chooses between push and accel modes, depending on input.

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;

Warning

HildonSizeRequestPolicy is deprecated and should not be used in newly-written code. This define and the policy request is deprecated, DO NOT use it in future code. Check hildon_pannable_area_set_size_request_policy documentation for more information.

Used to control the size request policy of the widget

HILDON_SIZE_REQUEST_MINIMUM The minimum size the widget could use to paint itself
HILDON_SIZE_REQUEST_CHILDREN The minimum size of the children 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

Returns : the newly created HildonPannableArea

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

mode : HildonPannableAreaMode
enabled : Value for the enabled property
vel_min : Value for the velocity-min property
vel_max : Value for the velocity-max property
decel : Value for the deceleration property
sps : Value for the sps property
Returns : the newly create HildonPannableArea

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.

area : A HildonPannableArea
child : Child widget to add to the viewport

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.

Example 11. 

 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.

area : A HildonPannableArea.
x : The x coordinate of the destination point or -1 to ignore this axis.
y : The y coordinate of the destination point or -1 to ignore this axis.

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.

area : A HildonPannableArea.
x : The x coordinate of the destination point or -1 to ignore this axis.
y : The y coordinate of the destination point or -1 to ignore this axis.

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.

area : A HildonPannableArea.
child : A GtkWidget, descendant of area.

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.

area : A HildonPannableArea.
child : A GtkWidget, descendant of area.

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.

area : A HildonPannableArea.
x : horizontal coordinate of the point
y : vertical coordinate of the point
Returns : the GtkWidget if we find a widget, NULL in any other case

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.

area : A HildonPannableArea
Returns : the area "center-on-child-focus" value

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.

area : A HildonPannableArea
value : the new value

Since 2.2


hildon_pannable_area_get_size_request_policy ()

HildonSizeRequestPolicy hildon_pannable_area_get_size_request_policy
                                                        (HildonPannableArea *area);

Warning

hildon_pannable_area_get_size_request_policy is deprecated and should not be used in newly-written code. See hildon_pannable_area_set_size_request_policy()

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.

area : A HildonPannableArea.
Returns : the policy is currently being used in the widget HildonSizeRequestPolicy.

Since 2.2


hildon_pannable_area_set_size_request_policy ()

void                hildon_pannable_area_set_size_request_policy
                                                        (HildonPannableArea *area,
                                                         HildonSizeRequestPolicy size_request_policy);

Warning

hildon_pannable_area_set_size_request_policy is deprecated and should not be used in newly-written code. This method and the policy request is deprecated, DO NOT use it in future code, the only policy properly supported in gtk+ nowadays is the minimum size. Use gtk_window_set_default_size() or gtk_window_set_geometry_hints() with the proper size in your case to define the height of your dialogs.

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.

area : A HildonPannableArea.
size_request_policy : One of the allowed HildonSizeRequestPolicy

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.

area : A HildonPannableArea.
Returns : The horizontal GtkAdjustment

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.

area : A HildonPannableArea.
Returns : The vertical GtkAdjustment

Since 2.2

Property Details

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.

Warning

HildonPannableArea:size-request-policy is deprecated and should not be used in newly-written code. See hildon_pannable_area_set_size_request_policy()

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

Style Property Details

The "indicator-width" style property

  "indicator-width"          guint                 : Read / Write

Pixel width used to draw the scroll indicators.

Default value: 8

Signal Details

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).

hildonpannable : the object which received the signal
direction : the direction of the movement HILDON_MOVEMENT_LEFT or HILDON_MOVEMENT_RIGHT
initial_x : the x coordinate of the point where the user clicked to start the movement
initial_y : the y coordinate of the point where the user clicked to start the movement
user_data : user data set when the signal handler was connected.

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.

hildonpannable : the pannable area object that finished the panning
user_data : user data set when the signal handler was connected.

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).

hildonpannable : the pannable area object that is going to start the panning
user_data : user data set when the signal handler was connected.
Returns : TRUE to stop the panning launch. FALSE to continue with it.

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).

hildonpannable : the object which received the signal
direction : the direction of the movement HILDON_MOVEMENT_UP or HILDON_MOVEMENT_DOWN
initial_x : the x coordinate of the point where the user clicked to start the movement
initial_y : the y coordinate of the point where the user clicked to start the movement
user_data : user data set when the signal handler was connected.

Since 2.2

See Also

GtkScrolledWindow