diff -r 7165f928e888 -r 31c16e0c5e3e classicui_plat/popups_api/inc/AknPopupField.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/classicui_plat/popups_api/inc/AknPopupField.h Wed Aug 18 10:02:14 2010 +0300 @@ -0,0 +1,677 @@ +/* +* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "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: +* +* Description: +* Represents a combo box type control, used to implement the Series 60 +* pop-up field. +* +* +*/ + + +#ifndef AKNPOPUPFIELD_H +#define AKNPOPUPFIELD_H + +#include +#include +#include +#include +#include + +#include +#include +#include + +class TResourceReader; +class CEikLabel; +class CEikCommandButton; +class CAknFormGraphicStyleListBox; +class MAknQueryValue; + +class CAknPopupField; +class CAknPopupFieldExtension; + +/** + * this interface should be implemented by classes that need to know + * about events occurring in the popup field control + */ +class MAknPopupFieldObserver + { +public: + enum TAknPopupFieldEvent + { + EAknPopupFieldEventModeChange, + EAknPopupFieldEventValueChange + }; +public: + /** + * Handles events from the popup field control, such as changes between + * selection list mode and label mode. + * + * @param aPopupField pointer to the popup field control that generated + * the event. + * @param aEventType the type of event. + * @param aHint for possible future use. + */ + virtual void HandlePopupFieldEventL(CAknPopupField* aPopupField, + TAknPopupFieldEvent aEventType, + TInt aHint)=0; + }; + +/** + * Represents a combo box type control, used to implement the Series 60 + * pop-up field. + */ +class CAknPopupField : + public CEikBorderedControl, + public MCoeControlObserver, + public MEikCommandObserver, + public MEikListBoxObserver + { +protected: + /** + * Specialises bitmap button to make the layout correct for popup field + */ + class CAknPopupFieldBitmapButton : public CEikBitmapButton + { + public: + /** + * Constructor + */ + CAknPopupFieldBitmapButton(); + }; +public: + /** + * Selection mode of the popup field. + */ + enum EAknPopupFieldSelectionMode + { + /** + * Label mode. In Label mode popup field is minimized and popup field + * looks identical to a list item. When it receives the selection key + * press it is changed to @c EAknPopupFieldSelectionListMode and the + * pre-defined list is displayed. + */ + EAknPopupFieldLabelMode, + + /** + * Selection list mode. In this selection mode pre-defined popup + * selection list is displayed. + */ + EAknPopupFieldSelectionListMode + }; + + /** + * Form mode for the popup field. + */ + enum EAknFormMode + { + /** View mode. */ + EAknFormModeView, + + /** Editable mode. */ + EAknFormModeEdit, + + /** View mode with graphic. */ + EAknFormModeViewWideWithGraphic, + + /** View mode without graphic. */ + EAknFormModeViewWideWithoutGraphic, + + /** Edit mode with graphic. */ + EAknFormModeEditWideWithGraphic, + + /** Edit mode without graphic. */ + EAknFormModeEditWideWithoutGraphic + }; +public: + EAknPopupFieldSelectionMode SelectionMode() const { return iSelectionMode; } + EAknFormMode FormMode() const { return iFormMode; } + /** + * C++ default constructor. + */ + IMPORT_C CAknPopupField(); + + /** + * Destructor + */ + IMPORT_C ~CAknPopupField(); + + /** + * Handles 2nd phase construction. + */ + IMPORT_C void ConstructL(); + + /** + * Sets a flag that enables user defined entry. Note that flag can also be + * set from resources, but this method allows behaviour to be changed at + * runtime. + * + * @param aAllows if @c ETrue sets a flag. + */ + IMPORT_C void SetAllowsUserDefinedEntry(TBool aAllows); + + /** + * Causes a list of pre-defined values to appear. + * Use this method to activate the pop-up field from a menu option command. + * Note that the desired control must be focused on before it can be + * activated. + */ + IMPORT_C void ActivateSelectionListL(); + + /** + * Used by the client to set the query value. It is used to represent the + * user defined query value in this popup field control. + * + * @param aValue Pointer to query value, ownership is not passed. + */ + IMPORT_C void SetQueryValueL(MAknQueryValue* aValue); + + /** + * Sets the font of the contained label. + * + * @param aFont Font definition used to set the font of the contained + * label. + */ + IMPORT_C void SetFont(const CFont* aFont); + + /** + * Sets a flag that determines whether the indicators are shown. + * In practice the indicators have the appearance of radio buttons. + * + * @param aShowIndicators If @c ETrue, indicators are displayed. + */ + IMPORT_C void SetShowIndicatorsL(TBool aShowIndicators); + + /** + * Number of lines used. + * + * @return Number of entries on the selection list. If selection list + * is not active, 1 is returned. + * NOTE that the number is limited by @c KAknMaxEditorLines. + */ + IMPORT_C TInt NumLines() const; + + /** + * Sets an observer of this class to receive events from popup field. + * + * @param aObserver Pointer to the class that implements the observer + * interface. + */ + IMPORT_C void SetPopupFieldObserver(MAknPopupFieldObserver* aObserver); + + /** + * Sets the note to be displayed when the selection list has no items + * available. + * + * @param aResourceId Resource id for the note. + * @param aTimeout = CAknNoteDialog::EShortTimeout Timeout for the note. + * @param aTone = CAknNoteDialog::ENoTone Tone for the note. + */ + IMPORT_C void SetEmptyListNoteL(TInt aResourceId, + CAknNoteDialog::TTimeout aTimeout = CAknNoteDialog::EShortTimeout, + CAknNoteDialog::TTone aTone = CAknNoteDialog::ENoTone); + + /** + * Sets the empty list note text. This note is displayed when the + * selection list has no items available. + * + * @param aEmptyText The empty list note text. + */ + IMPORT_C void SetEmptyTextL(const TDesC& aEmptyText); + + /** + * Sets the text to be added to the bottom of the array to enter user + * defined data. + * + * @param aOtherText Text to the bottom of the selection array. + */ + IMPORT_C void SetOtherTextL(const TDesC& aOtherText); + + /** + * Sets the text for view state when none of the elements in the + * list are available. + * + * @param aInvalidText The invalid text. + */ + IMPORT_C void SetInvalidTextL(const TDesC &aInvalidText); + + +public: // from CCoeControl + + /** + * From @c CCoeControl. + * + * Handles key events. + * + * @param aKeyEvent The key event. + * @param aType The type of key event. + * @return Indicates whether or not the key event was used by this control. + */ + IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType); + + /** + * From @c CCoeControl. + * + * Constructs the control from a resource file. + * + * @param aReader The resource reader pointing to the popup field resource. + */ + IMPORT_C void ConstructFromResourceL(TResourceReader& aReader); + + /** + * From @c CCoeControl. + * + * Determines the minimum size of the control. + * + * @return The minimum size required by the control. + */ + IMPORT_C TSize MinimumSize(); + + /** + * From @c CCoeControl. + * + * Handles a change to the control's resources. + * + * @param aType The type of the resource change. + */ + IMPORT_C void HandleResourceChange(TInt aType); + + /** + * From @c CCoeControl. + * + * Handles pointer events of popup field list. + * + * @param aPointerEvent The pointer event to be handled. + */ + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent); +public: + /** + /** + * Sets the maximium number of lines that can be displayed. + * + * @param aMaxNoLines The maximum number of lines. + */ + IMPORT_C void SetMaxNumberOfLinesPermitted(TInt aMaxNoLines); +public: + + /** + * Sets a form field rectangle so that a popup field can correctly position + * the label. + * + * @param aFormFieldRect The form field rectangle. + */ + IMPORT_C void SetFormFieldRect(TRect aFormFieldRect); + +protected: // from MCoeControlObserver + + /** + * From @c MCoeControlObserver. + * + * Handles an event from an observed control. + * + * @param aControl The control that sent the event. + * @param aEvent The event type. + */ + IMPORT_C void HandleControlEventL(CCoeControl* aControl,TCoeEvent aEvent); +protected: // from MEikCommandObserver + + /** + * From @c MEikCommandObserver. + * + * Processes events from the softkeys. Responds to @c EAknSoftkeyOk and + * @c EAknSoftkeyCancel to accept or cancel the pop-up. + * + * @param aCommandId Event Id from the soft-key. + */ + IMPORT_C void ProcessCommandL(TInt aCommandId); +protected: // From MEikListBoxObserver + + /** + * From @c MEikListBoxObserver. + * + * Processes key events from the listbox. Responds to + * @c EEventEnterKeyPressed to accept the pop-up. + * + * @param aListBox Listbox being observed. + * @param aEventType Event observed. + */ + IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, + TListBoxEvent aEventType); +protected: // from CCoeControl + + /** + * From @c CCoeControl. + * + * Gets the number of controls contained in a compound control. + * + * @return The number of component controls contained by this control. + */ + IMPORT_C TInt CountComponentControls() const; + + /** + * From @c CCoeControl. + * + * Gets an indexed component of a compound control. + * + * @param aIndex Control index. + * @return The component control with an index of @c aIndex. + */ + IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const; + + /** + * From @c CCoeControl. + * + * Responds to changes to the size and position of the contents of this + * control. + */ + IMPORT_C void SizeChanged(); + + /** + * From @c CCoeControl. + * + * Responds to a change in focus. + * + * @param aDrawNow Contains the value that was passed to it by + * @c SetFocus(). + */ + IMPORT_C void FocusChanged( TDrawNow aDrawNow ); + + /** + * From @c CEikBorderedControl. + * + * Called by the framework to draw the control. + * + * @param aRect Rectangle in which the Cone framework believes drawing is + * needed. + */ + IMPORT_C void Draw(const TRect& aRect) const; + +private: // from CCoeControl + IMPORT_C void Reserved_1(); + IMPORT_C void Reserved_2(); + +private: + /** + * From CAknControl + */ + IMPORT_C void* ExtensionInterface( TUid aInterface ); + +protected: // personal + + /** + * Construction tasks common to both a normal construction and a construction + * from a resource. Used from @c ConstructL() and + * @c ConstructFromResourceL(). + */ + void CommonConstructL(); +protected: // from MObjectProvider + + /** + * From @c CCoeControl. + * + * Retrieves an object of the same type as that encapsulated in @c aId. + * + * @param aId An encapsulated object type ID. + * @return Encapsulates the pointer to the object provided. + * Note that the encapsulated pointer may be NULL. + */ + IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId); +private: // personal + + /** + * Create the label that will show the currently selected value. + * + */ + void ConstructLabelL(); + + /** + * Create the command button that will be used to show the other choices indicator. + * + */ + void ConstructCommandButtonL(); + + /** + * Create the selection list box that will fill the expanded popup field + * + */ + void ConstructSelectionListL(); + + /** + * setup the scroll bar within the selection list box + * + */ + void SetUpScrollBarL(); + + /** + * set the scroll bar selection + * + */ + void SetScrollBarSelectionL(); + + /** + * Set up the bitmap array for the "not pushed" and "pushed in" states + * + */ + void InitialiseRadioButtonBitmapsL(); + + /** + * Handles the case where the selection list is closed. If necessary, + * update the value of the text label that is displayed. + * + * @return TBool ETrue always + */ + TBool HandleInteractionConfirmedL(); + + /** + * Create the popup list. Warn the user if there are no entries in the list. + * + */ + void CreatePopoutL(); + + /** + * Destroy the popup list and remove it from the stack + * + */ + void DestroyPopout(); + + /** + * Checks to see if the popupfield is empty + * + */ + TBool IsEmpty() const; + /** + * Checks to see if the popupfield is invalid + * + */ + TBool IsInvalid() const; + /** + * Handles a horizontal key event + * + * @return TKeyResponse returns either EKeyWasConsumed + * or EKeyWasNotConsumed + */ + TKeyResponse HandleHorizontalKeyEventL(TUint aKeyEventCode); +private: // Avkon + + /** + * Creates the CBA for use when the selection list is active + */ + void CreateCbaL(); + + /** + * Configures the decoration according to the currently set flags. + * Should be called whenever the flags are changed. + * + */ + void ConfigureDecorator(); + + /** + * Configures the layout decoration according to the radio button flag + * Should be called whenever the flags are changed. + * + */ + void ConstructLayoutDecoratorL(); + + /** + * display a note when the selection list has no items available + * + */ + void ShowEmptyListNoteL(); + + /** + * Re-defined method of the base class. Gets called when the + * user tries to select a value. If required, an editor is created to + * allow the user to input the user defined value. Otherwise, the + * normal selection behaviour of popup list is activated. + * + * @param aAccept If ETrue, popup list was accepted; + * if EFalse, popup list was cancelled + * + */ + void AttemptExitL(TBool aAccept); + + /** + * Changes the mode of the popupfield to one of + * the EAknPopupFieldSelectionMode's + */ + void ChangeMode(EAknPopupFieldSelectionMode aNewMode); + +private: // async + static TInt AttemptExitCallbackL(TAny* aThis); + void DoAttemptExitL(); + void DoSizeChangedL(); +protected: + // the following members are owned + /** + * Label of the popup field. + * Own. + */ + CEikLabel* iLabel; + + /** + * Bitmap button for the popup field. + * Own. + */ + CAknPopupFieldBitmapButton* iButton; + + /** + * List box for the popup field usage. + * Own. + */ + CAknFormGraphicStyleListBox* iSelectionList; + + /** + * Contains a popup field selection array and a leading text that will be + * inserted before the text from the descriptor array entry. + * Own. + */ + CAknListBoxLayoutDecorator* iLayoutDecorator; + + /** + * Button group container for the popup field. + * Own. + */ + CEikButtonGroupContainer* iCba; + + /** + * Active object for calling @c AttemptExitCallbackL asynchronously. + * Own. + */ + CAsyncCallBack* iAttemptExitAsync; + + // the following fields are reflected in the POPUP_FIELD resource structure + /** + * Flags for the popup field. + */ + TInt iFlags; + + /** + * Maximum line width. + */ + TInt iWidth; + + /** + * Text to the bottom of the selection array. + * Own. + */ + HBufC* iOtherText; + + /** + * The empty list note text. + * Own. + */ + HBufC* iEmptyText; + + /** + * The invalid text. Used in the view state when none of the elements in the + * list are available. + * Own. + */ + HBufC* iInvalidText; + + /** + * Resource id for the empty note. + */ + TInt iEmptyNoteResourceId; + + // the following members are not owned + /** + * Query value for the popup field. + * Not own. + */ + MAknQueryValue* iValue; + + /** + * Observer for receiving events from the popup field. + * Not own. + */ + MAknPopupFieldObserver* iObserver; + + // the following values are member variables + /** + * Enumeration representing form mode values. + */ + EAknFormMode iFormMode; + + /** + * Timeout for the empty tone. + */ + CAknNoteDialog::TTimeout iEmptyNoteTimeout; + + /** + * Tone for the empty note. + */ + CAknNoteDialog::TTone iEmptyNoteTone; + + /** + * Selection array for the popup field. + */ + TAknDesCArrayDecorator iDecorator; + + /** + * Enumeration representing selection mode values. + */ + EAknPopupFieldSelectionMode iSelectionMode; + + /** + * Maximum number of items in selection array. + */ + TInt iMaxNoLines; + // NOTE: use Extension() to extend this class. +private: + CAknPopupFieldExtension* iExtension; + TInt iSpare[3]; + }; + +#endif // AKNPOPUPFIELD_H