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