StudioTips - Object Classes

Object Classes

When I started learning Omnis Studio, I disliked object classes and couldn't see how they were supposed to be better than code classes. Code classes seemed so much easier to create, call, and use. After a year of working without object classes I attended my first Omnis conference and was enlightened by Geir Fjaerli on the beauty of object classes. His words "Anything you can do with a code class, you can do better with an object class" has proved true many times over.

Now object classes are my favorite!

Object Class vs. Code Class

There are several advantages that object classes have over code classes.

Object classes can have their own instance variables. This means you can send a bunch of data to an object class at different times, then later tell the object class to process the data. (Just be sure to hold the object class instance open). This gives you the flexibility of breaking a large process into logical steps, rather than having to prepare everything before hand and then sending a whole slug of parameters to a specific method. Also since the object class can store its own instance variable, onces you've told the object something (like a window instance reference) you don't have to keep sending the parameter to the same object class instance.
Object classes can extend task instances. If you try to create a table class instance inside a code class method, you will discover that inside the table class the task variables have vanished out of scope.
Object classes can have private methods. If you create a code class to handle a complex task and break the code into lots of subroutines you end up with a lot of visible methods when you want to use the code class. It is confusing trying to find the method you are supposed to call vs. the ones that you shouldn't call. If there is more than one developer working on the project, it is really hard to decide. With object classes you can hide all the subroutines by not prefixing them with $. The methods which are to be called from outside are prefixed with $ and will show up in the Interface manager. The result is a class that has a very clear public interface, and is able to hide its subroutines from the public.

Object-oriented code is like a road map. A road map is useful not only for what is shows, but just as much for the detail it doesn't show. Imagine trying to use a road map that not only gave you the roads, but also listed the topographic, demographic, and annual precipitation information ... not a very useful road map. The same goes for object-oriented programming ... you just want to show the information that is needed for using the object, not everything subroutine inside of the object.

Object classes, they're G-R-E-A-T ! ! !

Object Class Interface

Omnis has done a fantastic job on the developer interface for object classes.

When you need to use an object class.

Create a variable of the scope you need.

Object or Object reference.
Set the variable subtype to the object class you wish to use.
Right-click on the variable and select Interface manager from the context menu.
Shazam! Omnis Studio opens the Interface Manager window which lists all the methods in the object class along with the parameters.
Type a Do statement in your code.
Drag and drop a method from the Interface manager ... Omnis Studio puts all the parameters in brackets for you!

If you use good consistent naming conventions for your parameters, it will be very obvious to you (and others) what each parameter means. (See StudioTips - Naming Conventions)

You can use the Interface Manager to drag and drop methods from other types of classes, but you can't create a variable and right click on it, the way you can with object classes. (You can for table classes as of Omnis Studio v4.2)

Object vs. Object Reference Variable Type

Omnis Studio v4.1 introduced the Object reference variable type. This gives you two options for the variable Type:

Object
Object reference

When you use Object as the variable Type, Omnis Studio automatically creates an instance of the object class the first time you send a message to the object. The object instance is bound to the variable and is automatically closed when the variable is closed. If a local variable was used for the object instance, the object instance closes when the method is finished. The trouble with Object type instances is that it is very difficult to pass and store references to them in other instances. What often happens is that you end up with a new instance, rather then a reference to the original instance. To solve this problem Omnis Studio introduce the Object reference variable type.

When you use Object Reference as the variable Type, you must use $newref to create an instance of the object class.

Do $clib.$objects.ObjectClassName.$newref() Returns oObjRef

oObjRef is a pointer to the object instance. The instance is given a life of its own in memory. You can now pass around and make as many copies of oObjRef as you like. Everything points to the original instance of ObjectClassName. Even though oObjRef might be a local variable, the object instance will continue to live on after the method execution is finished. The object instance lives as long as the task which contains it is open. This makes it possible (and easy) to have several windows point to the data in a single object instance. Changing the data in the object instance will be reflected in all the windows which point to that instance. There is a downside to Object Reference object instances... you are responsible to delete the object instance if and when you are done with it. You use the $deleteref method to close the instance.

Do oObjRef.$deleteref()

If you forget to delete the object instances that you no longer need, and keep opening new ones, significant memory and resource leaks will occur.

You can get a list of all Object reference instances using $listrefs.

Do $listrefs() Returns List

You can also check if an Object reference is valid using $validref.

If oObjRef.$validref()

You can copy a Object Reference object instance using $copyref

Calculate oObjRef2 as oObjRef.$copyref()

David Swain has written some excellent Omnis Technical Newsletters on Object Classes and Object vs. Object Reference variable types. www.omnis.net/technews/

Object Classes on-the-fly

You can call an object class method in a single line, without creating an object type variable.

The syntax for doing this is as follows:

Do $libs.LibName.$objects.ClassName.$new().$MethodName(Parameters) Returns Value

This single line of code will instantiate the object, call the method, return the value, and then close the object instance. Omnis Studio evaluates the first part up to (), then calls the method in the object, sending along the parameters if any.

Do and Calculate are equivalent, so the following line of code, though different in format is exactly the same as the previous "Do" statement.

Calculate Value as Do $libs.LibName.$objects.ClassName.$new().$MethodName(Parameters)

If you have an object type variable which has the subtype empty (not pointed to an object) you can set the
subtype using the following syntax:

Do $libs.LibName.$objects.ClassName.$new() Returns oObjectVariable

Once you've set the object type variable's subtype you can use the variable the way you normally would.

Do oObjectVariable.$MethodName(Parameters) Returns Value

You don't have to use objects on-the-fly. I use them in situations where the default object class might be substituted with a different object class. For example I may switch the object class I'm using inside a table class depending on the data base the application is currently connected to, or in a multi-library application I might look for an object class in the $clib and point to it instead of the default object class in a base classes library.

Sharing an Object Instance

If you want to share an object instance with another class instance of any type, use the Object Reference variable Type and instantiate the object instance using $newref.

See the topic Object vs. Object Reference Variable Type

Instead of setting item references to the object instance, you can receive and copy the Object Reference. All the copies of the Object Reference point to the same object instance.

Singleton Design Pattern

A singleton is an object that you want one and only one instance of. For more information on the Singleton Design Pattern see Wikipedia.

If you want a singleton of an Omnis Studio object class the following technique recommended by Bruno Del Sol works quite nicely.

You would add a method to your Startup_Task with a method name like $getSingleton.

The $getSingleton method would have the following code: (except for the DEMO ONLY lines)

; Check for any instances of the object.
If $clib.$objects.oSingleton.$insts.$count=0

   ; No instance was found. Open a $newref instance.
   Do $clib.$objects.oSingleton.$newref() Returns ObjRef

   ; If you need to preset any properties in the singleton, you could do that here.
   Do ObjRef.$initialize(Value1,Value2)

Else

   ; An instance was found. Get the object reference to the instance.
   Calculate Row as $clib.$objects.oSingleton.$listrefs()
   Calculate ObjRef as Row.C1

End If

; Send a $doSomething message to the single instance. (DEMO ONLY)
Do ObjRef.$doSomething() ;; DEMO ONLY

Quit method ObjRef

To use the singleton you would do the following:

; Get a reference to the singleton
Do $ctask.$getSingleton() Returns ObjRef
If ObjRef.$validref

   ; Send a message to the singleton.
   Do ObjRef.$doSomething()

End If

Click the Run Demo button in the StudioTips Browser window. There is a breakpoint in the demo code. You can step through the code.

The first time you run the demo the singleton instance will be opened using $newref. The second time you run the demo, the single instance will be found in the $listrefs and simply returned to you.