Customizing Your App

Ping Buttons

Under the Programmer Menu you will see the menu item Programmer $ping Pushbuttons. By selecting this menu item you toggle the menu checkmark. With this menu item checked a tiny pushbutton (White X in a blue circle) appears in the top left corner of each subwindow.

If you click on the button a ping message tells you information about the subwindow.

If you shift+click on the button you will end up at a breakpoint inside the subwindow. This feature is very helpful when you are debugging and customizing windows.

I use the shift+click on the blue ping button technique for:

1. Looking at ivar values such as: iList, iSQLClassName, iWinInstID
2. Adding a red breakpoint to the $doCmnd class methods so that I can step through the code when I click one of the toolbar buttons.
3. Adding or modifying a window class method.
4. Adding or modifying an $event method of an entry field.

Debug OK Messages

If a developer version of Omnis Studio is being used and an error is logged, the error handler opens a debug OK message. The OK message allows the user to break into the code at the error handler. From there, using the Stack toolbar menu you can go back up the method stack to investigate the method which logged the error, and any previous methods currently in the method stack.

Being able to break into the method stack when an error is logged is extremely useful for solving bugs in your code.

Click the Run Demo button in the StudioTips Browser window to try out the debug OK message.

Programmer Test Method

Each main library has its own mProgrammer menu class which is instantiated by the main menu as a cascading menu by the name Programmer Menu AppName. AppName is replaced with its string table translation.

This method is helpful to you for experimenting and testing code which you write in StudioWorks. If I have a chunk of code that doesn't work and I want to experiment with variations of the code, I'll often go the the Programmer Test Method to try out different things. If I have a batch of records I need to fix in the database, I'll often use the Programmer Test Method to write and run the code.

1. Select the main menu > Programmer Menu AppName > Programmer Test Method
2. This takes you to a Breakpoint command followed by a Quit method command.
3. Below the Quit method you can write any code you like. The code in this method can access any of the task variable object methods so long as you are in the method stack. (i.e. You haven't cleared the method task after coming into the Programmer Test Method.)
4. Enter the following code below the Quit method.
   
   Do stb.$getText('Mn','AppName',#S1) Return FlagOK
5. Assuming you are still in the method stack, double-click on the line of code you just entered.
6. Click the Step In IDE toolbar button. You should have stepped into the $getText method of the oStringTable object class.
7. Click the Step Out button of the IDE toolbar. You should be back to the mProgrammer method.
8. Hover over the #S1 variable in your line of code. The value should be the name of the current app.

Method Calls or Messages?

One of the things that was confusing to me when I got into reading the object-oriented programming books was this thing about sending messages.

In Omnis I was used to the the term method call. If I was explaining code to someone I would say that MethodA does a method call to MethodB even if MethodB was in another class.

Instead of using the words making a method call to another class, the object-oriented programming world uses the word sending a message, which once you get your head adjusted to it, it really is a better word picture of what the code is doing.

So, when we talk to each other about our code (or if we're talking to ourselves), let's talk about class instances sending messages to each other rather than using the term of making method calls.

You can still use the term method call when MethodA and MethodB are in the same class.

So how does this word picture help the developer? Let's use a the real world which all of use can easily relate to.

• In this world there is a class called Human
• Doug is an instance of the class Human.
• Andy is another instance of the class Human.
• The instance Doug sends an $email message to the instance Andy. Doug is the sender. Andy is the target.
• In order for Andy to receive the $email message, Andy needs to have an $email recipient method.
• The $email message may contain parameters: pFrom, pTo, pReplyTo, bBody, which must map correctly to the $email recipient method's parameters.

Do you see how this relates to classes and public methods in Omnis Studio? Let's use a StudioWorks framework example to tell a similar story.

• In StudioWorks there is a class called oStringTable
• The stb startup task variable is an instance of the class oStringTable.
• Programmer Menu is an instance of the class mProgrammer
• The instance Programmer Menu sends a $retText message to the instance stb and includes the parameters ('Mn','AppName') with the message.
• The stb instance receives the $retText message with the enclosed parameters, processes the message, and returns the value, Drivers, to the sender.

Once you get the picture of instances sending messages to each other, a lot of things gain clarity in Omnis Studio.

When a user clicks on a line in a headed list:

• Omnis Studio sends an $event message to the headed list object instance.
  
  In this special case of event handling instead sending parameters to the $event method, Omnis Studio sets the task scope variables pEventCode and pRow so that any instance within the task can access the event parameters.
• If the headed list object has an $event recipient method it can receive and act on the message.
• The $event method of the headed list object instance can then pass the message to the $control method of the window class.
• If the window class has a $control method it can receive the message and process it.

When you open a library, Omnis Studio looks for a task class named Startup_Task. If found Omnis Studio opens an instance of the Startup_Task class and names the instance the same name as the library name. Omnis Studio then sends the task instance a $construct message. If the $construct recipient method exists, the code in the method can open instances of menu classes, toolbar classes, and window classes. All of these instances that are opened are contained within the startup task instance.

Interface Manager

One of the keys to using the StudioWorks framework (and Omnis Studio ) is learning to use the Interface Manager. I wrote code using Omnis Studio for about 2 years without using the Interface Manager. Today, I'd be lost without the Interface Manager.

The Interface Manager shows you the public interface to a class, that is, all the class methods which begin with the $ character.

Well built object-oriented programs have a good clean public interface. You write your code using the public interface. The Omnis Studio IDE works very well with the Interface Manager.

If you aren't familar with the Interface Manager and how to use it to write code, let's go through some exercises.

For these exercises you will be writing code in the Programmer Menu AppName > Programmer Test Method. The instructions below assume that you will write the code below the Quit method in the $event method of the Programmer Test Method menu line of the mProgrammer class method.

Get and set the $:AppName property in the oConstants object class instance.

1. In the method, type the word Do and tab to the Calculation line.
2. In the Variable pane, click the Task tab, and find the task variable cn.
3. Right-click on cn > select .
4. Scroll down the list and find the $:AppName method.
5. Drag the $:AppName method from the into the Calculation field of your Do command.
6. Press tab and enter #S1 in the return field.
   
   
   

   Do not use # hash variables for your real app code.

7. Programmer Menu > Programmer Test Method > double-click your line of code and click the Step Over button in the IDE toolbar.
8. Hover your mouse over the #S1 variable in your line of code. Is the value Drivers or whatever you named your app?
9. Start a new Do command line.
10. Drag the $:AppName.$assign method from the into the Calculation field. Omnis Studio very kindly includes the parameters in parenthesis for us when we drag in the method from the .
11. Replace pAppName with 'Crazy Drivers' including the single quotes.
12. Double-click your line of code and click the Step Over button in the IDE toolbar.
13. Now double-click the first Do command and Step Over that line of code. The value returned to #S1 should now be Crazy Drivers.

Your finished code should look like this:

Do cn.$:AppName() Returns #S1

Do cn.$:AppName.$assign('Crazy Drivers')

Now we'll use the

1. Enter a Do command.
2. Right-click the task variable lsts > select .
3. Drag the $retDefinedList method into the Calculation field of your Do command.
4. Replace the pSQLClassName parameter with 'sCountry' including the single quotes.
5. Remove the other parameters, they are optional.
6. Enter #L1 in the Returns field.
7. Programmer Menu > Programmer Test Method. Double-click your line of code and click the Step Over button in the IDE toolbar.
8. Right-click the #L1 variable > select Variable #L1... This opens the variable window which should display to you an empty list with the column names. Close the variable window.
9. Enter another Do command in the next line.
10. Right-click #L1 in your method code > select .
    
    
    

    The list or row variable

    is only available after the list or row has been bound to a table class while you are stepping through the code. If you were to clear the method stack and right-click on the list variable the menu line does not appear in the context menu.

11. Drag the $:BaseTable method into the Calculation field of your new Do command.
12. Enter #S1 in the Returns field.
13. Double-click your line of code and click the Step Over button in the IDE toolbar.
14. Hover the mouse of the #S1 variable, that value should be Country.
15. Enter another Do command in the next line.
16. Right-click #L1 in your method code > select .
17. Select the $getAllRecords method in the Interface Manager.
18. Click the Description tab in the bottom part of the . Note the method description.
    
    If I've done my job, you should see a short description about what the method does and what it returns. Well written classes with good public methods should be like a black box. You should never need to look inside the box to see what the method does. The Interface Manager tells you the method name, the parameters, the method description, and the return value you can expect.
19. Drag the $getAllRecords method into the Calculation field of your Do command.
20. Enter #F in the Returns field.
    
    
    

    Do not use # hash variables for your real app code.

21. Double-click your line of code and click the Step Over button in the IDE toolbar.
22. Right-click #L1 in your Do command > select Variable #L1...
    
    All going well the variable window will show a list of country records that were fetched from the database.

Your finished code should look like this:

Do lsts.$retDefinedList('sCountry') Returns #L1

Do #L1.$:BaseTable Returns #S1

Do #L1.$getAllRecords() Returns #F

The

.

From the method editor you can look at the Interface Manager of the class you are in using the View IDE toolbar button.

From the F2 Browser you can look at the Interface Manager of any class by right-clicking on the class and selecting

.

Take some time and study the public interface of the Startup_Task task variables. These are the key object classes of the StudioWorks framework. Before you spend time writing a custom method, look at the object classes in the StudioWorks core libraries. There are object classes for exporting and importing data, encrypting and decrypting files, opening the client's web browser to a specific URL, preparing an email in the client's email program, etc. If you are unsure, ask a question on the StudioWorks list. Other StudioWorks members might know where to look. One of the benefits of the StudioWorks community is that we can create reuseable object classes which we can share, because we are using a common framework.

If you know the task variable name and have an idea of the public method name you don't have to use the

.

Try the following:

1. Set your Omnis > Preferences > General tab > $notationhelptimer to 50 milliseconds.
2. In the method editor type Do
3. Press the Tab key to go to the Calculation field.
4. Type the characters err. The task variable errhndler should show up in the notation helper.
5. Press the Tab key and type the characters $pr. The method $promptonceLastError should show up in the notation helper.
6. Press the Tab key.
7. Enter the opening and closing parenthesis () to finish the calculation.

I find the notation helper to be a huge help when writing code in Omnis Studio. It helps you enter method names, variable names, and even functions. You can play with the notation timer speed. I like it around 50 so that I don't have to pause and wait for the helper. You can use the up and down arrow keys or your mouse to select something in the notation helper list. If you don't select an item in the notation helper list the first matching item to what you have typed so far in the Calculation field will be used when you press the Tab key.

Adding a Toolbar Button

To add a toolbar button to the contacts list window:

1. Main Window > Contacts > Shift+click the blue ping button.
2. Find the $:ToolbarCmndsCSV method in the class methods.
3. Right+click the method and select Override Method.
4. Uncomment the method lines.
5. Add ,HelloWorld to the end of the toolbar buttons string being returned by the Quit method.
   
   Quit method 'Edit,New,NewCopy,Delete,SPACER,Find,Print,Export,HelloWorld'
6. Right+Click the class methods > select Insert New Method.
7. Name the new method $HelloWorld and put a breakpoint in the method.
8. Close the IDE window.
9. Close and reopen the main window and select the Contacts node.

The HelloWorld button should appear in the toolbar, but you will notice that the text is not translated, it is not enabled, and does not have an icon. To solve these problems:

1. Add HelloWorld to the sMn_stb schema class in the module. Enter Hello World in the description.
2. Add HelloWorld to the sIcons schema class in the module. Enter 1653 in the description.
3. Programmer Menu > Reload String Tables. (This also rebuilds the icons list)
4. Main Window > Contacts > Shift+click the blue ping button.
5. Find the $_retActiveCmndsList method in the class methods, override the method, and add the following code to the method:
   
   

   Do inherited Returns List
   Do List.$add('HelloWorld')
   Quit method List

6. Close and reopen the main window and select the Contacts node. All going well the button will have the correct text, icon, and be enabled.
7. Click the Hello World icon. All going well you will end up at the breakpoint in the $HelloWorld method.

Removing a Toolbar Button

There are two ways to remove a toolbar button.

1. Override the $:ToolbarCmndsCSV method and remove the button from the CSV string being returned by the method.
2. Send a $removeCmnd message to the window instance.

Writing Methods

How you write your code is up to you. The following are a list of guidelines which I follow when writing code. These guidelines have evolved over the years.

1. Always return something. Either FlagOK (true or false) or a return value.
2. Only exit at the end of the method. (This guideline was added in mid 2005. Code written by me prior to mid 2005 has lots of early exit points.)
3. If a method is returning a value calculate the value to a local variable and return the variable. If an error occurs in the method, set the variable to #NULL. The sender can check the return value with the isnull() function.
4. Preset the return local variable to the negative condition in the init value in the variables pane. FlagOK to kFalse. Return value to #NULL.
5. Always test the return flag or value from a method before proceeding further in the method. Sample code as follows:
   
   

   ; Test FlagOK
   Do List.$getAllRecords() Returns FlagOK
   If FlagOK
      ; Continue
   End If
   Quit method FlagOK

   
   

   ; Test return list. Lists and rows you can not test with isnull()
   Do lsts.$retDefinedList('sContact') Returns List
   If List.$colcount=0
      Calculate FlagOK as kFalse
   Else
      ; Continue
   End If
   Quit method FlagOK

   
   

   ; Test return string
   Do fn.$retCSVStringFromList(List) Returns String
   If isnull(String)
      Calculate FlagOK as kFalse
   Else
      ; Continue
   End If
   Quit method FlagOK

6. The method where an error occurs must immediately log the error to the error handler. Always declare and set both error message variables, Mssg and Dtls, even if you set Dtls to empty.
7. Only public methods of visual classes prompt the user with errors. (windows, toolbars, menus, menu obsever objects classes) Wait till the end of the method before prompting the user.
   
   

   ; Pretend this is a public method of a window class.
   Do lsts.$retDefinedList('sContact') Returns List
   If List.$colcount=0
      Calculate FlagOK as kFalse
   Else
      Do List.$getAllRecords() Returns FlagOK
      If FlagOK
         Do List.$smartlist.$assign(kTrue)
         Do List.$sendall($ref.Active.$assign(kTrue))
         Do List.$doworkBatch() Returns FlagOK
      End If
   End If
   
   ; Wait till the end of the method. Test the flag. Prompt the last error if the flag is false.
   If not(FlagOK)
      Do errhndlr.$promptonceLastError()
   End If

   
   
   You can avoid a lot of $promptonceLastError message calls by structuring your code so that the public methods of your visual classes call lots of private or protected methods which do the real work. The non-public methods only have to worry about returning the flag or value since the public visual class methods are responsible for taking care of the $promptonceLastError.
8. Only public methods of visual classes issue redraws. Following this technique makes it easy for non-public methods and non-visual class methods... they never have to think about redrawing the window, that is the responsibility of the visual class public methods.

In your Omnis Studio Preferences > General tab set the $notationhelpertimer property to 50 milliseconds. The notation helper will come up a lot faster and save you loads of keystrokes and typing errors.

Error Handling

If you want to write code that is easy to maintain you must be diligent about writing good error handling into your code.

1. Anticipate where errors might happen.
2. Log every error to the error handler.
3. Write clearly understandable error message text. (The Mssg and Dtls variables)
   
   
   

   The error handler takes care of reporting the library/class/method which reported the error. You simply need to report additional helpful error message and details information.

4. Check the return flag or value from every method which you call and bail out if the flag or value is communicating an error.
5. End every visual class public methods with an if error test which sends a $promptonceLastError message to the error handler if an error was detected by the visual class public method code.

The StudioWorks error handler has specific log error methods which make it easier for you to log certain types of errors. Study the different $log...Error methods in the oErrorHandler object class to become familiar with them. By using the correct method you can save yourself some time, and your user will get an error message with with the appropriate icon and error message information.

In some cases the error is not a program error. For example the user enters an incorrect password. A non-visual class method can send a $logMinorError message to the error handler and return false to the sender. The visual class method then sends a $promptonceLastError message to the error handler and the user is prompted with a non-threatening error message.

Click the Run Demo button in the StudioTips Browser window to see a demonstration.

Do not use OK message commands in your non-visual class methods. If you ever try to run your StudioWorks app as web server app the OK message commands will halt your application on the web server preventing it from responding to any further requests. Someone will have to go to the server and click the OK message to allow it to continue. Not a good thing.

Overriding a Method

When overriding a superclass method in StudioWorks, to avoid duplication, you should normally first Do inherited and then add your subclass specific method code.

; Run the superclass code
Do inherited Returns FlagOK
If FlagOK
   ; Do the subclass additional code.
End If

Using the 4GL Do inherited command you can get away with not declaring the parameters in the subclass, but if you put a breakpoint on the Do inherited and step up into the superclass method the parameters in the superclass method will be empty. For the superclass code to work while stepping through a Do inherited, the correct parameters must also be declared in the subclass method. If you need any of the parameters in the subclass method, you will need to declare the parameters in the subclass. Sometimes is it easier to copy the entire superclass method, which also copies the parameters to the subclass, and then delete the code from the sublclass method and enter Do inherited at the top of the subclass method. See the steps below for the proper way to copy a superclass method to a subclass.

Running the superclass method isn't always possible. In some cases you will have to copy the superclass method to the subclass and then modify the copied method in the subclass.

Use the following steps to copy a superclass method to the subclass.

1. Select the superclass method from the subclass. The superclass method will be in blue text.
2. Double-click anywhere on the superclass code. This takes you up to the superclass method.
3. Right-click on the superclass method > select Copy. This copies the entire method to the clipboard.
4. Close the superclass methods IDE window.
5. Right-Click on the superclass method in the subclass > select Override Method.
6. Right-Click on the overridden superclass method in the subclass > select Paste. This copies the entire method from the clipboard to the subclass.

Calling a Superclass Private Method

1. You subclass oStartupTaskDefaultMethods to your main library.
2. You want to add to the setDefaultsAndPrefs method, but it is a private method called from the $constructMethod method.