![]() |
![]() |
![]() |
Hildon Reference Manual | ![]() |
---|---|---|---|---|
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);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GtkBin +----HildonPannableArea
"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
"horizontal-movement" : Run Last / Action "panning-finished" "panning-started" "vertical-movement" : Run Last / Action
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.
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
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
typedef enum { HILDON_MOVEMENT_UP, HILDON_MOVEMENT_DOWN, HILDON_MOVEMENT_LEFT, HILDON_MOVEMENT_RIGHT } HildonMovementDirection;
Used to point out the direction of the movement
typedef enum { HILDON_SIZE_REQUEST_MINIMUM, HILDON_SIZE_REQUEST_CHILDREN } HildonSizeRequestPolicy;
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
typedef struct _HildonPannableArea HildonPannableArea;
HildonPannableArea has no publicly accessible fields
GtkWidget* hildon_pannable_area_new (void);
Create a new pannable area widget
Returns : | the newly created HildonPannableArea |
Since 2.2
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
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.
area : |
A HildonPannableArea |
child : |
Child widget to add to the viewport |
Since 2.2
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; 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
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
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
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
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
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
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
HildonSizeRequestPolicy hildon_pannable_area_get_size_request_policy (HildonPannableArea *area);
hildon_pannable_area_get_size_request_policy
is deprecated and should not be used in newly-written code.
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
void hildon_pannable_area_set_size_request_policy (HildonPannableArea *area, HildonSizeRequestPolicy size_request_policy);
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
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
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
"bounce-steps"
property"bounce-steps" guint : Read / Write / Construct
Number of steps that is going to be used to bounce when hitting theedge, the rubberband effect depends on it.
Default value: 3
"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
"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
"direction-error-margin"
property"direction-error-margin" guint : Read / Write / Construct
After detecting the direction of the movement (horizontal orvertical), we can add this margin of error to allow the movement inthe other direction even apparently it is not.
Default value: 10
"drag-inertia"
property"drag-inertia" gdouble : Read / Write / Construct
Percentage of the calculated speed in each moment we are are going to useto calculate the launch speed, the other part would be the speedcalculated previously.
Allowed values: [0,1]
Default value: 0.85
"enabled"
property"enabled" gboolean : Read / Write / Construct
Enable or disable finger-scroll.
Default value: TRUE
"force"
property"force" guint : Read / Write / Construct
Force applied to the movement, multiplies the calculated speed of theuser movement the cursor in the screen.
Default value: 50
"hadjustment"
property"hadjustment" GtkAdjustment* : Read
The GtkAdjustment for the horizontal position.
"hovershoot-max"
property"hovershoot-max" gint : Read / Write / Construct
Space we allow the widget to pass over its horizontal limits whenhitting the edges, set 0 in order to deactivate overshooting.
Allowed values: >= 0
Default value: 150
"hscrollbar-policy"
property"hscrollbar-policy" GtkPolicyType : Read / Write / Construct
Visual policy of the horizontal scrollbar.
Default value: GTK_POLICY_AUTOMATIC
"initial-hint"
property"initial-hint" gboolean : Read / Write / Construct
Whether to hint the user about the pannability of the container.
Default value: TRUE
"low-friction-mode"
property"low-friction-mode" gboolean : Read / Write / Construct
Avoid decelerating the panning movement, like no friction, the widgetwill stop in the edges or if the user clicks.
Default value: FALSE
"mode"
property"mode" HildonPannableAreaMode : Read / Write / Construct
Change the finger-scrolling mode.
Default value: HILDON_PANNABLE_AREA_MODE_AUTO
"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
"panning-threshold"
property"panning-threshold" guint : Read / Write / Construct
Amount of pixels to consider a motion event an scroll, if it is lessit is a click detected incorrectly by the touch screen.
Default value: 25
"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
"scrollbar-fade-delay"
property"scrollbar-fade-delay" guint : Read / Write / Construct
Time the scrollbar is going to be visible if the widget is not inaction in miliseconds.
Default value: 1000
"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
"sps"
property"sps" guint : Read / Write / Construct
Amount of scroll events to generate per second.
Default value: 20
"vadjustment"
property"vadjustment" GtkAdjustment* : Read
The GtkAdjustment for the vertical position.
"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
"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
"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
"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
"vovershoot-max"
property"vovershoot-max" gint : Read / Write / Construct
Space we allow the widget to pass over its vertical limits whenhitting the edges, set 0 in order to deactivate overshooting.
Allowed values: >= 0
Default value: 150
"vscrollbar-policy"
property"vscrollbar-policy" GtkPolicyType : Read / Write / Construct
Visual policy of the vertical scrollbar.
Default value: GTK_POLICY_AUTOMATIC
"indicator-width"
style property"indicator-width" guint : Read / Write
Pixel width used to draw the scroll indicators.
Default value: 8
"horizontal-movement"
signalvoid 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
"panning-finished"
signalvoid 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
"panning-started"
signalgboolean 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
"vertical-movement"
signalvoid 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