--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmuifw_plat/alf_widgetmodel_api/inc/alf/ialfnavigation.h Thu Dec 17 08:56:02 2009 +0200
@@ -0,0 +1,290 @@
+/*
+* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Navigation interface for list-like widgets.
+*
+*/
+
+
+
+#ifndef I_ALFNAVIGATION_H
+#define I_ALFNAVIGATION_H
+
+#include <alf/ialfinterfacebase.h>
+
+namespace Alf
+ {
+
+namespace alfnavigation
+ {
+static const IfId ident =
+ {
+ 0, "alfnavigation"
+ };
+ }
+
+/**
+* An interface that defines functionality for navigation in a
+* one-dimensional array of items. In addition to the normal
+* one-dimansional behavior, a common use case is to have
+* a two-dimensional layout and navigation model for the items.
+* Therefore, both one- and two-dimensional navigation models are
+* supported by the interface.
+*
+* Since the logical behavior is decoupled from the presentation,
+* the navigation is controlled in terms of logical dimensions,
+* namely the primary and the secondary dimensions. The primary
+* dimension is the dimension in which the navigation space
+* expands when new items are inserted. In a one-dimensional layout,
+* only the primary dimension is needed. The secondary dimension
+* is used with two-dimensional layouts and navigation models.
+* The size of the navigation space in the secondary dimension
+* should be a constant.
+*
+* The navigation interface consists of navigation parameters,
+* scrolling parameters, and orientation parameters. The navigation
+* parameters are used to control the focused item in the logical
+* navigation events. The scrolling parameters are used to send
+* scrolling events according to the focused item. The orientation
+* parameters are used to convert directional navigation events
+* to the logical navigation events. In addition, the usage of
+* default navigation key events, i.e., arrow keys, can be enabled
+* or disabled.
+*
+* @lib alfwidgetmodel.lib
+* @since S60 ?S60_version
+* @status Draft
+*/
+class IAlfNavigation : public IAlfInterfaceBase
+ {
+public:
+ /**
+ * Getter for the type identifier of this interface.
+ *
+ * @since S60 ?S60_version
+ * @return A descriptor to identify the type of this interface.
+ */
+ static inline const IfId& type()
+ {
+ return alfnavigation::ident;
+ }
+
+ /**
+ * Getter for the index of the currently focused item.
+ *
+ * @since S60 ?S60_version
+ * @return An index of the currently focused item.
+ */
+ virtual int focusedIndex() const = 0;
+
+ /**
+ * Setter for the index of the currently focused item.
+ * If the given index is outside the range of items,
+ * the index is set to the first or the last index.
+ *
+ * @since S60 ?S60_version
+ * @param aIndex The new index of the focused item.
+ */
+ virtual void setFocusedIndex( int aIndex ) = 0;
+
+ /**
+ * Getter for the size of the page in primary dimension.
+ * The page size is used for EEventNavigatePrimaryPageUp and
+ * EEventNavigatePrimaryPageDown events, as well as for scrolling
+ * in primary dimension.
+ *
+ * @since S60 ?S60_version
+ * @return The page size in primary dimension.
+ */
+ virtual int primaryPageSize() const = 0;
+
+ /**
+ * Getter for the size of the page in secondary dimension.
+ * The page size is used for EEventNavigateSecondaryPageUp and
+ * EEventNavigateSecondaryPageDown events, as well as for scrolling
+ * in secondary dimension.
+ *
+ * @since S60 ?S60_version
+ * @return The page size in secondary dimension.
+ */
+ virtual int secondaryPageSize() const = 0;
+
+ /**
+ * Getter for the size of the navigation space in secondary dimension.
+ * One step in the primary dimension changes the index of the focused
+ * item by the secondary size. The size is also used for scrolling
+ * in secondary dimension. The secondary size of a one-dimensional
+ * list should be one.
+ *
+ * @since S60 ?S60_version
+ * @return The size in secondary dimension.
+ */
+ virtual int secondarySize() const = 0;
+
+ /**
+ * Getter for looping in primary dimension.
+ *
+ * @since S60 ?S60_version
+ * @return <code>true</code> if the looping is enabled,
+ * <code>false</code> otherwise.
+ */
+ virtual bool primaryLooping() const = 0;
+
+ /**
+ * Getter for looping in secondary dimension.
+ *
+ * @since S60 ?S60_version
+ * @return <code>true</code> if the looping is enabled,
+ * <code>false</code> otherwise.
+ */
+ virtual bool secondaryLooping() const = 0;
+
+ /**
+ * Set the navigation parameters for one-dimensional navigation.
+ * The secondary size and the secondary page size are set to one,
+ * to indicate that navigation and scrolling in secondary direction
+ * is disabled. Also the secondary looping is disabled.
+ *
+ * @since S60 ?S60_version
+ * @param aPrimaryPageSize The page size in primary dimension.
+ * @param aPrimaryLooping Enable or disable looping.
+ */
+ virtual void setNavigationParams( int aPrimaryPageSize,
+ bool aPrimaryLooping ) = 0;
+
+ /**
+ * Set the navigation parameters for two-dimensional navigation.
+ * The parameters determine the behavior of all navigation events.
+ * Navigation and scrolling are supported in both dimensions.
+ * If the secondary page size is equal to the size of the whole
+ * navigation space, the scrolling in secondary dimension is disabled.
+ *
+ * @since S60 ?S60_version
+ * @param aPrimaryPageSize The page size in primary dimension.
+ * @param aPrimaryLooping Enable or disable looping.
+ */
+ virtual void setNavigationParams( int aPrimaryPageSize,
+ int aSecondarySize,
+ int aSecondaryPageSize,
+ bool aPrimaryLooping,
+ bool aSecondaryLooping ) = 0;
+
+ /**
+ * Getter for scrolling distance in primary dimension.
+ * The scrolling distance is the minimum number of items before
+ * the first or the last visible item. For example, the scrolling
+ * distance of one defines that the focus should never get to the
+ * first or the last visible item, except in the beginning or the
+ * end of the list.
+ *
+ * @since S60 ?S60_version
+ * @return The scrolling distance in primary dimension.
+ */
+ virtual int primaryScrollingDist() const = 0;
+
+ /**
+ * Getter for scrolling distance in secondary dimension.
+ *
+ * @since S60 ?S60_version
+ * @return The scrolling distance in secondary dimension.
+ */
+ virtual int secondaryScrollingDist() const = 0;
+
+ /**
+ * Set the scrolling distances for the list control.
+ * The scrolling distances are used to determine when
+ * to start scrolling. The scrolling distance of zero
+ * indicates that the scrolling should start if the focus
+ * is moved outside of the visible items. Similarly,
+ * the scrolling distance of one indicates that the
+ * scrolling should start when the first or the last
+ * visible item is focused.
+ *
+ * @param aPrimaryScrollingDist The minimum number of items before the first
+ * or the last visible item in primary dimension.
+ * @param aSecondaryScrollingDist The minimum number of items before the first
+ * or the last visible item in secondary dimension.
+ * @since S60 ?S60_version
+ */
+ virtual void setScrollingParams( int aPrimaryScrollingDist,
+ int aSecondaryScrollingDist ) = 0;
+
+ /**
+ * Determine if the primary dimension on the screen is vertical.
+ * This is used to convert directional navigation events to the
+ * logical navigation events.
+ *
+ * @since S60 ?S60_version
+ * @return <code>true</code> if the primary dimension is vertical,
+ * <code>false</code> if the primary dimension is horizontal.
+ */
+ virtual bool verticalPrimary() const = 0;
+
+ /**
+ * Determine if the indices in the navigation space
+ * increase from left to right. This is used to determine
+ * the direction of the horizontal navigation events.
+ *
+ * @since S60 ?S60_version
+ * @return <code>true</code> if the indices increase from left to right,
+ * <code>false</code> if the indices increase from right to left.
+ */
+ virtual bool leftToRight() const = 0;
+
+ /**
+ * Determine if the indices in the navigation space
+ * increase from up to down. This is used to determine
+ * the direction of the vertical navigation events.
+ *
+ * @since S60 ?S60_version
+ * @return <code>true</code> if the indices increase from up to down,
+ * <code>false</code> if the indices increase from down to up.
+ */
+ virtual bool upToDown() const = 0;
+
+ /**
+ * Set the orientation parameters.
+ * The orientation parameters are used to convert directional
+ * navigation events to logical navigation events.
+ *
+ * @since S60 ?S60_version
+ * @param aVerticalPrimary Specify the orientation of the primary dimension.
+ * @param aLeftToRight Specify the increasing order of horizontal indices.
+ * @param aUpToDown Specify the increasing order of vertical indices.
+ */
+ virtual void setOrientationParams( bool aVerticalPrimary,
+ bool aLeftToRight, bool aUpToDown ) = 0;
+
+ /**
+ * Determine if the default key events are used for navigation.
+ *
+ * @since S60 ?S60_version
+ * @return <code>true</code> if the default key events are used,
+ * <code>false</code> otherwise.
+ */
+ virtual bool defaultKeysEnabled() const = 0;
+
+ /**
+ * Enable or disable the default key events.
+ *
+ * @since S60 ?S60_version
+ * @param aEnable The usage of the default key events.
+ */
+ virtual void enableDefaultKeys( bool aEnable ) = 0;
+ };
+
+ } // namespace Alf
+
+#endif // I_ALFNAVIGATION_H
+
+// End of File