<?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->SetTextHorizontalAlignment( horAlignment ); 

textButton->SetTextVerticalAlignment( verAlignment ); 

// Preserve icon button aspect ratio 

iconButton->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->State()->SetHelpTextL( *helpText ); 

// Set dimmed help text to all states 

textButton->SetDimmedHelpTextL( *dimmedHelpText ); 

CleanupStack::PopAndDestroy( 2 );  // helpText, dimmedHelpText 

// Help note timeout adjustments 

const TInt KButtonTimeoutBeforeNote = 300; 

const TInt KButtonTimeoutNoteInView = 5000; 

textButton->SetHelpNoteTimeouts( KButtonTimeoutBeforeNote, KButtonTimeoutNoteInView ); 

</codeblock></section>