// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "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:

// <hr>

// It should be assumed that it is only possible for CAF agents to display 

// dialogs on screen if the CAF function is called from a thread where

// a static Uikon environment exists.

// <hr>

// CAF provides several APIs that allow a client application to request an agent to

// display information on the screen. Some agents may not support these calls and leave 

// with \c KErrCANotSupported.

// Both the <code>ContentAccess::CContent::DisplayInfoL()</code> function and the 

// <code>ContentAccess::CManager::DisplayInfoL()</code> function allow the application 

// to display file information such as last modification date and/or DRM rights information

// CManager *manager = CManager::NewL();

// manager->DisplayInfoL(EFileProperties, avirtualPath);

// Applications can also ask a particular agent to go into management mode, displaying configuration 

// information on screen, allowing the user to view and set agent specific information.

// // create manager

// CManager *manager = CManager::NewL();

// // Get a list of the agents

// RPointerArray <CAgent> theAgents;

// manager->ListAgentsL(theAgents);

// // Display management info for the first agent

// manager->DisplayManagementInfoL(*theAgents[0]);

// <hr> 

// The agents will display errors on screen when they occur. Once the error has been acknowledged by the user

// the agent will return the error code to the client application.

// If a client application does not want errors displayed on screen, it can request to disable the agent UI 

// using the <code>SetProperty()</code> functions, e.g. <code>ContentAccess::CContent::SetProperty()</code>. 

// The agent may ignore this request and still present dialogs on screen.

// CContent *content = CContent::NewL(URI);

// // Disable UI

// content->SetProperty(EAgentPropertyAgentUI , 0);

// // Open CData 

// CData *data = content->OpenContentL(EPlay, uniqueId);

// <hr> 

// Some agents may present confirmation dialogs to the user before allowing them to perform certain operations. A 

// good example would be when an application tries to delete a DRM protected file. The user may have been purchased the

// content and may have inadvertently pressed delete. The agent can present a dialog asking "are you sure?"

// The agent can then return the outcome of the delete to the application, i.e. \c KErrCancel, if the user presses cancel.

// The application can use the same <code>SetProperty()</code> as above to disable these dialogs, but some agents may ignore that 

// request and display the dialogs regardless.

// <hr>

// The default implementation of the <code>F32AgentUI.DLL</code> does not do anything. If licensees want the

// \c F32Agent to display information on the screen they should replace the existing <code>F32AgentUI.DLL</code>

// with one that does support display functions.

// 

//

/**

 @page CAFUI CAF and the User Interface

 - @ref UikonEnv

 - @ref AppDisplay

 - @ref UIErr

 - @ref UIConfirmation

 - @ref F32AgentUi

 @section UikonEnv Uikon Environment

 @section AppDisplay Applications asking the agent to display information

 @code

 @endcode

 @code

 @endcode

 @section UIErr Error Handling

 @code

 @endcode

 @section UIConfirmation Confirmation Dialogs

 @section F32AgentUi F32 Agent UI

*/