iOSLib Structure & conventions - UBogun/Xojo-iosLib GitHub Wiki

Yes, I know, iOSLib tends more and more to overwhelm the curious coder by its size. Until we are able to build Xojo plugins with Xojo, I am afraid it will even grow. Here’s a small legend for first explorations:

iOS classes

Every native iOS class in iOSLib begins with an "Apple" instead of "NS" or "UI". The Core Foundation derivatives of different classes that Apple has not built into classes (you usually handle the pointer only and use it for different framework methods) have been built into classes too with their framework identifier added to the classname. Thus, a NSArray in iOSLib is an AppleArray and a CFArray is an AppleCFArray.

Every such native class has its ID As Ptr which is the ptr to the object itself, very much like the Handle property of Xojo iOS classes. Where a Xojo class is a subclass of a native iOS class, you will usually find methods to convert between both:
toiOSxxx and toApplexxx.

So for example Color.toAppleColor converts a Xojo color to an iOSLib color and AppleColor.toiOSColor does the reversed conversion.

Conversion modules

Where possible (because it is basically a native control and has a Handle), convenience modules contain the conversion and install "virtual" properties on the Xojo controls. You find them in the folder Class Extensions.
No matter what they do, they all have a property
AppleView As (subclass of) AppleView.
Which means all method and property calls in their convenience modules work on this property.

If you want to maximize performance without using custom controls, work on this AppleView property directly with the native iOSLib classes. Keep in mind that while this property may be called AppleView, it is the respective subclass of AppleView always. For a iOSTextfield, AppleView is a UITextField/AppleTetField property.
Please note that this property was named View for some time, and some parts of the documentation may still say so. I had to rename it to AppleView to resolve conflicts with iOSKit.

Custom controls

Where it made sense, custom controls exist which are built on iOSCustomControl subclasses and mostly feature the events of the class too. Plus you can address many of their properties in inspector. Minus they will only appear as a cutomControl rectangle during layout phase.
These controls are almost ever built on the iOLib native class. Exceptions are controls that don’t use special events (or where it’s very doubtful these will ever be needed) where I could just subclass the Xojo control.

You find custom controls in the folder Custom Controls where they follow the naming scheme
iOSLibXojoname, iOSLibAppleName or XojonameiOSLibEnhanced, depending on if a Xojo control of that class exists or if the control is a subclass of the Xojo control.
Therefore, a custom AppleView/UIView class, basically the full implementation of a Xojo iOSCanvas, is called iOSLibCanvas. An AppleLabel control that doesn’t need special events and is therefore a subclass of iOSLabel is called iOSLabeliOSLibEnhanced instead.

The custom controls have, wherever possible, Xojo properties built around them so you can integrate them into you Xojo iOS workflow, the computed properties doing the conversion. Again, if you want maximum performance, they each own an
ID As AppleObject (subclass) that gives you access to the iOSLib implementation behind.
Which means an iOSLibScrollView has an ID As AppleScrollView property.

Event handling

Where an iOSLib class has certain events implemented into its custom ClassPtr, they are usually forwarded to the iOSLib object itself, mostly under the name Apple uses in its documentation and with iOSLib properties if they use any.
When you use those classes as a custom control, the event is forwarded to the wrapper customControl object, mimicking Xojo Event names and reporting with Xojo parameters if any. In that case, the internal iOSLib object’s events do not fire anymore!

Frameworks & status

I have tried to put every control into its respective framework folder. When you read Apple’s documentation, you should be able to check if an implementation exists.
Recently I have started to update the documentation. Where this is finished, you find the class in a finished folder inside its framework folder, together with a note on its implementation and documentation status. The note usually tells you what max. iOS version features are included.

Technical requirements

With Apple’s iOS 9 having widely spread, I see no use in supporting iOS 7 anymore. Where a feature is iOS 9 exclusively, checks are (or rather should be) included that forbid the use of the feature.

The minimum requirement to run iOSLib is currently Xojo 2015r3. I will not use the new CGFFloat data type but I have included method and property descriptions that show up at the bottom of Xojo’s code editor if you use Xojo 2015r4.

Interdependencies

iOSLib has the idea of building an easy-to-use Xojodized image of the iOS API. That sadly makes many classes dependent on others. Frameworks that only use a special purpose can mostly be kicked out of the project, like SpriteKit or Security. If you want to slim down you project, I would recommend to do so starting with one framework and checking the project after each removal. If you are looking for a more modularized implementation, check out Jason King‘s iOSKit.