Provides the higher-level logic of interacting with the server (in comparison with the TTranslationsSite class) by taking into consideration the state of the current application.
TTranslationsSiteInteraction (TTranslationsSite *TranslationsSite, TLocalTranslations *LocalTranslations);
constructor Create(TranslationsSite: TTranslationsSite; LocalTranslations: TLocalTranslations);
- TranslationsSite: The instance of the TTranslationsSite class.
- LocalTranslations: The instance of the TLocalTranslations class.
Checks whether a translations-related event has occurred, for example, the new version of the translation was uploaded to the server. By the word «event», we call here the classes that derived from the TTranslationsEventFunc base class.
void CheckForEvent (TTranslationsEventFunc EventFunc, const TLanguage &DesiredLanguage, TStopFunc StopFunc, ptrdiff_t CallbackParam);
procedure CheckForEvent(EventFunc: TTranslationsEventFunc; const DesiredLanguage: TLanguage; StopFunc: TStopFunc); overload;
Return value: None.
- EventFunc (TTranslationsEventFunc): Function, which is called once the check has finished. If no other events had occurred, the function is called and the pointer to the dummy class of the type TTranslationsEvent_NoOtherEvents is passed to it. Thus, the pointer passed to the EventFunc can be type cast to one of the following types:
- DesiredLanguage (TLanguage): Language which is the most suitable for the user. Usually this should be the system language. In most cases, it is not recommended to override the default value of this parameter.
- StopFunc (TStopFunc): If this function returns true, the operation will be immediately aborted.
- CallbackParam: Here you may specify any value and it will be passed to the EventFunc and StopFunc functions.
If an event of the type TTranslationsEvent_LanguageSwitchPossible has occurred after calling CheckForEvent, this member function performs the switching to the most suitable language. It asks the users whether they want to switch to the more relevant language and if so, downloads the recommended translation and returns it as a local translation.
bool LanguageSwitch ( const TTranslationsEvent_LanguageSwitchPossible *Event, TLocalTranslation &LocalTranslation, bool AskBeforeDownload, bool *UserChoosedToCancel);
function LanguageSwitch( const Event: TTranslationsEvent_LanguageSwitchPossible; var LocalTranslation: TLocalTranslation; AskBeforeDownload: Boolean; var UserChoosedToCancel: Boolean): Boolean; overload;
Return value: True if the recommended translation has been successfully downloaded.
- Event (TTranslationsEvent_LanguageSwitchPossible): The event class instance returned by CheckForEvent.
- LocalTranslation (TLocalTranslation): If the translation is successfully downloaded (the LanguageSwitch function has returned true), it is returned via this parameter as a local translation.
- AskBeforeDownload: Should the function ask the user whether they want to switch to the recommended language? The message to be shown is obtained from the fields of the TOnSiteTranslation structure associated with the Event, so you do not have to provide it manually. The message consists of the strings of the two languages: English and the language of the translation to be downloaded:
Example 1 (for French):
La traduction française non officielle est disponible. L'utiliser?
The unofficial translation is available to: French. Enable it?
Example 2 (for Russian):
Доступен неофициальный русский перевод. Включить его?
The unofficial translation is available to: Russian. Enable it?"
The download is performed only if the user confirms enabling the translation in the above dialog.
- UserChoosedToCancel: If not zero, the truth that the user has chosen Cancel in the dialog window is passed here.
After the recommended translation was successfully downloaded, it must be applied to the user interface, therefore it becomes active and the ApplyTranslationFunc passed to the TLocalTranslations constructor will be called.
If the currently active translation is unofficial and not built-in, and the quality dialog has not yet been shown for the current translation, this shows the dialog window asking the user whether they want to keep this translation or switch to the default one. Depending on what the user chose, it sends the positive or negative rating of this translation to the server.
If the user chooses «no», the default translation is turned on replacing the currently working one.
bool ActiveTranslationQualityDialog( const TActiveTranslationQualityDialogStrings &Strings, bool *UserChoosedToCancel, TVoidBoolFunction RatingSentFunc, ptrdiff_t CallbackParam);
function ActiveTranslationQualityDialog( const Strings: TActiveTranslationQualityDialogStrings; var UserChoosedToCancel: Boolean; RatingSentFunc: TVoidBoolFunction): Boolean; overload;
Return value: If the user had chosen to stay on the current translation, returns true.
- Strings (TActiveTranslationQualityDialogStrings): The text strings used in the dialog window.
- UserChoosedToCancel: If not null, returns true if the user has pressed Cancel in the dialog window or closed it.
- RatingSentFunc (TVoidBoolFunction): This function will be called when the rating has been sent out to the server. The success (or failure) is passed to the function through the parameter.
- CallbackParam (C++ only): Here you may specify any value and it will be passed to the RatingSentFunc function.
Does not work under the systems prior to Windows Vista and under the Classic theme. In this case returns true.
If no function is passed through the RatingSentFunc parameter, the function will return only after the rating is passed to the site.
Returns true if the translation quality dialog can be shown using the ActiveTranslationQualityDialog function. If the dialog have been already displayed for the current translation, returns false.
bool IsActiveTranslationQualityDialogCanBeShown ();
function IsActiveTranslationQualityDialogCanBeShown: Boolean;
Return value: Boolean value.
If an event of the type TTranslationsEvent_DemandedTranslation has occurred after calling CheckForEvent, this member function shows, if necessary, the dialog window for the potential translator with the offer to participate in translating the program. If the user states that he is interested, opens the site with the additional information.
Simultaneously registers the show of the demanded translation offer on the site. This will increase the on-site counter, so that you will be able to view how often the offer to translate the program into the specific demanded language has been shown.
If the offer has been already shown to the current user and they had pressed Cancel, does nothing when calling this function next time.
void ShowTheDemandedTranslationOfferIfNeeded( const TTranslationsEvent_DemandedTranslation *Event, const UnicodeString &MessageText, const TProxyServerSettings &ProxySettings);
procedure ShowTheDemandedTranslationOfferIfNeeded( const Event: TTranslationsEvent_DemandedTranslation; const MessageText: WideString; const ProxySettings: TProxyServerSettings ); overload;
Return value: None.