<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 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: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-EB76BA4B-D6A2-5651-A310-647E1D2CDEBC" xml:lang="en"><title>User

Interface MTM</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>User Interface (UI) MTMs offer user interface capabilities, such as viewing,

editing and copying of messages. Users interact with different message types

in different ways. For example, a messaging protocol that supports attachments

needs a more feature-rich editor than one that only supports text. UI MTMs

allows a developer to produce user interface components to suit these differing

requirements. Some Messaging protocols do not need any user interaction at

all: in such cases, a UI MTM component does not need to be implemented. </p>

<p>UI MTMs offer some or all of the following capabilities: </p>

<ul>

<li id="GUID-6832B4D6-633A-5C74-ADE6-9DFC956D896E"><p>Message viewing </p> </li>

<li id="GUID-09F1E9E0-1A40-5AD9-BF2B-FC46FF3E91BF"><p>Message editing </p> </li>

<li id="GUID-AFF6F519-F5DE-5F3B-BCFC-605759B9AEBB"><p>Folder manipulation </p> </li>

<li id="GUID-DBF12F1E-974B-5E41-AB67-8726D5196262"><p>Editing service settings </p> </li>

<li id="GUID-B0473D77-B689-5147-B5D3-85C92812BD83"><p>Providing

pre-transfer or connection settings UI </p> </li>

<li id="GUID-1A1FEA3D-21A0-51A3-BD4D-6C65B4C023CC"><p>Providing pre-transfer

preparation of messages before sending </p> </li>

<li id="GUID-31A3FA9B-155A-59D2-8263-A0DE8213F681"><p>Interpreting and displaying

mail transfer progress </p> </li>

<li id="GUID-EF964F08-1D1B-5321-81F1-B5EEB0E1F977"><p>Interpreting and displaying

error conditions </p> </li>

</ul>

<section><title>UI MTM base class</title> <p>The base class for UI MTMs is <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita"><apiname>CBaseMtmUi</apiname></xref>.

Message client applications use the class to access the functionality polymorphically.

Many functions are required to return an instance of a <xref href="GUID-AF724192-6580-3DE3-9287-3A005C0AA932.dita"><apiname>CMsvOperation</apiname></xref> derived

class to provide asynchronous control and monitoring to the caller of the

operation being performed. </p> <p>The following are some significant functions

that can be implemented in a class derived from the <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita"><apiname>CBaseMtmUi</apiname></xref> base

class: </p> <ul>

<li id="GUID-CEC38AC9-4FF6-56C9-BEB7-75BD4BB1D064"><p> <b>Entry manipulation

functions</b>  </p> <p>The <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-0DD6B979-0473-3AAD-AE14-F1B0AC1E73C5"><apiname>CBaseMtmUi::OpenL()</apiname></xref>, <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-F7895B4B-21B8-36BD-A1B7-F66C4013871B"><apiname>CBaseMtmUi::CloseL()</apiname></xref>, <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-E637CFD7-6055-3581-B804-34889E83CB10"><apiname>CBaseMtmUi::EditL()</apiname></xref>, and <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-036C63AE-0289-3718-9588-3D0539F48522"><apiname>CBaseMtmUi::ViewL()</apiname></xref> functions are entry manipulation

functions. They are all available in two overloaded versions. The first version

operates on the current context. The second version operates upon groups of

entries specified by a <xref href="GUID-6BC8851B-D913-3CE5-B343-5163661E8AD5.dita"><apiname>CMsvEntrySelection</apiname></xref> argument. All

entries must be in same folder and all of the correct MTM type. The context

may change after calling these functions. </p> </li>

<li id="GUID-F8613B65-9C4F-5174-BC04-2169BF985A34"><p> <b>Copying and moving

functions</b>  </p> <p>The <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-5CDA28D4-070B-38D4-ABA8-1DBEF5216721"><apiname>CBaseMtmUi::CopyToL()</apiname></xref>, <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-CF9EC3B2-A56B-31E4-AEBE-D65E440BD5CA"><apiname>CBaseMtmUi::CopyFromL()</apiname></xref>, <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-11AD0A75-CA8D-336B-B2EB-5CBC0996C1CE"><apiname>CBaseMtmUi::MoveToL()</apiname></xref>, and <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-2D4A6DC2-9FB7-3B2B-AAFE-CCDEAAE262A8"><apiname>CBaseMtmUi::MoveFromL()</apiname></xref> functions copy and move

entries to and from remote servers. MTMs can implement these functions to

provide any user interaction needed before copying or moving can proceed,

such as dialog to confirm settings. </p> </li>

<li id="GUID-7311A06E-94BE-5AF7-8345-07A29AED20AA"><p> <b>Progress information

functions</b>  </p> <p>The <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-3A65055B-C48B-3E45-B097-6C63C974259F"><apiname>CBaseMtmUi::DisplayProgressSummary()</apiname></xref> and <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-F67FCA0E-510C-3A45-B196-8B60BC2D5208"><apiname>CBaseMtmUi::GetProgress()</apiname></xref> progress

information functions convert MTM-specific progress information about some

asynchronous operation, such as message sending, to a human-readable form.

The progress information to pass into these functions is, in general, obtained

from an on-going <xref href="GUID-AF724192-6580-3DE3-9287-3A005C0AA932.dita"><apiname>CMsvOperation</apiname></xref> by calling <xref href="GUID-AF724192-6580-3DE3-9287-3A005C0AA932.dita#GUID-AF724192-6580-3DE3-9287-3A005C0AA932/GUID-5814F4B0-F8B6-36C6-8E69-11554BA62BA7"><apiname>CMsvOperation::Progress()</apiname></xref>.

The nature of any information provided by these functions is MTM-specific. </p> </li>

<li id="GUID-00644644-BD9E-548B-82B3-4E166A86B414"><p> <b>MTM-specific UI

functions</b>  </p> <p>MTM components can offer protocol-specific functionality

not provided by base class interface functions. MTM components define IDs

that correspond to each protocol-specific operation offered, and implement

the <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-3F350426-30C3-3BD0-8245-F13E72CEDC7C"><apiname>CBaseMtmUi::InvokeSyncFunctionL()</apiname></xref> and <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita#GUID-A5982338-A057-3870-8832-F503AEAC470A/GUID-78637126-6EEF-318D-B1D3-A24055EE8AD5"><apiname>CBaseMtmUi::InvokeAsyncFunctionL()</apiname></xref> functions

to allow clients to access these operations by passing in the appropriate

ID. Two functions are provided to allow the MTM component to offer both synchronous

and asynchronous functionality. Message client applications can dynamically

add user-interface features for these operations using <xref href="GUID-899C6D87-5712-34A7-902C-EA452894700C.dita#GUID-899C6D87-5712-34A7-902C-EA452894700C/GUID-75DE35D7-4738-38C0-9BFA-A066F67B114B"><apiname>CBaseMtmUiData::MtmSpecificFunctions()</apiname></xref>. </p> </li>

</ul> <p>The <xref href="GUID-A5982338-A057-3870-8832-F503AEAC470A.dita"><apiname>CBaseMtmUi</apiname></xref> class provides the virtual functions

for overriding in derived classes.</p> </section>

<section><title>Editors and viewers</title> <p>Functionality to edit and view

messages may be one of the larger programming tasks in creating an MTM. Such

functionality is typically implemented in separate DLLs that the UI MTM loads

as required, to reduce the memory footprint of a UI MTM. </p> </section>

</conbody><related-links>

<link href="GUID-59217FA7-3078-53CA-88B3-78D6FB788271.dita"><linktext>MTM     

           overview</linktext></link>

<link href="GUID-BAD138D5-2914-5C6E-9FA4-F7A3CCB85E6D.dita"><linktext>MTM     

           Capabilities</linktext></link>

<link href="GUID-133999E8-0ACB-5929-949E-82BB16F8E267.dita"><linktext>Writing a

UI MTM </linktext></link>