File: JVE.Utils.pas
Several utilities, mostly used internally throughout the suite, are part of this file. Though they are internal, some of them might be useful, especially when developing for Mac OS X and iOS.
Several major functions are described in the following subsections; in addition to them this unit exposes the functions, listed below. For Mac OS X and iOS:
- ToNSSTR(String):NSString – convert from Delphi string to NSString (added for consistency across Delphi versions).
- FromNSSTR(NSString):String and FromNSSTR(Pointer):String – convert from NSString to Delphi string; the NSString might be wrapped or unwrapped.
- PointerNSSTR(String):Pointer – same as NSSTR, included as part of the Foundation interface, but returning unwrapped NSString (especially useful for Apple collections).
- PointerNSObject(NSObject):Pointer – unwraps the object.
The following functions are only available for iOS:
- GetRootViewController:UIViewController – returns the current root view controller.
- SharedUIApplication:UIApplication – returns the shared UIApplication instance.
Device Unique Identifier
The following function returns an array of identifiers, which are unique for the current machine. On Mac OS X and Windows these are the MAC addresses of all the network adapters. On iOS 6 this is the identifierForVendor; on earlier iOS devices this is a persistent random number (meaning on iOS this value change on reinstall).
- GetDeviceUniqueIds:TArray<String> – usually the first array entry is good enough for most uses.
Implementation Existence Check
This helper allows you to verify whether the platform (Mac OS X or iOS) implements the given class. You can use this, for example, to check whether an iOS 6-only class is present.
- Defined – you can use this function by simply calling it on a given class (i.e. “if TSLComposeViewController.Defined then”).
Apple Dictionary to String List Converter
This helper function converts a Mac OS X and iOS NSDictionary to Delphi’s TStrings object:
- NSDictionaryToStrings(NSDictionary):TStrings
The general layout of the resulting TStrings is constructed to be easily accessible using the Values property. Example output might be:
Name1=Value1 Name2=Value2 Arr#=2 // An array will have a count record with '#' suffix, followed by data Arr[0].Name1=Value3 Arr[0].Name2=Value4 Arr[1]=Value5
Only NSDictionary and NSArray have specific converters, other types within use simple description converter.
Detaching Threads
This helper function works on all platforms and runs the given procedure in a separate thread, automatically managing the lifecycle of the underlying TThread object. On reference-counted platforms this function will host the list of active thread for correct operation.
- procedure DetachThread(TProc<TProc<TThreadProcedure>>);
To use the function, call it as follows:
DetachThread(procedure(Synchronize: TProc<TThreadProcedure>) begin Your_Code_Here; Synchronize(procedure begin Your_Synchronized_Code_Here; end); More_of_Your_Code_Here; end);
Idle Execution
This helper function executes the given procedure in the main thread, but at the next idle time. This procedure returns immediately, without executing the code, but queuing it for idle execution.
- procedure ExecuteInIdle(TProc);
Showing Messages
The following group of procedures provides message boxes, whose invocation does not block the calling thread (on iOS, without an additional message loop). The user choice (if applicable) is provided via a callback, instead of a function result.
In all the functions below, if Title is not provided, a default for the dialog type will be used instead.
The following function presents a regular dialog with an OK button only. It is convenient for simply displaying a message without blocking the app.
- procedure ShowDialog(Msg[; DlgType[; Title]]);
The following function presents a confirmation dialog with OK and Cancel buttons. It calls the Result callback with a Boolean, indicating whether OK was clicked.
- procedure ShowConfirmation(Msg; [Title;] Result: TProc<Boolean>);
The following function is a generic one, allowing opening an arbitrary dialog, similarly to the standard Delphi function, but remaining non-blocking.
- procedure ShowDialog(Msg; DlgType; [Title: string;] Buttons; [DefaultButton: TMsgDlgBtn;] Result: TProc<TModalResult>);
Lang Saver
As an added convenience, for the developers creating multilingual applications, this component suite provides a design-time helper for the TLang Delphi component.
This helper is invoked by right clicking on the component icon in the designer; the following tools are added:
- Save as CSV…
- Load from CSV…
These tools allow you to save the content of the entire TLang component into a CSV file or load it from the CSV file. The file is generated for all languages, stored within the TLang component: each string is output as a line (i.e. Excel row) and each language is created as an additional column, across all values.