/*
* Copyright (c) 2006 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:
*
*/
#ifndef C_CMAPPLICATIONSETTINGSUI_H
#define C_CMAPPLICATIONSETTINGSUI_H
#include <e32def.h>
#include <e32base.h>
class CCmConnSettingsUiImpl;
namespace CMManager
{
/**
* CCmApplicationSettingsUi::RunApplicationSettingsL leaves with this
* error code if the selection dialog would have zero elements caused
* by filtering out all the Connection Methods with the aFilterArray
* and not requesting other list elements by the aListItems bitfield.
* See the comment of the RunApplicationSettingsL method for more
* detailes.
* This error code is supported by the error resolver.
*/
const TInt KErrConnectionNotFound = -32700;
/**
* The selection type of a list item in application settings UI
*/
enum TCmSettingSelectionMode
{
EAlwaysAsk, /**<
* The user selected Always ask
*/
EDestination, /**<
* The user selected a destination
*/
EConnectionMethod, /**<
* The user selected a connection method
*/
EDefaultConnection // The user selected Default Connection
};
/**
* These bitmasks controls what items does the selection UI containes.
* Bitmasks not listed in the enum are reserved for future usage and they
* are disabled by default. So extending these bitmasks does not cause
* BC break later.
*/
enum TCmSelectionDialogItems
{
EShowAlwaysAsk = 0x01, /**<
* AlwaysAsk is added to the
* selection UI.
*/
EShowDefaultConnection = 0x02, /**<
* DefaultConnection is added to the
* selection UI.
*/
/**
* The following enumerations controls how destinations and
* Connection Methods are presented in the selection UI.
* EShowDestinations is set and EShowConnectionMethods is set:
* Destination list is added to the selection UI and a Connection
* Method can be selected inside a Destination.
* EShowDestinations is set and EShowConnectionMethods is not set:
* Destination list is added to the selection UI and no Connection
* Method can be selected inside a Destination.
* EShowDestinations is not set and EShowConnectionMethods is set:
* Connection Method list is added to the selection UI. Connection
* Methods are ordered according to the global bearer type
* priorities. Destination cannot be selected.
* EShowDestinations is not set and EShowConnectionMethods is not set:
* The selection UI will not contain any Destination or Connection
* Method. E.g. If EShowAlwaysAsk and EShowDefaultConnection was set
* then the selection UI will contain two entries (AlwaysAsk and
* DefaultConnection).
*/
EShowDestinations = 0x04, /**<
* Destination list is added to the
* selection UI. Destinations which
* does not contain any Connection
* Methods are not shown.
*/
EShowConnectionMethods = 0x08, /**<
* If EShowDestinations is set:
* Connection Method can be selected
* inside a destination.
* If EShowDestinations is not set:
* Connection Method list is added to
* the selection UI.
*/
};
}// namespace CMManger
// Structs
/**
* Stores the details of a setting selection
*
* @lib cmmanager.lib
* @since S60 3.2
*/
NONSHARABLE_STRUCT( TCmSettingSelection )
{
/**
* Selection mode, refers to the type of the list item which is selected
*/
CMManager::TCmSettingSelectionMode iResult;
/**
* Id of the selected destination or connection method
*/
TUint iId;
};
/**
* Typedef of the bearer filter array.
* This type of array is used to filter Connection Methods
* by bearer types.
*
* The array elements are bearer IDs. The IDs are defined in the bearer
* type specific cmplugin...def.h files. E.g. the ID of the CSD bearer
* type (KUidCSDBearerType) can be found in the cmplugincsddef.h header.
*/
typedef RArray<TUint32> TBearerFilterArray;
/**
* For launching the Application Settings UI
*
* Displays a radio button page for an application used to select
* a destination or connection method
*
* @lib cmmanager.lib
* @since S60 3.2
*/
NONSHARABLE_CLASS( CCmApplicationSettingsUi ) : public CBase
{
public: // construction/destruction
/** Epoc constructor */
IMPORT_C static CCmApplicationSettingsUi* NewL();
/** Epoc constructor
* Pushes the object on the cleanup stack
*/
IMPORT_C static CCmApplicationSettingsUi* NewLC();
/** Destructor. */
virtual ~CCmApplicationSettingsUi();
//=======================================================================
// UI API
//
public:
/**
* Launches the 'easy to use' Settings UI provided for applications
* for handling Destinations and Connection Methods.
* This function call launches the same selection dialog as the
* the extended RunApplicationSettingsL do (see below) with the
* list items Default Connection, Destinations and Connection Methods
* without any filtering.
*
* @since 3.2
* @param aSelection If initialised to a valid value, sets the higlight to the
* corresponding list item at startup. If a list of Destinations is displayed, and
* the initial highlight is set to a Connection Method, the parent Destination
* gets highlighted. On return, holds user selection.
* @return TBool seleceted or not.
*/
IMPORT_C TBool RunApplicationSettingsL(
TCmSettingSelection& aSelection );
/**
* Launches the 'easy to use' Settings UI provided for applications
* for handling Destinations and Connection Methods
*
* @since 3.2
* @param aSelection If initialised to a valid value, sets the higlight to the
* corresponding list item at startup. If a list of Destinations is displayed, and
* the initial highlight is set to a Connection Method, the parent Destination
* gets highlighted. On return, holds user selection.
* @param aListItems A bit field which indicates which items shoud be
* shown in the selection dialog. The bitmasks are
* defined in the TCmSelectionDialogItems enum.
*
* The function leaves with KErrNotSupported if all the items which
* were set to be shown are not supported/enabled.
* E.g. Default Connection availability/support is controlled by the
* Feature Manager so if only EShowDefaultConnection is set and the
* Default Connection feature is not enabled than the function leaves
* with KErrNotSupported.
*
* In other cases (when an item or items are not supported/enabled but
* not all) the selected but not supported/enabled items are not added
* to the list. The request to show such an item is silently ignored.
*
*
* Special note about the EShowDestinations and EShowConnectionMethods
* bitmasks:
* The following enumerations controls how how destinations and
* Connection Methods are presented in the selection UI.
* General rule about the EShowDestinations:
* Destinations which does not contain any Connection Methods are
* not shown in the selection dialog. The same rule is applied if
* the Destination containes Connection Methods but all of them
* are filtered out by the filtering criteria.
* EShowDestinations is set and EShowConnectionMethods is set:
* Destination list is added to the selection UI and a Connection
* Method can be selected inside a Destination.
* EShowDestinations is set and EShowConnectionMethods is not set:
* Destination list is added to the selection UI and no Connection
* Method can be selected inside a Destination.
* EShowDestinations is not set and EShowConnectionMethods is set:
* Connection Method list is added to the selection UI. Connection
* Methods are ordered according to the global bearer type
* priorities. Destination cannot be selected.
* EShowDestinations is not set and EShowConnectionMethods is not set:
* The selection UI will not contain any Destination or Connection
* Method. E.g. If EShowAlwaysAsk and EShowDefaultConnection was
* set then the selection UI will contain two entries (AlwaysAsk
* and DefaultConnection).
*
* @param aFilterArray Only Connection Methods with bearer types from
* the aFilterArray will be shown.
* All Connection Methods will be listed if the
* array has no element.
* @return TBool seleceted or not.
*
* @leave KErrArgument If the selection dialog would have zero
* elements based on the aListItems bitmask
* (aListItems is equal to zero).
*
* @leave KErrNotSupported
* If the selection dialog would have zero
* elements based on the aListItems bitmask
* (all the selected elements in aListItems
* are not supported/disabled).
* E.g. aListItems = EShowDefaultConnection but
* Default Connection feature is not enabled.
*
* @leave KErrConnectionNotFound
* If the selection dialog would have zero
* elements caused by filtering out all the
* Connection Methods with the aFilterArray
* and not requesting other list elements by
* the aListItems bitfield than the function
* call leaves with KErrConnectionNotFound
* error code. A corresponding error note can
* be shown using the error resolver.
* E.g.
* - aListItems = EShowConnectionMethods
* but all Connection Methods are filtered
* out by the aFilterArray.
*/
IMPORT_C TBool RunApplicationSettingsL(
TCmSettingSelection& aSelection,
TUint aListItems,
TBearerFilterArray& aFilterArray);
private:
/** C++ constructor */
CCmApplicationSettingsUi();
/**
* Epoc 2nd phase constructor
*
* @since S60 3.2
*/
void ConstructL();
private: // data
/**
* implementation of the class
*/
CCmConnSettingsUiImpl* iImpl;
};
#endif // C_CMAPPLICATIONSETTINGSUI_H