1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #include <coeinput.h>

    17 

    18 

    19 //

    20 // TCoeInputCapabilities

    21 //

    22 

    23 EXPORT_C TCoeInputCapabilities::TCoeInputCapabilities()

    24 	{

    25 	}

    26 

    27 /** Constructor which initialises the capabilities. 

    28 

    29 The new object has NULL pointers to the FEP aware text editor and the FEP 

    30 caption retriever objects.

    31 

    32 @param aCapabilities A bitmask of the text input capability flags giving the 

    33 supported capabilities. The possible flags are given in the anonymous 

    34 enumeration in this class, beginning with ENone. */

    35 EXPORT_C TCoeInputCapabilities::TCoeInputCapabilities(TUint aCapabilities)

    36 	:iCapabilities(aCapabilities),

    37 	 iFepAwareTextEditor(NULL),

    38 	 iCaptionRetrieverForFep(NULL),

    39 	 iFepUid(0),

    40 	 iFepSpecificExtensions(NULL),

    41      iObjectProvider(NULL)

    42 	{

    43 	}

    44 

    45 /** Constructor which sets the capabilities, a FEP aware text editor and a 

    46 FEP caption retriever object. 

    47 

    48 @param aCapabilities A bitmask of the text input capability flags giving the 

    49 supported capabilities. The possible flags are given in the anonymous 

    50 enumeration in this class, beginning with ENone.

    51 @param aFepAwareTextEditor A FEP aware text editor. This enables FEPs to 

    52 do things like inline editing, retrieving portions of text, enquiring 

    53 the position of the insertion-point (cursor), etc.

    54 @param aCaptionRetrieverForFep A caption retriever for a FEP. */

    55 EXPORT_C TCoeInputCapabilities::TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep)

    56 	:iCapabilities(aCapabilities),

    57 	 iFepAwareTextEditor(aFepAwareTextEditor),

    58 	 iCaptionRetrieverForFep(aCaptionRetrieverForFep),

    59 	 iFepUid(0),

    60 	 iFepSpecificExtensions(NULL),

    61      iObjectProvider(NULL)

    62 	{

    63 	}

    64 

    65 /** Constructor which sets the capabilities, a FEP aware text editor, a 

    66 FEP caption retriever object, a FEP UID and a FEP specific extensions object.

    67 

    68 This overload is provided to allow an application to report its specialised 

    69 input capabilities, if any, to a FEP. The application should override 

    70 CCoeControl::InputCapabilities() and/or CCoeAppUi::InputCapabilities(), 

    71 to return a TCoeInputCapabilities object created using this overload, passing 

    72 the FEP's UID (as published in its header file) and the address of a 

    73 MCoeFepSpecificExtensions object.

    74 

    75 @param aCapabilities A bitmask of the text input capability flags giving the 

    76 supported capabilities. The possible flags are given in the anonymous 

    77 enumeration in this class, beginning with ENone.

    78 @param aFepAwareTextEditor A FEP aware text editor. This enables FEPs to do 

    79 things like inline editing, retrieving portions of text, enquiring 

    80 the position of the insertion-point (cursor), etc.

    81 @param aCaptionRetrieverForFep A caption retriever for a FEP.

    82 @param aFepUid The UID of the FEP for which the extended capabilities aFepSpecificExtensions 

    83 apply.

    84 @param aFepSpecificExtensions FEP specific extensions supported by the control 

    85 or app UI returning this object.

    86 @see FepSpecificExtensions() */

    87 EXPORT_C TCoeInputCapabilities::TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep, TUid aFepUid, MCoeFepSpecificExtensions* aFepSpecificExtensions)

    88 	:iCapabilities(aCapabilities),

    89 	 iFepAwareTextEditor(aFepAwareTextEditor),

    90 	 iCaptionRetrieverForFep(aCaptionRetrieverForFep),

    91 	 iFepUid(aFepUid.iUid),

    92 	 iFepSpecificExtensions((aFepUid.iUid==0)? NULL: aFepSpecificExtensions),

    93      iObjectProvider(NULL)

    94 	{

    95 	}

    96 

    97 /** Copy constructor. Constructs this object using the capabilities of another 

    98 instance.

    99 

   100 @param aAnother The input capabilities object to be copied. */

   101 EXPORT_C TCoeInputCapabilities::TCoeInputCapabilities(const TCoeInputCapabilities& aAnother)

   102 	:iCapabilities(aAnother.iCapabilities),

   103 	 iFepAwareTextEditor(aAnother.iFepAwareTextEditor),

   104 	 iCaptionRetrieverForFep(aAnother.iCaptionRetrieverForFep),

   105 	 iFepUid(aAnother.iFepUid),

   106 	 iFepSpecificExtensions(aAnother.iFepSpecificExtensions),

   107      iObjectProvider(aAnother.iObjectProvider)

   108 	{

   109 	}

   110 

   111 /** Assignment operator. 

   112 

   113 This copies the capabilities of aAnother into this object.

   114 

   115 @param aAnother The object to be copied

   116 @return This object. */

   117 EXPORT_C TCoeInputCapabilities& TCoeInputCapabilities::operator=(const TCoeInputCapabilities& aAnother)

   118 	{

   119 	iCapabilities=aAnother.iCapabilities;

   120 	iFepAwareTextEditor=aAnother.iFepAwareTextEditor;

   121 	iCaptionRetrieverForFep=aAnother.iCaptionRetrieverForFep;

   122 	iFepUid=aAnother.iFepUid;

   123 	iFepSpecificExtensions=aAnother.iFepSpecificExtensions;

   124     iObjectProvider=aAnother.iObjectProvider;

   125 	return *this;

   126 	}

   127 

   128 /** Equality operator. 

   129 

   130 Compares this and aAnother for equality.

   131 

   132 @param aAnother The object to be compared to this object.

   133 @return ETrue if the objects are equal, otherwise EFalse. */

   134 EXPORT_C TBool TCoeInputCapabilities::operator==(const TCoeInputCapabilities& aAnother) const

   135 	{

   136 	if ((iCapabilities==aAnother.iCapabilities) &&

   137 		(iFepAwareTextEditor==aAnother.iFepAwareTextEditor) &&

   138 		(iCaptionRetrieverForFep==aAnother.iCaptionRetrieverForFep) &&

   139 		(iFepUid==aAnother.iFepUid) &&

   140 		(iFepSpecificExtensions==aAnother.iFepSpecificExtensions) &&

   141         (iObjectProvider==aAnother.iObjectProvider))

   142 		{

   143 		return ETrue;

   144 		}

   145 	return EFalse;

   146 	}

   147 

   148 /** Inequality operator. 

   149 

   150 Compares this and aAnother for inequality.

   151 

   152 @param aAnother The object to be compared to this object.

   153 @return ETrue if aAnother is not equal to this object, otherwise EFalse. */

   154 EXPORT_C TBool TCoeInputCapabilities::operator!=(const TCoeInputCapabilities& aAnother) const

   155 	{

   156 	if ((iCapabilities!=aAnother.iCapabilities) ||

   157 		(iFepAwareTextEditor!=aAnother.iFepAwareTextEditor) ||

   158 		(iCaptionRetrieverForFep!=aAnother.iCaptionRetrieverForFep) ||

   159 		(iFepUid!=aAnother.iFepUid) ||

   160 		(iFepSpecificExtensions!=aAnother.iFepSpecificExtensions) ||

   161         (iObjectProvider!=aAnother.iObjectProvider))

   162 		{

   163 		return ETrue;

   164 		}

   165 	return EFalse;

   166 	}

   167 

   168 /** Merges the capabilities of a specified TCoeInputCapabilities with this object. 

   169 

   170 The capabilities are merged using a logical OR. The pointers to the FEP aware 

   171 text editor, caption retriever and object provider are merged only if this 

   172 object has NULL pointers.

   173 

   174 @param aAnother The capabilities to be merged. */

   175 EXPORT_C void TCoeInputCapabilities::MergeWith(const TCoeInputCapabilities& aAnother)

   176 	{

   177 	iCapabilities|=aAnother.iCapabilities;

   178 	if (iFepAwareTextEditor==NULL)

   179 		{

   180 		iFepAwareTextEditor=aAnother.iFepAwareTextEditor;

   181 		}

   182 	if (iCaptionRetrieverForFep==NULL)

   183 		{

   184 		iCaptionRetrieverForFep=aAnother.iCaptionRetrieverForFep;

   185 		}

   186 	if ((iFepUid==0) && (iFepSpecificExtensions==NULL))

   187 		{

   188 		iFepUid=aAnother.iFepUid;

   189 		iFepSpecificExtensions=aAnother.iFepSpecificExtensions;

   190 		}

   191     if (!iObjectProvider)

   192         {

   193         iObjectProvider=aAnother.iObjectProvider;

   194         }

   195 	}

   196 

   197 /** Sets the input capability flags of this object.

   198 

   199 @param aCapabilities The input capabilities. This is a bitwise-"or" of one 

   200 or more values from the anonymous enum in this class.

   201 @see Capabilities() */

   202 EXPORT_C void TCoeInputCapabilities::SetCapabilities(TUint aCapabilities)

   203 	{

   204 	iCapabilities=aCapabilities;

   205 	}

   206 

   207 /** Gets the input capability flags of this object.

   208 

   209 @return The input capabilities. This is a bitwise OR of one or more values 

   210 from the anonymous enum in this class.

   211 @see SetCapabilities() */

   212 EXPORT_C TUint TCoeInputCapabilities::Capabilities() const

   213 	{

   214 	return iCapabilities;

   215 	}

   216 

   217 /** Tests whether the control supports any type of text input.

   218 

   219 @return ETrue if no text input is supported, otherwise EFalse. */

   220 EXPORT_C TBool TCoeInputCapabilities::IsNone() const

   221 	{

   222 	return iCapabilities==ENone;

   223 	}

   224 

   225 /** Tests whether the control supports entry of positive integers.

   226 

   227 @return ETrue if positive integers are supported, otherwise EFalse. */

   228 EXPORT_C TBool TCoeInputCapabilities::SupportsWesternNumericIntegerPositive() const

   229 	{

   230 	return iCapabilities&EWesternNumericIntegerPositive;

   231 	}

   232 

   233 /** Tests whether the control supports entry of negative integers.

   234 

   235 @return ETrue if negative integers are supported, otherwise EFalse. */

   236 EXPORT_C TBool TCoeInputCapabilities::SupportsWesternNumericIntegerNegative() const

   237 	{

   238 	return iCapabilities&EWesternNumericIntegerNegative;

   239 	}

   240 

   241 /** Tests whether the control supports entry of real numbers.

   242 

   243 @return ETrue if real numbers are supported, otherwise EFalse. */

   244 EXPORT_C TBool TCoeInputCapabilities::SupportsWesternNumericReal() const

   245 	{

   246 	return iCapabilities&EWesternNumericReal;

   247 	}

   248 

   249 /** Tests whether the control supports entry of text in the western alphabets.

   250 

   251 @return ETrue if the western alphabet is supported, otherwise EFalse. */

   252 EXPORT_C TBool TCoeInputCapabilities::SupportsWesternAlphabetic() const

   253 	{

   254 	return iCapabilities&EWesternAlphabetic;

   255 	}

   256 

   257 /** Tests whether the control supports text input in Japanese Hiragana.

   258 

   259 @return ETrue if Japanese Hiragana is supported, otherwise EFalse. */

   260 EXPORT_C TBool TCoeInputCapabilities::SupportsJapaneseHiragana() const

   261 	{

   262 	return iCapabilities&EJapaneseHiragana;

   263 	}

   264 

   265 /** Tests whether the control supports text input in half width Japanese Katakana.

   266 

   267 @return ETrue if half width Japanese Katakana is supported, otherwise EFalse. */

   268 EXPORT_C TBool TCoeInputCapabilities::SupportsJapaneseKatakanaHalfWidth() const

   269 	{

   270 	return iCapabilities&EJapaneseKatakanaHalfWidth;

   271 	}

   272 

   273 /** Tests whether the control supports text input in full width Japanese Katakana.

   274 

   275 @return ETrue if full width Japanese Katakana is supported, otherwise EFalse. */

   276 EXPORT_C TBool TCoeInputCapabilities::SupportsJapaneseKatakanaFullWidth() const

   277 	{

   278 	return iCapabilities&EJapaneseKatakanaFullWidth;

   279 	}

   280 

   281 /** Tests whether the control supports dialable characters as text input.

   282 

   283 @return ETrue if dialable characters are supported, otherwise EFalse. */

   284 EXPORT_C TBool TCoeInputCapabilities::SupportsDialableCharacters() const

   285 	{

   286 	return iCapabilities&EDialableCharacters;

   287 	}

   288 

   289 /** Tests whether the control supports secret text.

   290 

   291 @return ETrue if secret text is supported, otherwise EFalse. */

   292 EXPORT_C TBool TCoeInputCapabilities::SupportsSecretText() const

   293 	{

   294 	return iCapabilities&ESecretText;

   295 	}

   296 

   297 /** Tests whether the control supports auto sentence case.

   298 

   299 @return ETrue if auto sentence case is supported, otherwise EFalse. */

   300 EXPORT_C TBool TCoeInputCapabilities::SupportsAutoSentenceCase() const

   301 	{

   302 	return iCapabilities&EAutoSentenceCase;

   303 	}

   304 

   305 /** Tests whether the control supports non-predictive input.

   306 

   307 @return ETrue if non-predictive input is supported, otherwise EFalse. */

   308 EXPORT_C TBool TCoeInputCapabilities::SupportsNonPredictive() const

   309 	{

   310 	return iCapabilities&ENonPredictive;

   311 	}

   312 

   313 /** Tests whether the control supports all types of text input.

   314 

   315 @return ETrue if all text input is supported, otherwise EFalse. */

   316 EXPORT_C TBool TCoeInputCapabilities::SupportsAllText() const

   317 	{

   318 	return iCapabilities&EAllText;

   319 	}

   320 

   321 /** Tests whether the control supports navigation keys.

   322 

   323 @return ETrue if navigation keys are supported, otherwise EFalse. */

   324 EXPORT_C TBool TCoeInputCapabilities::SupportsNavigation() const

   325 	{

   326 	return iCapabilities&ENavigation;

   327 	}

   328 

   329 /** Gets the FEP aware text editor object pointed to by this object.

   330 

   331 @return The FEP aware text editor object pointed to by this object */

   332 EXPORT_C MCoeFepAwareTextEditor* TCoeInputCapabilities::FepAwareTextEditor() const

   333 	{

   334 	return iFepAwareTextEditor;

   335 	}

   336 

   337 /** Gets the caption retriever pointed to by this object.

   338 

   339 @return The caption retriever pointed to by this object. */

   340 EXPORT_C MCoeCaptionRetrieverForFep* TCoeInputCapabilities::CaptionRetrieverForFep() const

   341 	{

   342 	return iCaptionRetrieverForFep;

   343 	}

   344 

   345 /** Gets the specialised input capabilities of the application.

   346 

   347 This function is called by the FEP and returns the specialised capabilities 

   348 supported by the application. If the application has no specialised input 

   349 capabilities, or if the application does not know about this FEP, the 

   350 function returns NULL.

   351 

   352 Notes:

   353 

   354 The application only knows about one FEP. This is the one that was written to implement 

   355 its specialised capabilities. If aFepUid does not match the UID of this known 

   356 FEP then NULL is returned.

   357 

   358 If an MCoeFepSpecificExtensions is returned, the FEP then calls the supported 

   359 extension functions in the application via its virtual interface. The 

   360 functions return some value, which, depending on the current context, may 

   361 instruct the FEP to perform some actions.

   362 

   363 Background information:

   364 

   365 The specialised capabilities are defined as pure virtual functions in the 

   366 concrete FEP's MCoeFepSpecificExtensions interface, and are implemented 

   367 by the app UI. 

   368 

   369 When the focus in the app UI changes, the FEP queries the application's 

   370 capabilities using CCoeControl::InputCapabilities() and/or CCoeAppUi::InputCapabilities(). 

   371 It then gets the extensions using this function.

   372 

   373 The FEP then calls any member functions of MCoeFepSpecificExtensions that 

   374 it needs to (to inquire about the extended capabilities). The functions return 

   375 a value to the FEP instructing it to perform an action, if that extended functionality 

   376 is appropriate to the current state of the application. 

   377 

   378 @param aFepUid The UID of the current FEP.

   379 @return NULL if there are no FEP specific input capabilities or if the FEP 

   380 is not "known" about by the application. */

   381 EXPORT_C TCoeInputCapabilities::MCoeFepSpecificExtensions* TCoeInputCapabilities::FepSpecificExtensions(TUid aFepUid) const

   382 	{

   383 	if (aFepUid.iUid==(TInt)iFepUid)

   384 		{

   385 		return iFepSpecificExtensions;

   386 		}

   387 	return NULL;

   388 	}

   389 

   390 /** Gets the object provider of the control which supplied this TCoeInputCapabilities 

   391 object.

   392 

   393 This function can be called by a FEP to gain access to the object provider 

   394 tree. For instance, the FEP might need to update an input mode indicator that 

   395 is located in the same object provider tree as the editor with focus.

   396 

   397 @return The object provider. This allows the FEP to access objects in the 

   398 context of the control which supplied this TCoeInputCapabilities object. */

   399 EXPORT_C MObjectProvider* TCoeInputCapabilities::ObjectProvider() const

   400     {

   401     return iObjectProvider;

   402     }

   403 

   404 /** Sets the object provider of the control which supplied this TCoeInputCapabilities 

   405 object.

   406 

   407 This allows the control to give the FEP access to its object provider tree.

   408 

   409 @param aObjectProvider The object provider. */

   410 EXPORT_C void TCoeInputCapabilities::SetObjectProvider(MObjectProvider* aObjectProvider)

   411     {

   412     iObjectProvider=aObjectProvider;

   413     }