Symbian3/PDK/Source/GUID-96C49728-8C78-4D82-876D-6B1196362D44.dita
author Dominic Pinkman <Dominic.Pinkman@Nokia.com>
Tue, 30 Mar 2010 11:56:28 +0100
changeset 5 f345bda72bc4
parent 3 46218c8b8afa
child 14 578be2adaf3e
permissions -rw-r--r--
Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"

<?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-96C49728-8C78-4D82-876D-6B1196362D44" xml:lang="en"><title>Setting
button properties not specific to any state</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-03E298C7-E545-423F-B1FE-52EDDFEDEDC9">       <title>Button
frame</title>       <p>If the button has a frame, change its features by setting
new frame IDs using the method <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#9307c6a78e16837dddf3d55ad462cd03" format="application/java-archive"><codeph>SetFrameAndCenterIds()</codeph></xref> in the class <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html" format="application/java-archive"><codeph>CAknButton</codeph></xref>. </p><p>Use the flag <codeph>KAknButtonStateHasLatchedFrame</codeph> for
a button state to set whether the frame for the button in the state in question
should look latched down. </p><p>To disable the frame for the button, use
the <codeph>KAknButtonNoFrame</codeph> flag.</p>     </section>
<section id="GUID-3ED77835-CFA7-45EB-8DC7-548A46C39936"><title>Button text</title><p>By
default, the button text is truncated to fit the size of the button. Use the <codeph>KAknButtonSizeFitText</codeph> flag
to make the method <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#f42c28866284991b8ee1a9717498f245" format="application/java-archive"><codeph>MinimumSize()</codeph></xref> return the size into which the text fits. To change the font, color,
and alignment of the text, use the following methods in <codeph>CAknButton</codeph>:</p><ul>
<li><p><xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#cfb256140a4d572c62e88e6bd44b9cf4" format="application/java-archive"><codeph>SetTextFont()</codeph></xref></p></li>
<li><p><xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#6fb1525ce1a318954ab760ff09851e0f" format="application/java-archive"><codeph>SetTextColorIds()</codeph></xref></p></li>
<li><p><xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#ef346ee5cbe9492b00eddf7f145fcad8" format="application/java-archive"><codeph>SetTextHorizontalAlignment()</codeph></xref></p></li>
<li><p><xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#6edfd9a6ac89bd6905d7c1f3cd361234" format="application/java-archive"><codeph>SetTextVerticalAlignment()</codeph></xref></p></li>
</ul></section>
<section id="GUID-068F5301-03A8-43BF-A274-5359D7073500"><title>Button icon</title><p>If
you use an icon in your button, you can use the same icon for both the pressed
and non-pressed states; however, for the dimmed state another icon is recommended.
For the icon's appearance, follow the <xref href="GUID-EB212C35-5416-4CA7-8091-61B45D78E220.dita">Symbian
look and feel guidelines</xref>. Dimmed icons are generated automatically
if they are not provided by the application.</p><p>To change the scale mode
for the icon image, use the method <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#a941a1e729d7b4da8754e0e3339463ef" format="application/java-archive"><codeph>CAnkButton::SetIconScaleMode()</codeph></xref>. By default, the button
component uses the <codeph>EAspectRatioNotPreserved</codeph> mode, so that
the icon fits the size of the button. To adjust the icon’s alignment on the
button, use the methods <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#6cbee93c541f38be959543f196bb5af3" format="application/java-archive"><codeph>CAknButton::SetIconHorizontalAlignment()</codeph></xref> and <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#800758db92e0a4f11d5c6a1e109f8a57" format="application/java-archive"><codeph>CAknButton::SetIconVerticalAlignment()</codeph></xref>.</p></section>
<section id="GUID-96802265-17DD-486C-B7DA-4B74317D9D72"><title>Button help
text</title><p>If the button provides a help text, it is shown close to the
button if the button is focused or the stylus is held down for some time.
You can set the state-specific help text when constructing the button, at
the construction of a button state, or by calling <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButtonState.html#3aa033c14f22fc44efd11e6177249b75" format="application/java-archive"><codeph>CAknButtonState::SetHelpTextL()</codeph></xref>. To set the help
text for a dimmed button, use the method <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#62e188e1891ea1419ea57c4dd7a03b43" format="application/java-archive"><codeph>CAknButton::SetDimmedHelpTextL()</codeph></xref>. </p><p>To change
time-outs for the help text, use the method <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#8645dabaee65d8f9f36203b44c01d788" format="application/java-archive"><codeph>CAknButton::SetHelpNoteTimeouts()</codeph></xref>.</p><p>To display
and hide the button help text, use the methods <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#2e56627db2398a090d5adaf84c38d87b" format="application/java-archive"><codeph>ShowHelpL()</codeph></xref> and <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#efb2ac6870f957b496494b942d340596" format="application/java-archive"><codeph>HideHelp()</codeph></xref> in the class <codeph>CAknButton</codeph>.</p></section>
<section id="GUID-C36C83B8-C98B-43A5-8CD6-A3E729AC0463"><title>Button background</title><p><codeph>CAknButton</codeph> supports
a background composed of both a <codeph>CCoeControl</codeph> background interface
and an Avkon skin background. If both are set, the <codeph>CCoeControl</codeph>-based
background has higher priority. In case of <codeph>CCoeControl</codeph>-based
background, do the following in order for the button’s background to be drawn
by the container:</p><ul>
<li><p>Set the container class to be derived from the <codeph>MCoeControlBackground</codeph> interface.</p></li>
<li><p>Provide implementation for the <codeph>Draw()</codeph> method in the <codeph>MCoeControlBackground</codeph> interface.</p></li>
<li><p>Call the <codeph>SetBackground( pointerToContainer )</codeph> method
for the button.</p></li>
</ul><p>If the background is set from the skin, use the method <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknButton.html#9853c317f7f3801bd003c9aad7d9c8d6" format="application/java-archive"><codeph>CAknButton::SetBackGroundIds()</codeph></xref>.</p><p>For implementation
examples, see the sample code below:</p><codeblock xml:space="preserve">// Text alignment top-left corner 
CGraphicsContext::TTextAlign horAlignment( CGraphicsContext::ELeft ); 
CAknButton::TAlignment verAlignment( CAknButton::ETop ); 
textButton-&gt;SetTextHorizontalAlignment( horAlignment ); 
textButton-&gt;SetTextVerticalAlignment( verAlignment ); 

// Preserve icon button aspect ratio 
iconButton-&gt;SetIconScaleMode( EAspectRatioPreserved ); 

// Help texts 
HBufC* helpText = StringLoader::LoadLC( R_MYAPP_HELPTEXT );  
HBufC* dimmedHelpText = StringLoader::LoadLC( R_MYAPP_DIM_HELPTEXT ); 
// Set help text to current state 
textButton-&gt;State()-&gt;SetHelpTextL( *helpText ); 
// Set dimmed help text to all states 
textButton-&gt;SetDimmedHelpTextL( *dimmedHelpText ); 
CleanupStack::PopAndDestroy( 2 );  // helpText, dimmedHelpText 
// Help note timeout adjustments 
const TInt KButtonTimeoutBeforeNote = 300; 
const TInt KButtonTimeoutNoteInView = 5000; 
textButton-&gt;SetHelpNoteTimeouts( KButtonTimeoutBeforeNote, KButtonTimeoutNoteInView ); 
</codeblock></section>
</conbody></concept>