/*
* 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