Debugger 101

There are a lot of users that don't realize that Real Studio has a debugger- and it's very easy to use!

Let's say that you want to track down a bug in your code and you know that the problem occurs when you push the Show Me button on a window. In your project you would go to the action event of the Show Me button and set a breakpoint next to one of the lines of code as shown below by the red dot (click on the hash mark to set the breakpoint):

Then, to debug the code:

1. Press the Run button

2. Enter any necessary values into the UI

3. Press the Show Me button

You will see debugger pane on the right (this shows the result after pressing the Step button several times):

That's all there is to it. Using the debugger you will have a much easier time locating and fixing problems in your code. For more details on how to use the Real Studio debugger visit "Debugging Your Code" in our Documentation Wiki.

Leveling the playing field

Anyone reading this blog knows that one of the most valuable features of Real Studio is its ability to create cross-platform applications. So it goes without saying that the more level the desktop OS playing field is, the more important cross-platform becomes. As the Mac market share has increased, we get more and more Windows developers coming to Real Studio because their customers want them to support the Mac.

Last week, research firm Gartner released a report on PC shipments for the fourth quarter of 2011. It showed that while all the major Windows PC makers saw a drop in market share, the market share for the Mac increased substantially. And this week, the Wall Street Journal reported that big companies like GE are allowing employees to choose the Mac as the computer they will use at work.

As the market share for the Mac increases, the OS playing field becomes more level and that's great for cross-platform software. It's good news for those of you that create cross-platform, commercial software with Real Studio and it's great for us. In the ideal world, the market share for the three major desktop OSs would be split evenly. But anything that makes it more even is a good thing.

Is it time to redesign?

A huge part of what makes any application intuitive is its interface. If it's well thought out, a user interface can make the difference between an app that is fun and easy to use and one that makes water boarding seem like a nice alternative. If the developer has taken the time to make sure the interface is not only self-consistent but consistent with other applications that provide similar functionality (when appropriate), it can add beauty to an application.

User interfaces don't age like fine wine. If an application's user interface is not updated from time to time, it's going to start making the app look old and out-dated. Additionally, if the application has a lot of features, its developers are likely to have learned quite a bit over the years about how people use the app. It's important to continually advance the usability of an application, this improves the productivity of its users and, in the case of commercial software, keeps the app competitive.

In some cases, incremental improvements can be made to a user interface. But sometimes the entire user interface needs to be redesigned. If you could do it over again, would you create the same user interface you have today? Though it may be a lot of work up front, a much improved user interface should be seriously considered throughout an application's life. Real Studio has gone through several user interface changes since version 1 and we are working on another big one right now.

Let's take a look at how the Real Studio user interface has evolved. Real Studio was first released on July 4, 1998 as REALbasic. The original release of Real Studio back in 1998, looked like this:

REALbasic 1.0

When Mac OS X was released, we updated the user interface to have an appropriate, native look and feel:

REALbasic 5.5 for Mac OS X

And when we brought it to Windows, we took care to make sure the UI felt native:

REALbasic 5.5 for Windows

Over the years we began to recognize that there were areas where we could really improve the user interface. One of the downsides to the original interface was that a user could easily end up with a lot of windows open. At the time, browsers also suffered from this same problem and to solve it the idea of using tabs to separate documents rather than windows was adopted. We also recognized that users spend a lot of their time navigating their projects, so anything to make navigation easier would be helpful. Lastly, we decided we should be eating our own dog food. The IDE was written in C++ and it really should be written in Real Studio itself. So in 2004 we began redesigning the user interface, rewriting in it Realbasic, to solve these and other problems. In mid-2005 we introduced the current Real Studio user interface:

Real Studio 2011

This current interface uses a single window rather than multiple windows. This makes it easier for the user to concentrate on the item they are editing, rather than spending time rearranging and scanning through windows that are layered on top of each other. This concept started on Windows and Linux but has been adopted more and more by Mac OS X applications as well.

The user interface you see above has served Real Studio users well for the past six years. In that time, however, we have learned a lot about how people use and learn to use Real Studio and we have taken note as interfaces have changed in the last six years. As a result, we are applying all of this to a significant redesign of Real Studio's user interface. Our goals are a cleaner user interface, easier navigation, better interactivity, a more intuitive user interface and a more modern look and feel. I'll be more specific about these goals for Real Studio:

• Cleaner user interface - Every piece of text, control, line, and icon you present in a window is something the user believes they have to understand to use the product. Determining which items are infrequently used and removing them (possibly moving them to menus if they still do provide a needed function) can help make the interface cleaner. For example, the current user interface relies too much on text.
• Easier to navigate - Real Studio users spend a lot of time moving from one part of a project to another. While the tabs help, they can also get in the way. The user has to constantly return to the project tab and double-click on a project item which then opens in its own tab. All of these tabs start to take up a lot of room in the tab bar and before long the user is spending time closing tabs to make room for new tabs! Search results only add to this issue because double-clicking on  result opens another tab. And while there's one way to navigate a project, there's a different way to navigate the code for the project. All of these ways of navigating present opportunities for improvement.
• Better interactivity - A project can be filled with many different project items that need to interact with each other. The current user interface does not make this as easy as it could be. For example, to create a custom canvas subclass and use it on a window requires as many as six steps:

1. Click Add Class in the Project Editor.
2. Change the Super property of the new class to Canvas.
3. Write your code.
4. Switch to the Window Editor.
5. Choose Project Controls from the Controls Selector popupmenu above the Controls list in the Window Editor.
6. Drag your custom canvas subclass to the window.

That's a lot of steps. It's also not easy for a new user to figure out these steps. Making basic tasks like this more simple and intuitive helps create better interactivity. And this not only makes it easier for a new user to learn; it makes the experienced user more productive.

• More intuitive - An intuitive interface is one where the user can use the software, for the most part, without consulting the documentation. The key is to think of all the different ways users will try to use the software and anticipate them. The more often a user is successful when attempting a task, the more intuitive the software is. In the current version of Real Studio, there is usually only one way to do a particular task. In the new user interface, we are adding more ways to accomplish tasks to create a more intuitive design for more users.
• Modern look and feel - Modern user interfaces are using higher resolution graphics, shadows, textures, animation and more. We are using many of these elements in the new user interface to modernize the look and feel.

It's been 2 years since we first began designing and implementing a greatly improved user interface to reach these goals. Because Real Studio has many editors, this has been an enormous task but we are very pleased with the results and I'm sure you will be too. 

Some people just don't like change and any significant change to a user interface will result in some of the existing users balking at these changes. There's just no getting around that. Though most of our users really appreciated the changes in the 2005 user interface refresh, there were a small number of users that just hated it. Apple changed the direction of gesture for scrolling in Mac OS X Lion; though it seemed like a huge change at first, it quickly became more intuitive to users. Technology moves fast and user interfaces need to keep pace. People will adjust quickly to well-thought-out changes and designers have to consider what the best user interface will be for the application moving forward. 

iOS Meta Tags

Over the last few months, there have been several requests for the ability to override the tags that are used for determining how a website scales on iOS devices. Before Real Studio 2011r4, you were locked into using our defaults.

Viewport

The default tag looks like this:

<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0">

This says:
1. The page width should be the same as the device width
2. Users are NOT allowed to pinch or zoom the page to change the scale
3. The initial scale is 100%
4. The minimum scale is 100%
5. The maximum scale is 100%

While this works out great for web applications (most of the time anyway), it's not so hot for other uses.

Take our Orders example – the minimum width of the main screen is 1012. Not so much a constraint of the browser, but of the content on the page. When viewed on an iPad in portrait mode, you have to slide the page left and right to access all of the elements. To accommodate this, you can now override this tag with your own by simply adding a replacement in App.HTMLHeader. For the Orders example, the code looks like this:

<meta name="viewport" content="width=1012">

This tag tells the browser that the width of the content is 1012 and not to restrict page scale. In doing so, the page will scale to fit the device. Note: Using this dimension does not work for smaller devices like the iPhone. With a smaller screen, it tries to fit the content into 320px (portrait mode) or 480px (landscape mode), which means the content will be drawn at ¼ or ⅓ of the original size, respectively.

Web App Capable

On iOS devices, when looking at a web page in Safari, you can add the current page to your Home screen where it will get an icon and be available directly with a single touch. Our defaults make it so Safari does not display the URL and Search fields, nor the Safari toolbar across the bottom of the page. The result is that there is a greater amount of vertical space for your application to run.

If you want to turn off this capability, thereby making your application always work more like a website, you can add a line to App.HTMLHeader:

<meta name="apple-mobile-web-app-capable" content="no">

Web App Icons

By default, we compose your application icon for you so that it fits nicely within a white rounded rectangle background. While this is the style that Apple recommends for icons, you have very little control of how big your icon will be. Moreover, as Apple has started offering devices with higher resolution screens, they've suggested different resolutions for different devices.

You can override the default icon by adding a line like this:

<link rel="apple-touch-icon-precomposed" href="touch-icon-iphone.png">

if you want iOS to add the nice "shine" effect to your icon, leave out "precomposed" like this:

<link rel="apple-touch-icon" href="touch-icon-iphone.png">

For more information on the options for configuring Web Applications for iOS, see Apple's Safari Web Content PDF.

Remember: setting these values affects every page that is loaded. If you set the width to 1024, every page will render as if it needs 1024 pixels to appear properly. If your page is only 320 pixels wide it will only take up ⅓ of the device width, regardless of the resolution.

More Video Tutorials Coming Soon

Starting in February we will welcome Paul Lefebvre as our new Developer Evangelist. Among many other tasks, Paul will be giving live tutorials on a number of Real Studio topics each month.

We already have quite a few ideas for these tutorials from your feedback and I'm sure that Paul will arrive with ideas of his own. In addition, we welcome tutorial suggestions from you. If you have a suggestion for a video tutorial, one that would be helpful for you as well as other Real Studio users, please enter a Feature Request into Feedback.

What got you interested in programming?

When I was a kid, I would race home after school to watch M*A*S*H reruns on TV. One of my older brothers watched Star Trek reruns so I would sit through Star Trek waiting for M*A*S*H to start. It didn't take long before I became a Star Trek fan. Star Trek provided me with a view of the future. In that future all things were better. No one was poor, getting around was easy and just about any sickness seemed curable all in a 60 minute episode. Computers were an important element in Star Trek so for me, they became a way to touch the future.


I grew up near the University of California at Irvine. I would ride my bike there and hang out in the computer science lab. I bought punch cards, put them in a punch card machine and typed on them. I had no idea how to write programming code. I just mimicked what I saw others doing. I was probably 13 at the time and why no one chased me out of there still surprises me to this day.


My father spent his career as an electrical engineer mostly creating communications equipment for the military. One day he brought home a Texas Instruments portable terminal. It had no screen, just acoustic couplers that held the telephone handset for communication with the VAX mainframe at his work. A thermal printer was the only output device and of course when we would run out of the special thermal paper, that was a problem. My dad taught me to program in the original BASIC and we played the original text adventure game (called "Adventure") as well.


When the Apple II came along I wanted one but being in high school at the time, I certainly couldn't afford it. My dad was unwilling to pay extra for the Apple brand so instead purchased a Franklin ACE 1000, which was an Apple II Clone. The Franklin's motherboard failed several times, and I'll bet my dad ended up paying far more for it than he would have paid for an Apple II to begin with!  He bought me a book that taught Applesoft BASIC and 6502 assembler. One look at the pages about assembler and I knew right away that I was going to stick with BASIC.


Programming for me became a terrific outlet where I could create anything I could imagine. That's what got me interested in programming.


What got you interested in programming? Share your story.

How to create a Dylib on Mac OS X and create declares in Realbasic to use it.

This tutorial explains how to use Xcode to create a dylib, and then use Realbasic to declare into it. Dylib is short for Dynamic Library, which is a file that contains code that can be linked against at runtime. This means that it isn't built directly into your application, like a static library is, but you can still load it up and call methods in it.


This is mainly useful for C/C++ or Objective-C programmers to create a library that may do something not possible from Realbasic.

Creating the dylib

1. Launch Xcode
   This tutorial assumes that you are using Xcode 3.1.4 from Apple.
2. Choose "File->New Project", or type Command-Shift-N.
3. Select BSD Dynamic Library, and click "Choose".
4. Choose a project name. For this example, we'll call it "SampleDylib".
5. Choose "File->New File..."
6. Choose "C File", from within the "Mac OS" section
7. Name the file. For this example, we'll call it "SampleDylib.c". The default settings are generally correct, but if you have multiple projects open with multiple targets, make sure the proper project and target is selected. When done, click "Finish".
8. Open the SampleDylib.c source file.
9. Add the code below:
   

   #include <string.h>
   
   int addFunction( int a, int b ) {
    return a + b;
   }
   
   int stringLength( char *str ) {
    return strlen(str);
   }

10. Save the file, then click the Build button, or press Command-B.
11. If there were build errors, ensure that the code you entered looks exactly like it does above. Once the build is successful, continue to step 12.
12. Find where the build was saved. If the builds folder location hasn't been changed, it will be located in a "build" folder, next to your project file. It will be named libSampleDylib.dylib. (This is bceuase we've not altered the default install name in the build target.)
    Another way to locate the file is to locate the target by going to the project window, expanding libSampleDylib, then expanding Products. Select libSampleDylib.dylib, and control-click (or right-click, for those with two-button mice), and choose Reveal in Finder
    You will need to access this location later.

Creating the Realbasic project

1. Launch Real Studio. Create a new project, and choose "Desktop"
2. Save the project to your Documents folder (so that it is next to the dylib file). For this example, we'll name it, "Test Dylib.rb"
3. Double click on "App" in the project window.
4. Expand the "Events" section, and select "Open"
5. Add the code below:
   

   CONST dylibLocation = "@executable_path/../Frameworks/libSampleDylib.dylib"
   
   Declare Function addFunction lib dylibLocation (a as integer, b as Integer) as Integer
   Declare Function stringLength lib dylibLocation (s as CString) as Integer
   
   msgBox "5 + 2 = " + str(AddFunction(5,2))
   
   msgBox "The length of ""asdf"" is " + str(stringLength("asdf"))

6. Run your application using the "Run Paused" feature of the IDE.
7. Copy the dylib from the Xcode build into the application bundle. You can do this by right clicking on the debug app & selecting "Show Package Contents".
   Navigate to Contents > Mac OS & copy the dynamic library created by Xcode into the Frameworks directory in the bundle. (If the edition of Real Studio you use supports this you could use a Build Automation Step to do this for you on every compile)
8. Now launch the debug application by double clicking it in the Finder. It should then connect to the debugger in the IDE.
9. Notice that it correctly adds, and also correctly computes the length of the string.

What is it doing?

The loader (aka Dynamic Linker) doesn't search for a dynamic library very well. It relies on either having a full path to the library, or having it relative to the executable path. Since we want the dylib to be installed in the bundle, we use "@executable_path/../Frameworks/libSampleDylib.dylib" as the path for non-debug builds. This means that when you build your application you will need to copy the SampleDylib.dylib file into your Contents/Frameworks directory next to your actual executable file.
However, since the application is regenerated every time Realbasic builds it, the same path won't work for debug builds. (Suggestions about how to deal with this are included later)

What about the native types in Realbasic?


Using Realbasic, you can do almost anything through declares. Here are a few tips on how to handle different types in Realbasic:

• Passing a float into your dylib, or returning a float: In Realbasic, use "Single" as the data type. Singles are the exact same as a float -- a single precision floating point, to be specific.
• Passing a double into your dylib, or returning a double: Doubles are the exact same in both languages.
• Passing a c-string (null-terminated string) into your dylib: In Realbasic, declare the type for the parameter as CString.
• Passing a pascal-string (one byte length specifier) into your dylib: In Realbasic declare the type for the parameter as PString.
• Passing a void* (arbitrary data) into your dylib, or returning it: In Realbasic, declare the type for the parameter as Ptr, and pass in a MemoryBlock. Also declare the return type as Ptr, and it will automatically be converted to a MemoryBlock on return.
• Passing a pointer to a struct into your dylib: The same as above. Set up the memoryblock to contain the different fields, and pass it in as a Ptr.
• Limitation: It isn't currently possible to pass in a struct inline.

Known issues

• By default all symbols (functions & subroutines in C) are exported. This is usually what you want.
  If you happen to preface one with the C keyword "static" then it won't be exported & so it will not be usable directly in Real Studio code like we've shown.
  
• If you name your file with a ".cpp" extension then Xcode assumes that it is a C++ file & names will get mangled by the Xcode compiler. This means they would not be directly usable in Real Studio.
  You will need to preface them with an "extern "C"" declaration to make sure the names get exported unmangled.

Because Real Studio recompiles your application every time you run it under the debugger you can't use the same path for the dylib while debugging as you can in the final build. You can deal with this by using an absolute path to the dylib when debugging. In my case this would be:

CONST dylibLocation = "/Users/npalardy/Documents/libSampleDylib.dylib"

Another way to deal with this is to put the dylib next to the application bundle where Real Studio builds the application (right next to the project file on OS X). Then you can use a relative path like:

CONST dylibLocation = "@executable_path/../../../libSampleDylib.dylib"

And you could make the code in your Real Studio project look like:

#if debugBuild
   CONST dylibLocation = "@executable_path/../../../libSampleDylib.dylib" // next to the app bundle
#else
   CONST dylibLocation = "@executable_path/../Frameworks/libSampleDylib.dylib" // inside the app frameworks in the bundle
#endif

Declare Function addFunction lib dylibLocation (a as integer, b as Integer) as Integer
Declare Function stringLength lib dylibLocation (s as CString) as Integer

Document Updated by:Norman Palardy norman@realsoftware.com

Real Software, Inc.
based on a previous article by Jonathan Johnson
Real Software, Inc.