ScreenIO Listview Screen

The Development of the ScreenIO Library was a major step forward for the BR community as a whole. Not only has it completely revolutionized the thinking about what's possible to accomplish in BR, but on the way we learned many useful shortcuts, coding secrets, and new techniques, many of which require no special tools at all, or can be accomplished using only tools Sage makes available for free.

This tutorial will explain in detail how to use ScreenIO to create your first Listview Screen, and on the way, to demonstrate a few of these tricks and techniques. More detailed explanations of all of these topics can be found in the ScreenIO documentation.

During the BR group conference, I will go into more detail about many of the programming techniques that make all this possible. However, if you miss the presentation for some reason, I'd still like to give you a chance to check out ScreenIO and what it can do. So this guide is going to focus more on a straightforward example of how to create and use a ScreenIO screen.

For now, Sage AX has decided to provide a six month unlimited trial to potential users. This way you can follow along with the example and get a feel for using the ScreenIO designer to create programs.

Additionally, it should be possible to create and use these two screens in your own application, by tying them to your own data files and customizing them however you want. You're free to do so if you like. I'm confident that once you use ScreenIO, even just getting a taste of it creating your first two screens, you'll never want to write programs the old way again.

Creating a new screenio Screen

The first thing to do when creating a new Screenio screen is make sure the data files you want to work with are defined in Fileio file layouts. ScreenIO uses Fileio to simplify a lot of the programming process. We created our file layout during the Fileio Tutorial earlier, so if you missed that presentation, you may wish to take a look at it now. If not, you can skip ahead and just use the already created file layout in your Screenio sample programs folder.

You can download the sample environment for this tutorial here:

First, launch BR and fire up ScreenIO by typing "LOAD SCREENIO" and "RUN". You should be presented with a view of the main Screenio designer.

The ScreenIO Designer is broken up into several separate windows. This program was meant, among other things, to prove its possible to write a modern program interface entirely in BR. Along the left are various tools you'll use to create your new screen. At the bottom is the "Todo List", which contains suggestions for things that the ScreenIO designer thinks may be problems. If you see something listed in RED, then it is an error and your screen will not run until its corrected. If its listed in BLUE then its a warning, and you may or may not need to fix it.

In the top right corner, forming the majority of the screen, is the Editor window. Here is where you will watch your new screen begin to take shape.

To start with, lets take a look at the Window Attributes section of the Toolbar Window. It appears in the upper left corner and contains global information about your current screen. From here it is easy to change the screen size, color, screen name, rearrange your fields, select your file layout and do much much more.

First, we're going to select a file layout for our new screen. Click the button to the right of the words "File Layout:" in the Window Attributes section of the Toolbar. A selection window appears where you can select any of your file layouts. You should see the two Screenio file layouts, and the customer file we created before.

Select the Customer file layout and press ok.

You should now notice that the fields list listview on the left side of the screen has populated with the fields in your customer data file. This is a good way to be sure that the file layout loaded properly.

Lets take a look at another section of the screen now. The debug window, which used to have two comments, now has only one message for us. The other message, Select a File Layout, has already been done.

It looks like at this time the Debug Window is telling us we need to give a name to our new screen.

Click on the Window Name field and type a name for our new screen: "CUSTOMER".

Next, click on the button next to where it says "BG Color" to choose a more modern looking Business Blue for the new screen we're creating.

Click the button for the color you want. Choose the light blue on the first row, the one with the "*" in the screeenshot. Alternately, you can type the HTML color code in manually. If you do, the color we're using is "6699FF" Simply type it into the color picker and click the "Select Color" button.

The next thing to change is the screen size. Because monitors have consistently increased in size, BR programs generally have a much larger font than other programs do. Many of our customers like the large fonts, but it is still important to note that font size is a pretty important factor when it comes to designing modern Windows-looking programs. It is at least worth considering our options, and ScreenIO makes this easy.

Go to the Window Attributes section of the ScreenIO designer and type in 27 Rows and 90 Columns. This will make our program slightly bigger, just enough to make it not quite look necessarily like a BR program, and enough to show a little more information on the larger screens that have become commonplace.

You'll notice as you change the size of your screen, the change is effected in real time (as soon as you press ENTER anyway) and the whole ScreenIO designer automatically resizes to show more information where it can, and to show your BR window size.

At this point your ScreenIO window should look like the following screenshot.

By now, we have accomplished nearly all of the preliminary design work for the screen itself. Its time to start adding some controls to it.

This is going to be a Listview Screen, so start by adding a listview, using the button in the bottom left "Toolbox" window.

A new listview will appear in your screen, and after a second or so, your screen will fill with a black grid that we will use to quickly position the listview wherever we want.

The heading of the New Listview is yellow, indicating that it is the currently selected control.

At this time you can move it around the screen by clicking on any of the black squares in the grid, or by using the arrow keys. Clicking the black squares in the grid will position the top-left corner of the Listview. You can control the movement with the keyboard as well. The arrows will move your listview around. Space and Backspace will make it wider or narrower. And PgDn/PgUp will make it taller or shorter.

Position the listview so that it looks good. Use the following screenshot as a guide.

The ScreenIO Designer has many different modes you can use to edit your controls. Whenever you are in Control Movement Mode, you see the black grid, and one of your controls in in Yellow. You can press the "Enter" key to cycle through the various editing options for your new control. Most controls have two modes: A Movement mode for moving them around, and an Object Attributes mode for entering the attributes for the new control. You can reach Object Attributes mode by clicking on a control twice, or until the Object Attributes Window opens up. You can also select the control and press Enter to cycle through the controls various modes until you see the Object Attributes Window.

Listview Controls have three modes. In addition to Object Attributes mode and Movement mode, they also have a special mode for editing the listview columns. Press enter now to cycle through the various modes for this listview until you get to Listview Column Editing mode. You'll know you're there because the listview will be replaced with a grid inside which you can enter the attributes for the columns for the listview.

In Listview Column Editing mode you can see our new listview is made up of one default column called the "Empty Listview" column. At the left of the grid is a window describing what each row in the grid means. The grid has one column for each column in the listview and it has rows in each column for specifying all the necessary data to build your listview with.

Underneath the Row Caption window, you'll notice two buttons for "Delete Column" and "Add Column". Click the "Delete Column" button to get rid of our "Empty Listview" column. Next, click on the "Fields List" listview at the left hand corner of the screen. The Fields List listview will turn yellow, indicating that the cursor is in this listview now.

At this point you can add fields to the listview by scrolling through that list and pressing "Enter" on the fields you want to add. Select the "Name" field now and press enter. You'll see a new column appear in the listview.

Because the field is defined in your file layout, ScreenIO is able to figure out most of the information you need for each column. You only have to make adjustments in places where you don't like the default value that ScreenIO comes up with.

Now that you've added the "Name" column to your listview, its time to add the other columns. While the Fields List is still active, scroll through the other fields in the data file and add them: City, Zip and Phone number. Its not necessary to add the Customer Code field since in our example this is an automatically generated field hidden from the user.

You'll notice that all the columns extend off the right of the listview and there is a horizontal scroll bar. At this time change the "Width" for the Customer Name field to 15 to allow room for the extra columns and begin adjusting the sizes of things to make them look good.

After you've made this change, press enter a few times to cycle through the various modes and allow the Listview a chance to redisplay. In movement mode you'll notice you can already see the data from the data file.

ScreenIO always attempts to display listviews with at least the first page of data in them, if there is data available in the file. This can help to ensure the columns are adjusted to the correct width to fit the widest data that is likely to appear in them.

Keep pressing enter until you cycle back through to Listview Column Editing Mode.

At this time let's set the widths of all the other fields. Keep looking back through the various modes to see your changes and ensure that everything lines up well. Or just look at the following screenshot to see the values that I found looked best when creating this demonstration.

While we're in here, lets go ahead and set a background color for the listview. I chose a slightly lighter blue then the rest of the screen, in order to give the listview a slightly sunken 3D appearance. Enter "000000" (black) for the Foreground Color and "80A7FF" for the Background Color for each column.

Finally, it may be nice to center the zipcode and phone number, since they're all the same size, to make the data look nicer in the column. You can do that by placing a "C" in the Justify spec.

Go ahead and enter all the parameters you see in the screen shot above.

When you're done, press ESC to get out of Listview Attributes Mode. You can press the ESC key at any time in ScreenIO to back out of any special editing mode and go back to Window Attributes mode. Do so now and let's take a look at the listview. By now your editor window should look like the following screenshot.

Our screen is looking good, but its missing something. In order to be a File Maintenance Program we'll need to add a button for Editing a customer and a button for Adding a new customer. It would also look nice if we had a title for our screen. Use the toolbox in the bottom left corner to add two buttons and a Caption now.

The fields position themselves on the screen but they're not in the positions we want them in, and they don't have any data specified. They are simply new, blank, empty fields. Use Control Movement mode to position them like in the following screenshot.

Now it is time to enter the properties for your new fields. One at a time select them and go to the Control Properties window. We'll start with the two buttons.

In the first button, enter the following information:

• Caption: "Add"
• Function: "[CUSTEDIT]"

The Function parameter indicates what happens when the user clicks on the Function button. You can place custom code in this button, or select a library function to run, or call another screen. You can also type BR code directly into the function parameter for your button, which is usually the easiest way to configure the screen's exit mode, as we'll see in a moment.

In this button we want to call the "CUSTEDIT" screen which we're going to make in just a few minutes. We don't need to pass any information into the screen for Adding a new customer because the default action for an Add/Edit screen is to add a new record.

To make one of your events call another screen, simply type the name of the screen in square brackets. When the user clicks on the Add button, we want to jump to the "Add/Edit" screen. Once the user is done adding the customer, they'll be taken back here to continue what they were doing.

Go ahead and type in the information for the Add button now.

The Edit Button should have the following information entered:

• Caption: "Edit"
• Function: "[CUSTEDIT]key$=CurrentKey$"

If you DO need to pass any information into your screen, you can do so with a BR command placed after the screen name. In this example we're setting the key$ for the new screen, which tells what record we want to edit. In ScreenIO you have access to a bunch of system variables that tell you the state of the program at any time. One of these is called "CurrentKey$", and it always tells the key of the currently selected record in a listview.

For the caption, we simply want to center it and enter the text to display:

• Caption: "Customer List"
• Justification Spec: "CC"

At this point, press ESC again to look at your entire screen. It's really starting to come together now, and we haven't even had to write any custom code yet. We'll get to some simple code customizations later, but its important to point out that you can make a ScreenIO screen do nearly anything by entering the right custom code.

Now that we have this stellar listview, lets spruce it up a bit. Its easy to add a search box to a screenio listview. Simply Click the Add Searchbox button in the bottom left corner of the toolbox. It will find the listview on the screen if there is one and automatically tie itself to it.

Click the Add Searchbox button now. You should see your new searchbox appear just above the function. Notice the nifty magnifying glass icon that appears next to the search box. You can delete this (and any control) by highlighting it in Control Movement Mode and pressing delete but for this example, lets leave it there.

You may notice the debug window has something to say to us now. In order for Searching to work in BR, the listview has to be sorted on some column or another. Otherwise the BR search won't do anything. ScreenIO is reminding us to specify a sort column for our listview.

Go to the Listview Properties window and specify a sort column. We'll sort it on column one for this exmaple.

You can get to Listview Properties by clicking on the listview until it cycles through the various modes and you see the Object Attributes Window. Or, you can click on the Debug listview and select the note and press Enter on it. The Debug listview in ScreenIO will attempt to do its best to position you in the location where the error is found, if it thinks there is a problem.

Now that our search box has a sort column, we're almost finished. The only thing we still need to do is specify the exit conditions for the program. Here, we tell ScreenIO what the user has to do to end the program.

To exit a program in ScreenIO, one of your custom functions has to change or set the ExitMode value. There are several different modes you can set ExitMode to. For a Listview, we're mostly concerned with "SelectAndQuit" (return the current selection, don't save any data, exit the screen) and "QuitOnly" (return nothing, exit the screen). Normally you would add a button and specify "let ExitMode=SelectAndQuit" or some variation in the Function parameter for the buttons.

However, a listview screen nearly always needs a "Select" and a "Cancel" button, and an Add/Edit screen nearly always wants a "Save" and a "Cancel" button. You can easily add the most common exit buttons for your screen by selecting "Add Exit Buttons" from the "Add Control" windows dropdown menu.

Select this option from the windows menu now.

You'll now notice the new buttons are added to the screen. However, they may not necessarily be in the best position. ScreenIO attempts to line them up with the rightmost control on your screen, and place them near the bottom, but it can't read your mind and it doesn't always get them in the most ideal place.

Go now to Control Movement mode and position the new buttons so that they line up with everything else and look better.

Once these buttons are added, our screen is starting to look pretty good. Lets take a closer look at the buttons we added. ScreenIO entered most of the data for us, but you can always manually add your exit buttons and put whatever you want in them.

The Select Button has "let ExitMode=SelectAndQuit" entered in its Function Property. This makes it so that clicking on this button will set ExitMode and ScreenIO will exit the screen, returning the key of the item the user selected.

The Cancel Button has "let ExitMode=QuitOnly" entered in its Function Property. This will make it so that if the user presses the Cancel button, the screen will exit, returning nothing.

Testing your new screen

Now it's time to give our screen a try. Save the screen by selecting File, Save and Compile from the windows dropdown menu. ScreenIO will compile your screen, including any custom code you have added to it, and save it in the Screenio data files and on the disk.

Now you're ready to test the screen. Do so by selecting "Test Screen" from the "Screen" windows dropdown menu.

ScreenIO will now launch your screen in a new copy of BR. Lets give the new screen a try. The Search box should be working, and pressing the Select button should exit the screen, returning the key of the currently selected customer. The "Add" and "Edit" buttons won't work until we create the "CUSTEDIT" screen which we'll do next, but they should at least give an error message saying "The screen could not be found."

Custom Code

In looking at our new screen, I noticed the Phone Numbers don't look right. We should add a custom function to format the phone number to a more readable format by inserting "()-"s. This will add that extra professional touch to your Screenio screen.

Exit your test screen by clicking on the Windows X. Every ScreenIO screen will exit when you click the Windows X, returning control to your calling program so that you can handle the X however you want to in your own code.

Once the test window is closed, you should see the main ScreenIO designer again. Go to the Listview Controls Object Attributes page. We're going to add a custom Filter Function, so click on the button for setting the Filter Function.

When you click this button, the Custom Function Selection dialog appears. From this window you can create new Cutom Functions, or easily select existing Custom Functions that you've used in your screen before. With a little training, you can make your Custom Functions generic and reusable in all your screens, drastically cutting down on future development time. For now, we're going to add a new function.

Type the name of the new function, "GetPhoneNumber" in the textbox and click the "New" button. A Messagebox will pop up asking you if you are sure you would like to create a new function.

Click "Yes" and MyEdit (or your default editor for opening .BRS files) will open, showing you a blank, freshly generated new function.

Customize this function by typing the following code in your MyEdit window, and press the "Save" button.

  ! function\getphonenumber.brs
  ! Created on 03/31/2010
  !
  ! fnGetPhoneNumber - This Function will unpack the phone number from our
  !  customer file, adding in "()-"s where appropriate to make it easier to
  !  read.
  !
  !
  !
  def fnGetPhoneNumber
     let f$(cu_phone)="("&f$(cu_phone)(1:3)&") "&f$(cu_phone)(4:6)&"-"&f$(cu_phone)(7:10)
     let fnGetPhoneNumber=1
  fnend

The Filter event is fired for every record that is placed on the listview. You can include or exclude records by returning true or false with your function. In this listview, we want to show all records, so we always return true.

You can also pre-format the data before sending it to the listview. The first line of our function above inserts "(", ")", and "-" into the phone number field to make it look nicer.

After Saving your new function and switching back to the ScreenIO designer, you'll notice the new function is already assigned to the filter event for the listview on our screen.

Now, save and test your screen again, and you should be able to see the phone number column is now nicely sorted in your program.

Congratulations! You've just created your first ScreenIO screen. I hope you're beginning to realize how much time this amazing product can save in your future development.

I poured years of my life into this project, and the number one reason I did it is because I believe that as BR vendors, we simply cannot compete with programmers in other languages unless we start using the same tools they are using. ScreenIO has been my greatest programming achievement so far, and I really believe this product has the ability to change the future of BR and the future of all of us as BR programmers, enabling us to compete again in a world moving faster than any of us can imagine.

There is much more to the Screenio product than could be explained in a short demonstration. This is only the tip of the iceburg. I've been using ScreenIO now for two years to design every GUI interface I've written in BR. The only thing my clients notice is how much faster and cheaper I'm able to accomplish development, with beautiful, professional results.

I hope you've enjoyed this simple demonstration, and I sincerely hope you consider joining us by using ScreenIO to enrich your programming life, save time, and allow you to focus on designing quality software instead of having to deal with programming limitations and outdated techniques.

Next, we'll be stepping into a more detailed Screen, an Add Edit screen for our new Customer program.