1.1 --- a/epoc32/include/mw/cmapplicationsettingsui.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/cmapplicationsettingsui.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,300 @@
1.4 -cmapplicationsettingsui.h
1.5 +/*
1.6 +* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description:
1.19 +*
1.20 +*/
1.21 +
1.22 +#ifndef C_CMAPPLICATIONSETTINGSUI_H
1.23 +#define C_CMAPPLICATIONSETTINGSUI_H
1.24 +
1.25 +#include <E32def.h>
1.26 +#include <e32base.h>
1.27 +
1.28 +class CCmConnSettingsUiImpl;
1.29 +namespace CMManager
1.30 + {
1.31 +
1.32 + /**
1.33 + * CCmApplicationSettingsUi::RunApplicationSettingsL leaves with this
1.34 + * error code if the selection dialog would have zero elements caused
1.35 + * by filtering out all the Connection Methods with the aFilterArray
1.36 + * and not requesting other list elements by the aListItems bitfield.
1.37 + * See the comment of the RunApplicationSettingsL method for more
1.38 + * detailes.
1.39 + * This error code is supported by the error resolver.
1.40 + */
1.41 + const TInt KErrConnectionNotFound = -32700;
1.42 +
1.43 + /**
1.44 + * The selection type of a list item in application settings UI
1.45 + */
1.46 + enum TCmSettingSelectionMode
1.47 + {
1.48 + EAlwaysAsk, /**<
1.49 + * The user selected Always ask
1.50 + */
1.51 + EDestination, /**<
1.52 + * The user selected a destination
1.53 + */
1.54 + EConnectionMethod, /**<
1.55 + * The user selected a connection method
1.56 + */
1.57 + EDefaultConnection // The user selected Default Connection
1.58 +
1.59 + };
1.60 +
1.61 +
1.62 + /**
1.63 + * These bitmasks controls what items does the selection UI containes.
1.64 + * Bitmasks not listed in the enum are reserved for future usage and they
1.65 + * are disabled by default. So extending these bitmasks does not cause
1.66 + * BC break later.
1.67 + */
1.68 + enum TCmSelectionDialogItems
1.69 + {
1.70 + EShowAlwaysAsk = 0x01, /**<
1.71 + * AlwaysAsk is added to the
1.72 + * selection UI.
1.73 + */
1.74 + EShowDefaultConnection = 0x02, /**<
1.75 + * DefaultConnection is added to the
1.76 + * selection UI.
1.77 + */
1.78 +
1.79 + /**
1.80 + * The following enumerations controls how destinations and
1.81 + * Connection Methods are presented in the selection UI.
1.82 + * EShowDestinations is set and EShowConnectionMethods is set:
1.83 + * Destination list is added to the selection UI and a Connection
1.84 + * Method can be selected inside a Destination.
1.85 + * EShowDestinations is set and EShowConnectionMethods is not set:
1.86 + * Destination list is added to the selection UI and no Connection
1.87 + * Method can be selected inside a Destination.
1.88 + * EShowDestinations is not set and EShowConnectionMethods is set:
1.89 + * Connection Method list is added to the selection UI. Connection
1.90 + * Methods are ordered according to the global bearer type
1.91 + * priorities. Destination cannot be selected.
1.92 + * EShowDestinations is not set and EShowConnectionMethods is not set:
1.93 + * The selection UI will not contain any Destination or Connection
1.94 + * Method. E.g. If EShowAlwaysAsk and EShowDefaultConnection was set
1.95 + * then the selection UI will contain two entries (AlwaysAsk and
1.96 + * DefaultConnection).
1.97 + */
1.98 + EShowDestinations = 0x04, /**<
1.99 + * Destination list is added to the
1.100 + * selection UI. Destinations which
1.101 + * does not contain any Connection
1.102 + * Methods are not shown.
1.103 + */
1.104 + EShowConnectionMethods = 0x08, /**<
1.105 + * If EShowDestinations is set:
1.106 + * Connection Method can be selected
1.107 + * inside a destination.
1.108 + * If EShowDestinations is not set:
1.109 + * Connection Method list is added to
1.110 + * the selection UI.
1.111 + */
1.112 + };
1.113 +
1.114 + }// namespace CMManger
1.115 +
1.116 +
1.117 + // Structs
1.118 +
1.119 +/**
1.120 + * Stores the details of a setting selection
1.121 + *
1.122 + * @lib cmmanager.lib
1.123 + * @since S60 3.2
1.124 + */
1.125 +NONSHARABLE_STRUCT( TCmSettingSelection )
1.126 + {
1.127 + /**
1.128 + * Selection mode, refers to the type of the list item which is selected
1.129 + */
1.130 + CMManager::TCmSettingSelectionMode iResult;
1.131 +
1.132 + /**
1.133 + * Id of the selected destination or connection method
1.134 + */
1.135 + TUint iId;
1.136 + };
1.137 +
1.138 +/**
1.139 +* Typedef of the bearer filter array.
1.140 +* This type of array is used to filter Connection Methods
1.141 +* by bearer types.
1.142 +*
1.143 +* The array elements are bearer IDs. The IDs are defined in the bearer
1.144 +* type specific cmplugin...def.h files. E.g. the ID of the CSD bearer
1.145 +* type (KUidCSDBearerType) can be found in the cmplugincsddef.h header.
1.146 +*/
1.147 +typedef RArray<TUint32> TBearerFilterArray;
1.148 +
1.149 +/**
1.150 + * For launching the Application Settings UI
1.151 + *
1.152 + * Displays a radio button page for an application used to select
1.153 + * a destination or connection method
1.154 + *
1.155 + * @lib cmmanager.lib
1.156 + * @since S60 3.2
1.157 + */
1.158 +NONSHARABLE_CLASS( CCmApplicationSettingsUi ) : public CBase
1.159 + {
1.160 +
1.161 + public: // construction/destruction
1.162 +
1.163 + /** Epoc constructor */
1.164 + IMPORT_C static CCmApplicationSettingsUi* NewL();
1.165 +
1.166 + /** Epoc constructor
1.167 + * Pushes the object on the cleanup stack
1.168 + */
1.169 + IMPORT_C static CCmApplicationSettingsUi* NewLC();
1.170 +
1.171 + /** Destructor. */
1.172 + virtual ~CCmApplicationSettingsUi();
1.173 +
1.174 + //=======================================================================
1.175 + // UI API
1.176 + //
1.177 + public:
1.178 +
1.179 + /**
1.180 + * Launches the 'easy to use' Settings UI provided for applications
1.181 + * for handling Destinations and Connection Methods.
1.182 + * This function call launches the same selection dialog as the
1.183 + * the extended RunApplicationSettingsL do (see below) with the
1.184 + * list items Default Connection, Destinations and Connection Methods
1.185 + * without any filtering.
1.186 + *
1.187 + * @since 3.2
1.188 + * @param aSelection If initialised to a valid value, sets the higlight to the
1.189 + * corresponding list item at startup. If a list of Destinations is displayed, and
1.190 + * the initial highlight is set to a Connection Method, the parent Destination
1.191 + * gets highlighted. On return, holds user selection.
1.192 + * @return TBool seleceted or not.
1.193 + */
1.194 + IMPORT_C TBool RunApplicationSettingsL(
1.195 + TCmSettingSelection& aSelection );
1.196 +
1.197 + /**
1.198 + * Launches the 'easy to use' Settings UI provided for applications
1.199 + * for handling Destinations and Connection Methods
1.200 + *
1.201 + * @since 3.2
1.202 + * @param aSelection If initialised to a valid value, sets the higlight to the
1.203 + * corresponding list item at startup. If a list of Destinations is displayed, and
1.204 + * the initial highlight is set to a Connection Method, the parent Destination
1.205 + * gets highlighted. On return, holds user selection.
1.206 + * @param aListItems A bit field which indicates which items shoud be
1.207 + * shown in the selection dialog. The bitmasks are
1.208 + * defined in the TCmSelectionDialogItems enum.
1.209 + *
1.210 + * The function leaves with KErrNotSupported if all the items which
1.211 + * were set to be shown are not supported/enabled.
1.212 + * E.g. Default Connection availability/support is controlled by the
1.213 + * Feature Manager so if only EShowDefaultConnection is set and the
1.214 + * Default Connection feature is not enabled than the function leaves
1.215 + * with KErrNotSupported.
1.216 + *
1.217 + * In other cases (when an item or items are not supported/enabled but
1.218 + * not all) the selected but not supported/enabled items are not added
1.219 + * to the list. The request to show such an item is silently ignored.
1.220 + *
1.221 + *
1.222 + * Special note about the EShowDestinations and EShowConnectionMethods
1.223 + * bitmasks:
1.224 + * The following enumerations controls how how destinations and
1.225 + * Connection Methods are presented in the selection UI.
1.226 + * General rule about the EShowDestinations:
1.227 + * Destinations which does not contain any Connection Methods are
1.228 + * not shown in the selection dialog. The same rule is applied if
1.229 + * the Destination containes Connection Methods but all of them
1.230 + * are filtered out by the filtering criteria.
1.231 + * EShowDestinations is set and EShowConnectionMethods is set:
1.232 + * Destination list is added to the selection UI and a Connection
1.233 + * Method can be selected inside a Destination.
1.234 + * EShowDestinations is set and EShowConnectionMethods is not set:
1.235 + * Destination list is added to the selection UI and no Connection
1.236 + * Method can be selected inside a Destination.
1.237 + * EShowDestinations is not set and EShowConnectionMethods is set:
1.238 + * Connection Method list is added to the selection UI. Connection
1.239 + * Methods are ordered according to the global bearer type
1.240 + * priorities. Destination cannot be selected.
1.241 + * EShowDestinations is not set and EShowConnectionMethods is not set:
1.242 + * The selection UI will not contain any Destination or Connection
1.243 + * Method. E.g. If EShowAlwaysAsk and EShowDefaultConnection was
1.244 + * set then the selection UI will contain two entries (AlwaysAsk
1.245 + * and DefaultConnection).
1.246 + *
1.247 + * @param aFilterArray Only Connection Methods with bearer types from
1.248 + * the aFilterArray will be shown.
1.249 + * All Connection Methods will be listed if the
1.250 + * array has no element.
1.251 + * @return TBool seleceted or not.
1.252 + *
1.253 + * @leave KErrArgument If the selection dialog would have zero
1.254 + * elements based on the aListItems bitmask
1.255 + * (aListItems is equal to zero).
1.256 + *
1.257 + * @leave KErrNotSupported
1.258 + * If the selection dialog would have zero
1.259 + * elements based on the aListItems bitmask
1.260 + * (all the selected elements in aListItems
1.261 + * are not supported/disabled).
1.262 + * E.g. aListItems = EShowDefaultConnection but
1.263 + * Default Connection feature is not enabled.
1.264 + *
1.265 + * @leave KErrConnectionNotFound
1.266 + * If the selection dialog would have zero
1.267 + * elements caused by filtering out all the
1.268 + * Connection Methods with the aFilterArray
1.269 + * and not requesting other list elements by
1.270 + * the aListItems bitfield than the function
1.271 + * call leaves with KErrConnectionNotFound
1.272 + * error code. A corresponding error note can
1.273 + * be shown using the error resolver.
1.274 + * E.g.
1.275 + * - aListItems = EShowConnectionMethods
1.276 + * but all Connection Methods are filtered
1.277 + * out by the aFilterArray.
1.278 + */
1.279 + IMPORT_C TBool RunApplicationSettingsL(
1.280 + TCmSettingSelection& aSelection,
1.281 + TUint aListItems,
1.282 + TBearerFilterArray& aFilterArray);
1.283 +
1.284 + private:
1.285 +
1.286 + /** C++ constructor */
1.287 + CCmApplicationSettingsUi();
1.288 +
1.289 + /**
1.290 + * Epoc 2nd phase constructor
1.291 + *
1.292 + * @since S60 3.2
1.293 + */
1.294 + void ConstructL();
1.295 +
1.296 + private: // data
1.297 +
1.298 + /**
1.299 + * implementation of the class
1.300 + */
1.301 + CCmConnSettingsUiImpl* iImpl;
1.302 + };
1.303 +
1.304 +#endif // C_CMAPPLICATIONSETTINGSUI_H