Setting button properties not specific to any state

Button frame

If the button has a frame, change its features by setting new frame IDs using the method SetFrameAndCenterIds() in the class CAknButton.

Use the flag KAknButtonStateHasLatchedFrame for a button state to set whether the frame for the button in the state in question should look latched down.

To disable the frame for the button, use the KAknButtonNoFrame flag.

Button text

By default, the button text is truncated to fit the size of the button. Use the KAknButtonSizeFitText flag to make the method MinimumSize() return the size into which the text fits. To change the font, color, and alignment of the text, use the following methods in CAknButton:

• SetTextFont()

• SetTextColorIds()

• SetTextHorizontalAlignment()

• SetTextVerticalAlignment()

Button icon

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 Symbian look and feel guidelines. Dimmed icons are generated automatically if they are not provided by the application.

To change the scale mode for the icon image, use the method CAnkButton::SetIconScaleMode(). By default, the button component uses the EAspectRatioNotPreserved mode, so that the icon fits the size of the button. To adjust the icon’s alignment on the button, use the methods CAknButton::SetIconHorizontalAlignment() and CAknButton::SetIconVerticalAlignment().

Button help text

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 CAknButtonState::SetHelpTextL(). To set the help text for a dimmed button, use the method CAknButton::SetDimmedHelpTextL().

To change time-outs for the help text, use the method CAknButton::SetHelpNoteTimeouts().

To display and hide the button help text, use the methods ShowHelpL() and HideHelp() in the class CAknButton.

Button background

CAknButton supports a background composed of both a CCoeControl background interface and an Avkon skin background. If both are set, the CCoeControl-based background has higher priority. In case of CCoeControl-based background, do the following in order for the button’s background to be drawn by the container:

• Set the container class to be derived from the MCoeControlBackground interface.

• Provide implementation for the Draw() method in the MCoeControlBackground interface.

• Call the SetBackground( pointerToContainer ) method for the button.

If the background is set from the skin, use the method CAknButton::SetBackGroundIds().

For implementation examples, see the sample code below:

// 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 );