<?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>
</related-links></concept>