ScreenIO Library

The ScreenIO Library is a Rapid Application Design tool that enables Sage AX to create complete custom programs for a fraction of the cost of traditional development. For example, a fully functional File Maintenance program can now be created for $300. A zoom function or any other "single screen" program can be created for $150.

These "screen functions" integrate directly with your existing database and can be implemented as a standard BR library anywhere in your existing software. Some of our customers have placed them on tabs in already existing "tabbed windows" (or new tabbed windows). Some of our customers used them to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

Just about any business application can be designed faster, cheaper, and easier using ScreenIO, than ever before. You can even build entire application suites out of "Screen Functions". Sage recently wrote our entire internal accounting system using "screen function" technology, in just a couple of weeks.

The ScreenIO Library is a sister library to the FileIO Library. The ScreenIO library builds upon and requires the FileIO library in order to run.

The ScreenIO Library is a third party developer tool created and marketed by Sage AX to the BR programmer.

Bookmarks

Before we get any farther, if you're here for help with ScreenIO, here's a short list of common reference links:

ScreenIO's fnFm Parameter List
Custom Function - Events
Custom Function - Parameters
Keyboard Reference
Animations
ExitMode

Using ScreenIO Screens

This section of the documentation deals with all of the ways to make use of your screens created with the ScreenIO system.

Screen Functions

What is a Screen Function?

A Screen Function is a complete self contained program, that can be chained to, procced to, run as a regular program, or even run as a library from right in the middle of your existing program.

Screens are Modular and Reusable. That means you can create a screen for selecting a customer from a listview on the screen. This "Listview Screen" can also have buttons that chain to other screens, such as an Add/Edit Screen.

Now you have a complete FM program in two screens, for maintaining the customer file. But wait, what if you need a "Customer Selection" listview in your other programs? No problem, the same "Screen Function" program that was run before as your Customer FM, can also be run as a library function, as your Customer Selection screen.

So a Screen Function is more than a program. Its a program and a library, a gui, a complete software generation system, and an easy way to write beautiful software in BR that can be implemented again and again in your programs.

A Screen Function is a totally modular object. Its easy to add a screen to an existing program, or to another screen. By combining multiple screens you can create truly amazing effects.

By Combining four screens together, we can even write File Maintenance programs that work on two data files simultaneously, with a parent/child relationship!

How does it work?

Using our powerful ScreenIO Programming System, we create the Screen and save it in an internal data file that keeps track of what data needs to be displayed where on the screen, where it needs to be saved on the disk, and what we want to do with it. We can even embed function calls and business logic directly in the screens. When we "compile" the screens, a screen helper library is created with all the custom function code that needs to run from your screen. This helper library also serves as the program you can use to run your screens.

By keeping the screen layout in data files, it becomes easy to modify and easy to maintain. By making the screens run as library functions, they become easy to implement anywhere in your existing programs. All you have to do is create the library linkage and call the program with the following two lines of BR code:

 LIBRARY "screenio" : fnfm$
 let Result$=fnfm$("scrnname")

Result$ can be queried to see what the user did in the screen. A listview selection screen will return the record selected. An Add/Edit screen will directly write the results to the data file for you, and return the key to this new record in Result$. If the user cancels, Result$ will be empty.

What can a Screen Function Do?

A Screen Function can do many things. A Screen Function right now generally fits into three categories:

 1. A Listview Screen Function
 2. An Add/Edit Screen Function
 3. A Menu/Simple Screen Function

Listview Screen Function

A Listview Screen Function is a Screen Function that is tied to a data file (through fileIO) and has no editable text controls on it, and has a Listview on it somewhere.

A Listview Screen Function is now the very easiest way to implement 2D Controls in your BR programs. A ListView Screen Function displays all or some of the records in a data file and allows the user to select one. In your Listview screen, you may also have a link to the add/edit screen for the same data file, creating a basic File Maintenance program. You can use your Listview Screen anywhere that you would like the user to select a record from the ListView Screen's Target File. If it is tied to an Add/Edit screen, you may also use it as the File Maintenance program for that screen. You can use the same screen in multiple ways.

Add/Edit Screen Function

An Add/Edit Screen Function is a screen function that is tied to a data file (through fileIO) and has editable text controls on it, and no Listivew control on it anywhere. An Add/Edit screen can be passed a key, which will cause it to act as an Edit Screen Function, telling ScreenIO to edit the record who's key was passed in. If the Add/Edit screen is not passed in a key, it will act as an Add Screen Function, telling ScreenIO to Add a new record to the data file.

An Add/Edit Screen Function is the easiest way to create any sort of user interface asking for specific data from a customer.

A Menu/Simple Screen Function

A Menu/Simple Screen Function is a screen function that is not tied to any data file. This sort of screen is very limited in functionality. The primary purpose of using such a screen is to create a menu of buttons that call other screens or other programs or library functions or parts of your code.

A Menu/Simple screen function cannot change any data on disk because it is not tied to a data file. It is also not possible to get a lot of information back from the user in a Simple Screen Function, because instead of returning a key to a record in a data file that was edited (like an Add/Edit screen function would), a Menu/Simple screen is limited to returning a 255 byte string for its return value.

Limitations

No combination Listview/Add/Edit screens

It is not possible to make a screen that contains both a Listview, and Add/Edit capabilities in the same screen. When the user changes selection on a Listview, this changes the current record that the screen is using. If they were attempting to change a record on a combination ListView/Add/Edit screen, their changes would get lost each time the Listview selection changes. For that reason, if you wish to have both a Listview and some record selection going on at the same time, you will need to have two screens and tie them to each other.

It is much better to stick to a single purpose for each Screen Function.

Future

The following features are not currently available in screens, but will be soon:

Grids

Grids are not currently supported in ScreenIO. However, you can do just about anything using a 2 screen Listview and Add/Edit Screen Combination (a simple FM) that you can do with a grid. In future releases of ScreenIO, we will add support for Grids Directly.

Floating Child Windows

ScreenIO runs perfectly fine in both BR 4.1 and BR 4.2. However, it does't currently support advanced BR 4.2 features such as floating child windows. This will be coming soon, however.

Implementation Guide

Implementing your new Screen Functions in your existing programs is simple, modular, and flexible. The same screen can be used in multiple places in your program suite. Any changes or bug fixes to your Screen Function change it everywhere that it is used, thanks to the power of Libraries.

If you order a screen function from Sage AX, we will send you information explaining how to implement it. If you want to read about all the various ways to implement a screen, read on. If you are unsure what one of the options means, don't worry about it. If you buy a screen from Sage AX, we'll tell you which options apply to your screen.

Installing your new screen

When you order a screen, Sage will send you the following files:

 data\screenio.dat     - Screen Header Data file containing your new screen and all your old screens
 data\screenio.key     - Screen Header Key file
 data\screenfld.dat    - Screen Fields Data file containing all the fields for your screens
 data\screenfld.key    - Screen Fields Key file
 data\screenfld.ky2    - Screen Fields Key file

 screenio.br           - Free ScreenIO Runtime Library required to run your  screens
 screenio\scrnname.br  - Screen helper library (compiled in a br program)
 screenio\scrnname.brs - Screen helper library (BR Source File, included for your convenience only.)

"scrnname" is replaced by the name of your new screen.

To begin using your new screens, simply copy the files into the main folder of your BR programs.

Running your new screen

You can now run your new screen by simply typing:

 LOAD scrnname
 RUN

Calling your screen from your existing programs

However, to really get the most mileage out of your screen functions, you should implement them as library calls. This will enable you to interpret the result of the users action in the screen and act accordingly.

To implement your new screens as library calls from within your existing programs, all you need to do is add a library statement to the ScreenIO runtime library, and call your screens.

 01000 LIBRARY "screenio" : fnfm
 01200 let fnfm("scrnname")

When your program gets to line 1200, your screen is loaded and displayed, and the user is able to do anything your screen is set up for them to do. When they are done, control returns to your program at the line after 1200.

Returning Information from your screen

The ScreenIO Runtime Library can return limited information about the execution of each screen. This return string is limited to 255 characters, and is generally used to return the key of the record edited/added/selected from the listview. If a Cancel option is available in your screen, and the user cancels, then the return will be blank.

ScreenIO Returns the key of the record, by default. If you just draw a screen, and tie some fields from the file to it, writing no custom code at all, the key of the edited record will be the return value.

However, by placing custom code in your screen, it is possible to override the default return value for your Screen Function with any kind of data you want.

In general, if you want to use your screen to query the user for information that does not get saved in your system, then you create a screen and tie it to a temporary data file. In your calling program, you call the screen, and if the user did not cancel, you use that key to read the results from the temporary data file and interpret them, deleting the information from the file when you're done.

However, if the amount of information you wanted to return was less then 255 bytes, it would be possible to override the return value for the screen to just return all that information in a string of data that could be interpreted by your calling program.

Advanced Screen Implementation

ScreenIO Runtime Engine Library Functions

There are a few other useful functions in the ScreenIO Runtime Engine Library. They are all used to display and pass control to your screen, your screen but with a few different options:

• fnfm("scrnname"; key$, row, col, ParentKey$, ParentWindow, DisplayOnly,Dontredolistview,Recordval,Mat Passeddata$,Usemyf,Mat Myf$,Mat Myf,Path$,Selecting) - Displays and passes control to your screen. FnFm returns true if a record was selected/edited and false if the record was not edited. If the return value for the screen is numeric, then fnfm would return the numeric return value of the screen. If the return value is a string, calling fnfm will discard the string return value and return only 1 if the user didn't cancel, or 0 if they did.

• fnfm$("scrnname"; key$, row, col, ParentKey$, ParentWindow, DisplayOnly,Dontredolistview,Recordval,Mat Passeddata$,Usemyf,Mat Myf$,Mat Myf,Path$,Selecting) - Displays and passes control to your screen. FnFm$ returns the key of the record selected/edited, or blank if the user cancelled out of the screen. It is possible to override the return value in the screen by adding custom code to your screen. If the return value for a screen is numeric, then fnfm$ returns "str$()" of the numeric return value of the screen. Use "val()" to turn it back into a number if you need.

• fnDisplayScreen("scrnname"; key$, row, col, ParentKey$, ParentWindow,Recordval) - Deprecated, use fnfm instead, with the Display Only parameter. (This displays a screen, but does not pass control to it. This sort of functionality is very useful for advanced implementation of your screens in your programs. Oftentimes it is desirable, especially with a listview screen, to display a listview of items on the screen but not edit it yet. In that situation, you would want to continue in your main program, and wait until the user clicked on your listview Screen Function, at which point you would then call fnfm or fnfm$ for the same screen, allowing the user to use the listview later. The return value for fnDisplayScreen is the window number of the new Screen Function Window opened. When you are done displaying the Listview Screen Function and want to erase it, simply close the window number that fnDisplayScreen returned.)

Within ScreenIO you may call screen functions from any existing screen function by placing the internal syntax for calling a screen directly in the click event for any button or any other event in your screen. This would be in the form [SCRNNAME(Row,Col)]Key$="blah" : ParentKey$="blahblah". Row, Col, Key$, and ParentKey$ Are optional. You can also specify Record=, Selecting=, DisplayOnly=, and Path$=.

The simplest (and most common) form is just to say [SCRNNAME]

ScreenIO Runtime Engine Library Function Parameters

The ScreenIO Functions listed above all accept the following parameters:

• Scrnname$ - This is the name of the screen you are trying to call. This is the only required parameter. If you are using fnCallScreen$, it is also possible to substitute the internal screenio syntax for calling screens here, which is [SCRNNAME(Row,Col)].

• Key$ - This is the key of the current record you are editing. ScreenIO interprets this variable when it is loading and displaying your screen. If it is blank, it does not read the screen, and instead performs the screen's initialize event, the custom code (if there is any) for initializing a new record into the data file. However, if a key IS given, then instead it reads that record from the data file, performs the input, and saves the data.
  
  Note: A Key should never be passed into a Listview screen

• Row, Col - These scalar parameters represent the physical location to place the top left corner of your screen. If no Row or Col is specified, then the screen opens in the middle of your BR window, resizing Window 0 if necessary to display your entire screen. If you DO give a Row and Col value, then it is your responsibility to make sure the Screen Function fits in the BR window - otherwise you will get the BR Internal Error for invalid Row and Col specification when you try to run the screen.

• ParentKey$ - This is an extra value you can pass into your screen function. It is ignored by the ScreenIO Runtime Engine Library, but it may be used by your custom functions. Most often it is used by the filter event of a listview, to limit the records in the Listview. (If a Listview has no filter event defined, then by default every record of the data file is displayed).

• ParentWindow - This optional parameter is used in conjunction with Row and Col to specify the parent window for the Screen Function. If no Parent Window is given, then window 0 is assumed to be the parent, and the new Screen Function opens on top of whatever other windows may have been on your screen before. If a Parent Window is given, then that Parent Window is used for the Row and Col position of your screen.

• DisplayOnly - This optional Boolean Flag tells the ScreenIO Runtime Engine Library to display the screen and then exit without passing control to the screen. This parameter makes FnFm, FnFm$, and fnCallScreen$ work the same way that fnDisplayScreen works above. In the case of FnFM, the return value becomes the window number of the newly opened Screen Function. In the case of FnFM$ and FnCallScreen$, the return value becomes the "str$()" value of the window number of the newly opened Screen Function - use "val()" to get the actual Window Number as a numeric value.

• DontRedoListview - This optional boolean parameter is used when running a screen from within another screen, for example in one of your custom functions. If the calling screen has a listview on it, the Listview will automatically be repopulated when you return. If you're calling a screen that doesn't change the contents of the listview then its better not to repopulate the listview, in order to make your screens run as quickly as possible. Use this boolean flag to instruct ScreenIO not to redraw the listview you're returning to. If you're implementing a screen that Sage AX made for you, we will have already set this for you.
  
  Example: If you're in a listview screen and its calling an add/edit screen, this parameter is used on the call to the add/edit screen but it applies to the listview screen.

• RecordVal - If you are editing a record in an Add/Edit Screen By Record instead of by Key, specify the Record here, and leave "Key$" blank.

• Mat PassedData$ - Mat PassedData$ is an array you can use for passing Custom Information into your screens. Any of the functions inside the screen will have access to Mat PassedData$. If you're implementing a screen from Sage AX, we will tell you if there is any custom data you need to pass in.

• UseMyF - If you set this boolean parameter to True then you can pass in your own mat F$ and mat F arrays. Instead of reading the record from the disk, ScreenIO will use the record in the arrays you're passing in. Use this for an Add/Edit screen when you don't want ScreenIO to read or write the record on disk.

• Mat MyF$ - This is the corresponding string array containing information from a record you want to edit with a screenio screen. Use with the UseMyF parameter above.

• Mat MyF - This is the corresponding numeric array containing information from a record you want to edit with a screenio screen. Use with the UseMyF parameter above.

• Path$ - This is the FileIO Path$ Parameter that specifies a Data Path to be prepended to the path specified in your file layouts, in order to accommodate situations where the same data file with the same layout occurs in multiple paths.

• Selecting - This is a flag you can use to signal to your screens when you're running them as to the intentions of your users. You can use it to define different "modes" for the current screen. The parameter is not used by ScreenIO at all, but simply passed onto your functions, similar to the way ParentKey$ works.

How does it work Internally

Program Flow

When you call your new screen, no matter how it is called, the screen layout is loaded from the screenio data files (ScreenIO.DAT and ScreenFld.DAT). Then, if a file layout is given, the file is opened, and if there is a key given, then the key is read and the read event is triggered. If a key is not given, then the initialize event is triggered.

After that ScreenIO maps the fields in the data file onto the fields on your screen and displays them, allowing the user to interact with the screen as they wish. The screen remains in control until "ExitMode" is triggered, either from one of the events, or by pressing the ESC key to trigger an ExitMode of Cancel (by default), or the ENTER key to trigger an ExitMode of Select (by Default).

Once a Screen Function Event has been triggered that sets ExitMode to one of the various valid exit modes, the screen is exited, and depending on ExitMode, the return value is calculated and the data is saved or added, or dropped, or ignored, and the return value is set. The Prewrite Event and the Exit event is triggered here.

Philosophy

ScreenIO is a modular event driven system for BR. The ScreenIO Design and Runtime Libraries do for BR what Visual Basic did for the Microsoft world of programming. However, its easier to create and use ScreenIO screens then it is to write VB programs, because BR is simpler then VB in many of its internal working details, and because ScreenIO screens have the ability to write to your data files without having a stitch of custom code.

ScreenIO was designed to eliminate the BR headache of working with 2D object-style controls in the non-object oriented world of BR programming.

ScreenIO cannot make every program in the world. I would be very impressed if I saw someone make a video game in ScreenIO. It is limited to interfaces that BR can produce, and that means that you can only input from one screen at a time (because BR's input statement is Modal). It can only make BR style listviews and grids, and your interfaces work using rows and columns, instead of twips or pixels like other languages.

Instead, ScreenIO's focus is on remaining as simple as possible, while still allowing the flexibility to accomplish 90% of the business programming purposes. It can't make absolutely everything - if it could, it would become unruly and difficult to use. By limiting the scope, however, we are able to create 90% of business programs, much faster and easier then ANY other method of programming on the market.

Modular

Because ScreenIO is Modular, it is extremely easy to implement your screens in any of your existing programs using the chain statement, or more commonly, a library function call. Your screens can be called from each other, even recursively should you so desire.

Event Driven

Because ScreenIO is Event Driven, it is easy to call any of your existing business logic code from one of our screens.

Each ScreenIO Screen Function has several events, that can be used to extend the functionality of your screen, provide custom validation, provide custom filtering on a Listivew, extend functionality by linking to additional screens, and control and override the return values of your Screen Functions.

Your Screen Functions have the following events that can each be overridden with custom code, a library call, an execute command, or a link to another screen.

Screen Events

• Enter Event: This event is triggered when your screen is first displayed.

• Initialize Event: This event is triggered any time you call your screen without giving it a key$ (as long as there is a data file). The initialize event is used to initialize the values for newly added records in one of your data files, in an Add/Edit Screen.

• Read Event: This event is triggered when your screen reads the initial record, and in a Listview screen, any time the Listview selection is changed. It is primarily used for unpacking the data and placing it on a screen.

• Write Event: This event is triggered when the user selects the "Save" option in your screen, just before actually saving the data to the disk. In the Write event, you can cancel the users exiting of the screen, or change the exit mode to any other exit mode you like. You can also make any last minute changes to the data before it is saved to the disk.

• Mainloop Event: This event is triggered every time the main Rinput Fields statement is passed. You can use this event to update information on the screen, implement special keys, or implement windows menu's in your screenio screens.

• Wait Event: This event works in conjunction with the timeout setting you specify for your screen. This timeout value specifies the number of seconds before triggering a WAIT event. If you specify a WAIT event here, your event will be triggered if the keyboard is idle for that many seconds. If you do not write a WAIT event, the default ScreenIO Wait event is triggered.

• Record Locked: This event is triggered whenever a record is locked in a screenio screen. If you do not specify your own locked record event, the default ScreenIO Locked Record Event is triggered.

• Exit Event: This event is triggered last, when the screen is being closed.

Individual Control Events

Each of the controls on your screen has its own event, which get triggered in various ways depending on the control.

• Filter Event - In a Listview Control, the listviews event is the filter function that gets called to determine if the currently selected record should be added to the listview or not. Your filter function receives MAT F$ and MAT F for the screen, and if it returns true, (anything other then 0 or blank) then the record is included in the listview. If your filter function returns an HTML color code, then that HTML color is used to color that specific row of the listview. If there is no filter function, the listview displays every record in the data file.
  • Listviews

• Validation - In a data Control, the data Control's event is the validation function that gets called to determine if the data is acceptable or not. If there is no Validation Function, then the data gets saved according to internal rules: All text data gets saved regardless of what it is, and numeric data is saved only if the user entered valid numeric data. The validation function receives the value the user is trying to save, and it can modify that data, and return true or false, to force the data to be saved or not. (However, you never can force saving string data in a numeric field, that will always be discarded by the ScreenIO Runtime Engine).
  • CheckBoxes
  • SearchBoxes
  • Radio Buttons

• Click Events - Non-Data Controls have a "Click" event. This event is triggered whenever the user clicks on the control.
  • Buttons
  • Pictures
  • Captions

Purpose of Events

By overriding various events with custom code, we can make your screen functions behave any way you want them to.

Screens with two data files

ScreenIO Screen Functions are limited to one data file each. This means that each ScreenIO Screen function can only directly and automatically modify the MAIN data file for the screen. However, it is possible to modify additional related data files through the custom code added to the various screen events.

It is possible to use ScreenIO to modify data sets of two data files with a parent/child relationship, by using four screens and tying them together, and setting special code in various events.

Example

If you had a set of invoice files, with one invoice header file and another invoice detail file containing the line items of various invoices, and you wanted to maintain those files with ScreenIO, you would create four screens.

The first screen would be a listview screen tied to the invoice header that would list all the invoices on record. (You could also set up a filter function limiting this display to invoices for a certain customer (passed in using ParentKey$) if you desired.) This screen would have buttons linking to the Add/Edit screen for invoice headers (the second screen described below).

The second screen would be the Edit screen for the listview header. This screen would link (using Display Only) to the third screen (below) in its Enter Event. It would also have a button linking to the third screen (below) without the Display Only option, so that the user can click on this button and jump to the Listview displaying line items for the invoice.

The third screen would be a listview for the invoice detail lines. This screen would have to have a filter function to limit its display to only lines on the currently selected invoice (which would be passed in using ParentKey$). You would link to this screen using "DisplayOnly" in the second screens "Enter Event", so that when they are editing the invoice header records, they will also be able to view the line items on the listview. You would also have placed a button on Screen 2 linking to Screen 3 without Display Only (described above). The third screen, just like the first screen above, would have buttons linking to the Add/Edit screen for Invoice Detail items.

The fourth screen would be a simple Add/Edit screen for the detail line items. In the initialize event for this screen, you would want to initialize the value in the detail file that ties it to the header file. In our example of invoices, we would initialize an invoice line item by specifying which invoice it appears on.

This process allows you to quickly and easily create a set of four Screen Functions that preform complete FM operations on two linked data files with a parent/child relationship.

The ScreenIO Animated Loading Icon

ScreenIO comes with an Animated Loading Icon that automatically appears whenever a listview takes a long time to load. This tells the user that something is happening, so they know its not just hung.

You don't have to do anything to your screens to use the loading animation. It automatically happens whenever a listview takes more then a couple seconds to load.

Changing the Loading Icon

See Working with the ScreenIO Loading Icon for more information.

Save Money with Screen Functions

Lower Development Costs

A "Screen Function", depending on the complexity, represents about 4 - 8 hrs of traditional development time. Sage AX is selling all custom screens at a base price of $150. Custom processing code is occationally necessary to achieve particularly powerful effects, and it is available at a small additional charge. Most screen functions require little or no custom code, but more complex functionality is available. You can do just about anything with a screen.

Because the screens are contained in Data files, they are easy to modify and easy to maintain.

Because ScreenIO does the bulk of the work for you, the cost for custom processing code in your screens is lower then you might think.

Lower Maintenance Costs

The ScreenIO Runtime Library required to run your screens is free.

The ScreenIO Design engine used to create your screens is available for sale, for a one time unlimited-lisence fee. It will pay for itself after about 30 screens.

You don't need any special editor to edit the custom code that's already in your screen. That can be done by simply loading the screen helper library and modifying the code, the same way you would modify any BR program. However, if you make those sorts of changes yourself, you should send us a copy of your changes so that they can be included in any future modifications we make to that screen for you.

Because ScreenIO uses FileIO to access all your data files, you never need to update your screens for file layout changes. This happens automatically because of the magic of the FileIO Library. The only thing you have to do is update your File Layouts.

Estimated Price for your Screen Project

Please contact Sage AX (gabriel.bakker@gmail.com) with your project details to recieve a free price quote.

Visit http://www.sageax.com/products/screenio-library/ for more details.

Making ScreenIO Screens

It is also possible to purchase a ScreenIO Designer License, that entitles you to a full copy of the ScreenIO Designer, which you can use to make your own ScreenIO Screens. This part of the documentation deals with using the ScreenIO Screen Designer.

The ScreenIO Designer (Overview and Reference)

Error creating thumbnail: File missing

The ScreenIO Designer is modeled after other modern visual program designers. However, it is written entirely in BR, and as such has a few limitations. We have done our best to work past the limitations of traditional BR programming by employing a clever combination of tricks and advanced BR syntax.

At the top of the screen is the traditional Windows Menu. The left column of the Screen is made up of the Toolbar, which contains the Window Attributes, the Field List, and the ToolBox. At the bottom of the screen is the Debug window. The remaining space is the Editor window, where you can view and modify your screen in a graphical programming environment.

Windows X

Clicking on the Windows X from the ScreenIO Designer will close the ScreenIO Designer and exit BR.

Clicking on the Windows X when running your screen will Cancel and Exit out of all screens that you may currently be in recursively until you reach the calling program. It is up to your calling program to then close whatever it was doing and exit.

If there is no calling program, then clicking on the Windows X when running a ScreenIO screen will close the program and exit BR.

ScreenIO Windows Menu

File

File Options

New

Create a new screen.

Load

Load a previously saved screen.

Save and Compile

Save and Compile your screen.

Compile

Compile your screen only. Use this if you've changed some code but you haven't changed the screen itself.

Export Screen

Export your screen to a ScreenIO File (*.sio) for transferring it between different ScreenIO implementations.

This will not save the custom screen functions. It is necessary to transfer any required custom screen functions by hand from the functions\ subfolder in your source ScreenIO implementation.

Import Screen

Import a screen from a ScreenIO File (*.sio).

Purge ScreenFlds File

Because of the way ScreenIO Stores the screen information, the screenflds file tends to grow and grow. Run this menu option to purge all deleted records from this file and free up all the unnessicary space.

Recompile All Screens

This menu option automatically recompiles all your ScreenIO Autogenerated Helper Libraries. This is useful if you made a change to a Custom Screen Function that is in use by more then one screen, and you want to apply the change everywhere in your implementation at once.

Quit

Exit the ScreenIO System to a BR Prompt.

If you want to exit BR entirely from just one click, click on the windows "X".

Options

Performance Options

Click to Move

Default: On

This setting enables/disables the grid of blue dots that allows you to quickly move your controls around the screen by just clicking on the destination. On some computers, or some network settings, the click-to-move dots can slow down performance noticably. If this happens, disable the dots by using this menu setting, and move the controls around using the keyboard instead of the click to move dots. (Use the Arrow Keys).

The Click to Move dots are particularly slow when you are modifying large 2D controls such as ListViews.

Preview Listviews

Default: On

ScreenIO attempts to provide the developer with a WYSIWYG environment. To that end, it renders your screen as much as it possibly can at design time.

If you make a Listview Screen for a Data File that has records in it, the ScreenIO Designer will do the best it can to populate that listview even while you are designing the listview.

Previewing the listviews can be very slow for large data files. If you wish to increase performance, turn the "Preview Listviews" setting off.

Real Time Filters

Default: Off

If your ScreenIO listview has a custom filter function assigned to it, you can enable the use of the filter function during the WYSIWYG Preview Listview rendering.

Depending on the resources of your computer, this setting can have a serious impact on performance.

If the Preview Listviews setting is turned off, then the Real Time Filters setting has no effect.

Add Control

The add control menu gives you keyboard access for adding any control you want to your screen.

Add Field

This places the cursor in the Fields Listview where you can select fields from your data file and with the arrows and add them to your screen by pressing "Enter".

Add Exit Buttons

This automatically adds Exit buttons to your screen. If its a listview screen, then it adds "Select" and "Cancel" buttons. If its an Add/Edit screen, then it gives you "Save" and "Cancel" buttons. These buttons are added to the bottom right corner of your screen, lining up with your rightmost controls.

Add Textbox

Adds a Textbox. This is the same as clicking the button in your Toolbox.

Add Caption

Adds a Caption. This is the same as clicking the button in your Toolbox.

Add Checkbox

Adds a Checkbox or a Radio Button. This is the same as clicking the button in your Toolbox.

Add Listview

Adds a Listview to your screen. This is the same as clicking the button in your Toolbox.

Add Searchbox

Adds a SearchBox to your screen. This is the same as clicking the button in your Toolbox.

Add Button

Adds a Button. This is the same as clicking the button in your Toolbox.

Add Picture

Adds a Picture. This is the same as clicking the button in your Toolbox.

Skip A Space

Skips a space for the automatic placement of controls. This is the same as clicking the button in your Toolbox.

Screen

Screen Options

Adjust Screen Size

Automatically resizes your screen to just large enough to fit all your controls on it.

Move Controls

This puts ScreenIO into Control Movement Mode

Visit Checklist

This puts the curser in the Debug listview. You can do the same thing by clicking on the Debug Listview.

Set FG Color

This brings up the color selector, allowing you to select the Foreground Color for your screen. This is the same as clicking on the button in the Window Attributes panel.

Set BG Color

This brings up the color selector, allowing you to select the Background Color for your screen. This is the same as clicking on the button in the Window Attributes panel.

Select File Layout

This brings up the file selection dialog. This is the same as clicking on the button in the Window Attributes panel.

Set Events

This menu option does the same thing that clicking on the "Set Events" button (under Window Attributes) does: It opens a window where you can specify your Screen level Event Handler Custom Screen Functions.

Set Tab Order

This menu option allows you to set the tab order by clicking on all of your screen controls in the order that you want the tab order to go. This function is also availble from the "Set Tab Order" button in the Window Attributes corner of the ScreenIO Designer.

Configure Debug

This option allows you to specify any special instructions to use when testing the screen via the Test Screen menu option below.

Test Screen

This option fires up a second copy of BR to test your screen. All screenIO screens can be exited by clicking on the Windows X. Your screen runs in a completely separate instance of BR, so you don't have to worry about the test of the screen screwing up whats going on in your editor.

Its important to remember to save your screen before testing it. Otherwise, you will see the previous version of the screen when you test it.

ScreenIO will attempt to use the same BR executable and brconfig.sys file that you loaded screenio with, so make sure its the one you want to use for your application.

Help

Help Menu

Documentation

This menu option links to this wiki document.

About

Opens the ScreenIO About screen.

ScreenIO Designer Modes

The ScreenIO Designer has several different modes that it operates in. For the most part this is designed to be seamless to the programmer but it may help to understand whats going on behind the scenes.

BR has a major interface limitation, in that only one child window is able to be input from at a given time. The ScreenIO designer attempts to hide this problem by using different modes. The modes are as follows:

 let Inputattributesmode=1
 let Inputfieldlistmode=2
 let Inputeditormode=3
 let Inputeditormovemode=4
 let Inputdebugmode=5
 let Quitmode=6
 let Selectcolormode=7
 let Selectfilelaymode=8
 let Inputlistviewmode=9
 let Selecteventsmode=10
 let Settabordermode=11
 let Configuredebugmode=12

Input Attributes Mode is when the cursor is in the upper left corner of the screen, inputting the attributes for the whole screen. If you're in a different mode and you click on the Window Attributes, then the mode is changed to Window Attributes mode. Input FieldsList Mode is when the cursor is in the fields listview, and you're selecting fields to add to the screen. Input Editor Mode is when the cursor is in the attributes for a single field. Input Editor Move Mode is when the cursor is in the mode where you move controls, the mode with the blue dots. Input Debug Mode is when the Todo List debug at the bottom of the screen is active. Quit Mode is used to tell the designer to exit. Select Color Mode is the current mode whenever you're selecting a color for something. Select FileLay Mode is used to select the file layout for your screen. Input Listview Mode is the mode for entering the information for listview columns. Select Events mode is the mode you're in when you're selecting screen level events. Set Tab Order Mode is the mode for setting the tab order. Configure Debug Mode is the mode for configuring the debug window.

You can generally tell what mode you're in because that part of the screen will light up yellow.

Toolbar

The Toolbar Window is along the left side of the screen. It is made up of the Window Attributes window, the Fields List, and the Toolbox.

Window Attributes

The Window Attributes window contains information about all Screen level Attributes.

Window Name

This is the unique 8 digit Window Name. It is used as the unique key in the ScreenIO data file. It is the name you use to load your screen from code, and the name you use when you load your screen from the ScreenIO Designer File->Load menu.

Caption

This is the Caption in the Windows Title Bar when you run your application. If the Window you are creating has a border specified, then this is also the caption that appears in the border of that Child Window

Rows

The number of Rows your window takes up. You can change this any time, and your screen will adjust on the fly. This makes it easy to design your screens and then adjust the size of them when you already know what they will look like.

If you make your screen too small and not all the controls fit on it, the ones that are outside the border of the window will not be rendered, and a Debug Message will appear in the Debug Window. Simply make your screen large enough for all the controls to appear and move the offending controls away from the edge, and then resize your screen again to the size you want it to be.

Cols

The number of Columns your window takes up. See Rows (above) for more information.

Attributes

This Attributes Screen is used when opening your window. You can place any valid BR Window Attribute statement here. For example, to make your screen have a border around it, type "BORDER=S" in the Attributes setting for the window.

Picture

Type the path and filename of a picture file, and it will be used as the background image for your Screen.

Read Key

Specify the key to use when reading the file. The default is the first key specified in the layout for Add/Edit screens, and Sequential Read for Listview Screens.

Return Key

Specify the key to use when calculating the return value. The default is the first key specified in the layout.

Input Attr

Specify the Input Attr spec to use in the main Rinput Fields statement. This controls the appearance of the currently active field.

Wait Time

Specify the time to wait in seconds of keyboard inactivity before triggering a WAIT event. If you have no WAIT event specified, then ScreenIO will trigger the default ScreenIO WAIT event.

FG Color

This is the default Foreground Color when adding new controls to the screen.

BG Color

This is the background color for the screen.

File Layout

Click this button to select the file layout that your screen applies to.

Set Form Events

This button is a shortcut to the Windows Menu: Screen->Set Form Events. It opens a window where you can view and configure the ScreenIO Custom Helper Functions that get triggered for each of your Form (Screen) level Events.

Set Tab Order

This button is a shortcut to the Windows Menu: Screen->Set Tab Order. It allows you to change the tab order of your screen by clicking on your screen controls in the order that you would like the tab order to become.

Field List

This listview shows all the fields in the currently selected File Layout.

Because of a limitation in BR, only one child window can be active at any given time. You can tell if you are in "Input Fields List Mode" because the background for the Listview will turn Yellow. When you are in "Input Fields List Mode," you can navigate the listview with the mouse or arrow keys. Pressing Enter or Double Clicking on an item will add it to your new screen.

Toolbox

The toolbox contains buttons for adding each of the different control types supported by ScreenIO.

Add Field

This button adds the currently selected field from the Fields List to your new screen. This is the same as double clicking on a listview item or pressing enter while in Input Fields List Mode (while the Fields List is yellow). If you are not currently selecting a field from the Fields Listview, then clicking on this button does nothing.

The currently selected field is added as a Textbox that is automatically tied back to your data file. To the left of this new textbox is a caption containing the description from the File Layout for this field. Both can be customized to your hearts content, and positioned any place you want on the screen.

Add TextBox

This button adds an empty Textbox Control to your new screen. This textbox control can then be configured and tied to a field from the data file, or left as a Screen field that can be accessed and modified by your custom ScreenIO Helper Functions.

MultiLine Textbox

BR Supports Multi-Line Textboxes via a little-known programming trick that dates back to the days before graphical controls. It is possible to use this technique to make multiline textboxes in BR, and ScreenIO makes the process easy for you. The only down side to BR multi-line text boxes is that you can only make a multiline text box that goes all the way to both the left and right side of the window.

To make a MultiLine textbox in ScreenIO, simply add a regular textbox to the screen and then press the PgDn key while in movement mode. It will stretch horizontally to fill the screen, and grow to become a multiline textbox.

Add Caption

This button adds an empty Caption Control to your new screen. This caption can be configured and the Text to display can be specified. Or, you can tie it to a field in the data file, or leave it as a Screen field that can be accessed and modified by your Custom ScreenIO Helper Functions

Add CheckBox

This button adds an empty Checkbox Control to your new screen. This Checkbox can be configured and its caption can be specified. It can also be tied to a data file, or left as a Screen field that you can access and modify.

You can tie your checkbox to a field in your data file by specifying a TrueValue and a FalseValue in addition to a FieldName for a field from the file. If the checkbox is checked, the truevalue you specify will be saved in the file. If its not, the falsevalue will be saved in the file.

Add Radio Button

To add a Radio Button, start by adding a Checkbox to your screen. Then convert the Check box into a Radio Button using the following procedure.

You can turn your checkboxes into radio buttons very easily. Simply add a group number (1,2,3,etc) in the attribute field and your checkbox will be converted to a radio button as ScreenIO builds the screen.

You oftentimes will want to tie a group of Radio Buttons to a single field in the data file. In that event, specify the same field name for every radio button, and specify the True Value that you want associated with each Radio button in the group. For falsehood values for all the controls in the group, specify a value of "~ignore~". This will instruct ScreenIO to ignore the falsevalue, saving the truevalue from the currently selected radio button.

Add Listview

This button adds an empty listview to your new screen. This Listview can then be configured and modified. If you enter "Edit Listview Columns" mode, then you can add or remove columns from the listview. If you are currently in Edit Listview Columns mode, then you can click on the Fields List to automatically add listview columns from your datafile directly.

Add Search Box

This button adds a Search Box and ties it automatically to a listview if one is found. You can also tie the Search Box to a Listview later from its control attributes window.

Add Button

This button adds a Button to your new screen. You can specify a Click Event Handler, some custom BR code that gets triggered whenever the button is clicked on.

Add Picture

This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.

Skip a Space

This instructs ScreenIO to skip a row for the automatic placement of Screen Controls.

Editor

The Editor Window contains your new screen.

From the Editor Window you can move your Screen Controls around, and also edit each of their attributes and event functions.

Debug

The Debug window lists potential warnings and errors discovered by our Screen validation routine.

Messages in Blue are Warnings. They point to things that our ScreenIO Validation routine believes don't really make sense, even though they aren't really going to cause an error.

Messages in Red are Errors. If those problems are not corrected, your screen will not function properly.

If you double click on a message, the ScreenIO validation routines will do their best to take you to the location of the error so you can find it and fix it more easily.

Using the ScreenIO Designer

Now that we have gone over the various elements that make up the ScreenIO Design Library, lets take a closer look at the process of making a Screen.

Create a New Screen

The first thing that every screen needs is a Screen Name.

Fire up the ScreenIO Designer. You will notice a few messages in the Debug window, right off the bat. One of these is an error message, that says "Window Name cannot be blank." (The message may appear white on a blue background instead of Red on a White background. This is because of the current row selection bar, which is White on Blue.)

The Window Name is the primary unique key for the ScreenIO Screens file, and every screen needs one. You use the Screen Name when invoking your screen, and when loading it from the File->Load menu.

Enter a name for your new screen.

The next step is to Select the File Layout for your screen.

One of the nicest features of ScreenIO enabling truly Rapid Application Development, is ScreenIO's ability to automatically modify data files that have been defined within the FileIO Library system.

In order to use ScreenIO to create screens that dynamically interact with your data files, it is first necessary to define your data files with FileIO style file layouts. If you have not done so, do so now. For more information on the FileIO Library, visit the FileIO Librarys page on this wiki.

Click the button to the right of the text "File Layout:". Select the file layout for the file you plan to interact with using this screen.

Error creating thumbnail: File missing

Add Fields to your new Screen

As soon as you select your file layout, the Field List listview should populate with all of the fields in the selected data file. At this point, you can add these fields to your Screen, by selecting them from the Field List listview and pressing the "Add Field" button (or pressing "Enter" from the Field List listview).

The fields you add will appear in the top left corner of your screen. You can go ahead and add all the fields you want in a row. They will all go on top of each other, and the Debug Window will change to reflect that many of your controls cannot be drawn because they are on top of each other.

If you'd like to create a Listview Screen instead, you can do that by adding a Blank Listview control to your screen. Then, follow the instructions below to position your listview where you want it. When your listview is in the position and size you'd like it, press Enter twice, to go to "Edit Listview Columns Mode". Click the "Delete Column" button once to delete the Empty Listview Column that appears by default, and then click on the Field List to Jump to the Field List listview. From the field list, you can then add columns directly from your data file to your listview, by selecting them and pressing Enter.

Position the fields on your new Screen

When you have finished adding your fields, click on one of your controls in the Editor window. A grid of small blue dots should appear, and your selected control will appear in Yellow, indicating that you are in Movement Mode.

While you are in Movement Mode, ScreenIO will group your captions with your textboxes for any controls that were added together. If you move the textbox control, the caption associated with it will move automatically. This is regardless of weather or not the caption is part of a control group.

This piece of magic is accomplished via the Caption Field poperty.

Keyboard Control Movement

In Movement Mode, you can position your control using the Arrow Keys. The Backspace Key makes your control narrower, while the Space Key makes your control Wider. PgUp and PgDn make your 2D control Taller or Shorter. Enter toggles between Movement Mode, and Control Attributes Mode. For more information, see the chapter on Screen Control Movement Mode Keyboard Reference.

Click to Move Control Movement

While BR does not support true Drag and Drop, you can approximate the functionality of Drag and Drop in BR. This is what the ScreenIO Click to Move feature is all about.

While you are positioning your controls around the screen, the currently selected control is highlited in Yellow, and the BR Print Statement for the control is displayed in the text of the control.

If you click on one of the blue dots, your control will jump to that location. You can use this feature to quickly place your controls on the screen.

First, click on the control that you want to move. It will highlite in Yellow. Then click on the blue dot where you want to move it to. It will move there. If there is a control group selected, then all the controls in the selected group will be moved relative to how the main control moved.

When you move your controls around, select the Text Box field and move that first. The Caption field will automatically move with you, following the Text Box around the screen. This may be confusing at first, but this feature is designed to save you time in the long run.

Move all of your new controls around until your screen looks nice. You can also resize your screen at any time by changing the values in the Window Attributes window.

However, the Click to Move feature can significantly slow down the ScreenIO Designer on computers with limited resources. If you prefer to turn it off, you can do so from the Options menu.

Error creating thumbnail: File missing

Control Attributes Window

When you have your screen looking the way you want it, it is time to begin modifying the attributes of your individual controls. Click on the control that you want to view the attributes for to select it. It will highlight in Yellow. Click it a second time (or press the Enter key) and a little window will open up showing all the attributes for the given control.

The control attributes window shows all the customizable attributes for each of your screen objects. Each object type has its own set of attributes and events.

Here is a list of all the available Control Attributes and what they do:

Control Name

This is the name for the control. Your controls do not require a name. However, if your control is not tied to a field, but you give it a name, then ScreenIO automatically reserves a place for that control in Mat S$. You can modify the value of that control within your Custom Screen Functions by using its control name.

You can also use the control name to identify controls from within your event functions. If the control is called MyControl, then you can access its Background Color by looking at BgColor$(ctl_MyControl).

Field

This is the field the control is tied to in your data file. When the user enters the screen, the record is read (or added) and the information from this field is displayed in the control. When the user finishes modifying the code and presses the Save button, the information is automatically saved back into the data file for you. Validation is provided for in the Validation Function (explained below).

Caption

This is the caption for your Caption Fields, Check Boxes, and Buttons. This is the Tool Tip Text for your Buttons (not implemented yet).

Caption Field

This is the Control Name of the field that is tied to this field for movement purposes.

Any time you use the Movement Mode to move a control around, if it has a Caption Field specified, then the control referenced in the caption field is moved automatically for you. This helps keep the caption next to the text box it applies to.

Spec Width

This is the Internal Width of the data allowed in the control. This is not to be confused with the physical display width of the control. You modify the Display Width of a control by pressing "Space" or "BackSpace" when you are in Movement Mode and the control is selected. The Spec Width specifies how wide the data in the control can be.

Sort Column

The Sort Column attribute applies to ListViews only, and specifies which column the listview is sorted on when the program is first loaded. If you are using a search box with your listview, then it is highly reccomended that you specify a Sort Column along with it. Otherwise, your Search Box will not be usable until the user manually sorts the Listview by clicking on the column headings.

If you want your listview to sort in Descending Order, then specify a negative number. If you want it to sort in ascending order then specify a positive number here.

For example, if you want it to sort in Descending Order on the Second Column, then specify a Sort Column of -2.

Multiselect

This check box indicates weather you want to allow multi-selection in your listview or not. If you do enable multiselection, then use mat SelectedKeys$ or mat SelectedRecords in your custom functions to see which records the user has selected from your data file.

Truth Value

The Truth Value attribute applies to Checkboxes only, and is used to translate a checked/unchecked value into the true and false values for your data files.

Everybody uses something slightly different in their data files to represent True and False. Some people use "Y" or "N". Some people use "T" and "F". Some people use 1 and 0 to represent True and False in their data files. The Truth Value specifies the value that represents True in the data file for this Check Box.

Falsehood Value

The Falsehood Value attribute applies to Checkboxes only, and is used to translate a checked/unchecked value into the true and false values for your data files.

Everybody uses something slightly different in their data files to represent True and False. Some people use "Y" or "N". Some people use "T" and "F". Some people use 1 and 0 to represent True and False in their data files. The Falsehood Value specifies the value that represents False in the data file for this Check Box.

~Ignore~ (Radio Buttons)

If you are using Radio Buttons, you'll often want to tie several buttons to a single data file. To do this, you will specify the value that you want each option to write to the disk using the Truth Value, and for the false value you want to specify "~ignore~". This will tell ScreenIO to ignore the false value, and when the user selected a new radio button, the truth value for the radio button they selected will be used as opposed to the false value for the radio button that they unselected.

Function

The Function attribute specifies the Click event for your Button or Picture control. Press the Edit button to select from your existing Custom Screen Functions, or create a new one. See the Custom Screen Function section of this document (below) for more information about Custom Screen Functions.

The Click Event selects the BR Code that gets triggered whenever the user Clicks on this picture or button.

Validation

The Validation attribute identifies the Custom Screen function that gets triggered whenever the data in the control is changed. You can use this event to ensure that only valid data gets saved in the database. If your validation event returns false (0) or a null string then the data the user entered is thrown out, and the previous value is replaced in the control.

Filter

The Filter Function applies to a Listview only, and is one of the most versatile functions in the ScreenIO System.

Your filter function gets triggered for Each Row in the data file, before it is added to the listview. You can use the Filter event to include/exclude certian records from the listview. You can also modify the data displayed in the listview before it goes to the screen.

Conversion

The conversion field specifies to ScreenIO how to treat numeric data. You can specify any valid BR field spec, or FMT, PIC or DATE here. You may also specify your own conversion function to be used when unpacking the data from the disk.

If you use DATE then it will convert the value from a julian date into the date format you specify, and when its writing it back to the disk, it will convert it back to the julian date value before saving it to the disk.

Picture File

This specifies the path and filename of the picture file to use for the picture control. All the image types supported by BR are supported here.

Foreground Color (Header FG Color)

This is the foreground color of the control. If you intend to use Attribute Substitute statements to color your controls, then you need to leave the Foreground Color and Background Colors blank, as these values will override the colors specified in your Attribute Substitute Statements.

Background Color (Header BG Color)

This is the background color of the control. If you intend to use Attribute Substitute statements to color your controls, then you need to leave the Foreground Color and Background Colors blank, as these values will override the colors specified in your Attribute Substitute Statements.

Justification Spec

This attribute specifies the BR Justifcation Attribute to use for this screen object. The default "C" is Left Justify. You can specify:

• C - Left Justify
• CC - Center Justify
• CR - Right Justify
• CU - Force Uppercase
• CL - Force Lowercase

Set Listview

The Set Listview attribute applies to Search Boxes only, and specifies the Listview that the Search Box is tied to. When the user types something in the Search Box, the Listview will automatically jump to the record they are typing, based on which column the listview is sorted on.

If you have a Search Box, but no Sort column is specified in your listview, then an Error message is displayed in your Debug Window.

When you click the "Set Listview" button, the search box is automatically tied to the listview on the screen. (At this time ScreenIO does not support more then one listview on a logical screen at a given time.) The Spec Width for the Search Box is automatically updated to match the largest column in the listview.

If you added your listview before you added your search box, then the Search Box is already tied to your Listview by default. When your search box is tied to a listview, you will see the internal name of the listview (usually "LV1") in the "Set Listview" button.

Attributes

The Attributes control attribute specifies the Control and Display Attributes to use when displaying the control. (Say that five times fast...)

You can specify any valid BR attribute, including Attribute Substitution Statements from your brconfig.sys. This enables the use of BR style themes in your ScreenIO screens.

Tooltip Text

Here you can specify the help text, if any, to be associated with the given control. You can specify your own helplevel if you know how to do so. If you do not specify your own help level, ScreenIO defaults to the most unused help level available in the version of BR you're running. This is level 1 for 4.1 and level 0 for 4.2 or higher, indicating to display the help text as tooltip text whenever the mouse is over the control.

User Data

This is a field you can use for any purpose you like. You can view and modify this field in your screen functions.

Protected

This indicates if a field is protected or not. If its protected, then it is kept automatically out of the input fields statement, keeping the user from modifying it. We do it manually because there are certian times when it doesn't work properly using the standard BR Protected attribute. However if you wish to use the Standard BR Protected Attribute, you can always specify a "P" in the Attributes field. This value, and all of these values, can be changed at runtime from any of your custom functions.

Invisible

This indicates if a field is invisible or not. If it is invisible, then it is kept off the screen entirely. This is different from BR's invisible attribute, which hides the data behind a mask of "*"s. If you wish to use the standard BR invisible attribute, you can specify an "I" in your Attributes field. This value, and all of these values, can be changed at runtime from any of your custom functions.

Save and Test Screen

Once you have finished adjusting the positions, appearance, and behavior of your screen controls, it is time to save your screen. Select "Save" from the File dropdown menu and your new screen is written to the disk, and its Autogenerated Screen Helper library is compiled for you.

You may now select "Test Screen" from the Screen menu, to test your new screen in a seperate BR process.

Conclusion

Your new Add/Edit screen contains everything necessary to Add and Edit records in the selected data file, and you didn't have to write any custom code at all.

However, most screens you write will most likely utilize custom code to achieve a nicer effect. You can use your Custom Screen Functions to do just about anything with your ScreenIO Screen. For more details about Custom Screen Functions, see the Custom Screen Function section in this document (below).

ScreenIO Custom Screen Functions

You can already see that the ScreenIO system is the fastest way to develop functioning software in the BR world. Simple Listview and FM screens can already be quite powerful, without writing a stitch of custom code. Because of the object oriented database foundation afforded to us by FileIO, we can achieve some pretty amazing results in just a few minutes of graphic design with a WYSIWYG editor.

However, I'm sure you can already think of hundreds of situations where the default ScreenIO behavior is insufficient to achieve the results expected of custom code.

Its with ScreenIO Events and Custom Screen Functions, that the power of the ScreenIO Rapid Application Development system really begins to unfold.

You can write custom events to initialize your new record, unpack a record after reading it, validate a record before saving it, and open an close your screens. You can also place code in the events for your individual controls. You can add custom code to your listview's Filter Event, or the Click events for your Buttons and Pictures, and you can have your custom code perform Validation.

Your Custom Screen Functions can modify any value in the ScreenIO System, including the Control Attributes for your individual controls. All your screen's controls can be referred to by their FileIO syntax in the mat F$ and mat F arrays that are read from your data file. Simply read or change the data in the file record (mat f$ and mat f) and it will be reflected in real time on the screen.

If you place controls on your screen and don't tie them to a field, but give them a control name instead, then they are placed in a special array called mat S$ and you can access and modify their data values there, by control name.

By writing solid clean code, you can even reuse your Custom Screen functions, making future screen development faster even for complex powerful screens.

ScreenIO Events

The screenIO system has several Events that can trigger your custom code. You will write different sorts of functions for each type of event.

Form (Screen) Level Events

ScreenIO supports eight Screen level events. These are major events triggered by the state of the screen as a whole.

Enter Event

The Enter Event is triggered when your screen first loads. You can use it to initialize Screen Global Variables, Open additional data files, Initialize values on the screen, and even load other screens that you want to appear to the user as being a part of this screen.

Initialize Event

The Initialize Event is triggered from an Add/Edit screen when you are adding a new record to the data file. This happens any time you call FnFM without specifying the key to edit. (See Using Screens above). Use the Initialize Event to initialize the data in a new record that you are adding.

It is often useful to have your Initialize Event Function call your Read Event Function.

Read Event

The Read Event is triggered upon a successful read of the data file. This happens in an Add/Edit screen any time you are loading a record to modify it.

You most often use this event to Unpack the data from the data file for Screen Display purposes. This is why you sometimes want it to happen on Initialization of new records as well as the reading of existing records.

On a listview screen, the Read Event behaves totally differently. On a listview screen, you never give a key when you call the screen, so the Read event never gets triggered when the screen is loading. Instead, on a listview screen, the Read Event is triggered any time the user changes which row is currently selected in your listview. You can use this to update reference information on the screen from the new record in the data file.

Mainloop Event

The mainloop event is an event thats triggered every time the main RINPUT FIELDS statement is executed when running your screenio screen. This means, every time anything happens, the mainloop event happens first. You can use the mainloop event to test for fkey 98 (the windows dropdown menu) and add dropdown menu support to your screenio screen.

You can also place the "X" attribute in various fields to trigger the Mainloop Event to fire whenever the user moves the cursor out of these fields, in order to update the screen in some way.

Another way to use the mainloop event is to use the config keyboard command to remap any key on the keyboard to an fkey value, and test for that fkey value, tying your own custom action to any key on the keyboard.

See Example Mainloop Function.

Wait Event

The WAIT event is triggered any time your screen has a WAIT value specified in the Window Attributes panel. This event determines the action you would like ScreenIO to take when the keyboard has been idle for some time.

Your WAIT event return value determines the action screenio takes after the main processing of your WAIT event. If your WAIT event function returns True, then ScreenIO clears the WAIT condition and continues executing the screen until another event is triggered. If your WAIT event function returns False, then the ScreenIO screen is closed with an ExitMode of Cancel, and the screen is backed out of.

If you do not specify a WAIT event function, then the default ScreenIO WAIT event code fires, and ScreenIO informs the user that their keyboard has been idle for some time, and requests that they please press a key sometime in the next 30 seconds or else they will be logged out of the current screen. If they press a key in the alotted time, they are taken back to the RINPUT FIELDS statement and allowed to continue using the screen. If not, the screen closes and logs them out, freeing up the record so someone else can use it.

Locked Record Event

The Locked Record event is triggered any time ScreenIO attempts to read a record that has been locked by another user. Your Locked Record event should tell ScreenIO what to do when a record locking error occurs in your screen.

If your Locked Record event returns True, then the read is attempted again. If it returns false, then the read is cancelled and the screen is exited.

If you do not specify a Locked Record event function, then the default ScreenIO Locked Record event code fires. The user is informed of a file sharing violation and the user name of the person who has the record locked. They are given the option to Retry or Cancel the operation. If they select Retry, the read is attempted again. if they select false, then the read is cancelled and the screen is exited.

Write Event

The Write Event happens just before your screen exits, when Save has been selected. You can use the Write event to perform last minute validation. From the Write Event, you can correct any validation problems, discard the invalid data, or cancel the ExitMode, forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.

Exit Event

The Exit Event happens when the screen exits. If you had to open reference data files in your screens "Enter" event, then the "Exit" event is a good place to close those same data files.

Control Specific Events

In addition to the Form Level events, ScreenIO provides one custom event per control. The meaning of this event is different depending on the control type. Some controls don't have any event at all.

Click Event

The Click Event is the simplest event to code for. It is triggered whenever someone clicks on a Button or a Picture. In this event, you can place any code that you want to be called when they click on the button.

See Example Click Event Function.

Validate Event

The Validate Event is triggered whenever the data in the element changes. You can use this event to discard or accept the data, display a msgbox to the user, and position the curser. If your validation routine returns non-zero and non-blank, then the value the user typed is accepted and saved. If your validation routine returns null or 0 then the value the user typed in is ignored and the previous value is retained. You can also modify the value directly by modifying the optional parameter "FieldText$" in your function.

See Example Validate Field Function.

Filter Event

The Filter function is the most versatile function. This function can be used to unpack the record data so it can be properly displayed in the listview. It can also mark records for inclusion or exclusion in the listview, and if it specifies a color, then that color is used to conditionally color the records of the data file while displaying them in the listview.

Your filter function must return true (non-zero) or something (non-empty string) for all records which are to be included in the listview. Any time your Filter Function returns False (or a null string), the record is ignored.

See Example Listview Filter Function.

Conversion Function

The Conversion Function Event is more powerful then many of the other events. It can also contain a function or a reference to a library, but in addition to those values it may contain any valid BR PIC or FMT or DATE statement that can be applied with the "CNVRT$" function.

Also, if you're using BR 4.2, the Conversion function may be used with Listview Columns to natively support numeric listview columns.

If the conversion value is DATE then ScreenIO will automatically use it to convert what the user typed in back into a natural DATE value.

You may also use the validation function to preform validation on the field. However, if you are using DATE, then remember to leave the accpted value in the DATE format so that ScreenIO can convert it back to the julian DAYS format that you will be saving on disk.

If the conversion value is PIC or FMT then ScreenIO will not attempt to convert it back, but it will still use "val" to change numeric fields back into numeric fields.

If the conversion value is a custom function, then your custom function will need to modify "FieldText$" to the appropriate value for Converting from Disk to Screen. If you then need to convert it back, you may do so through the fields Validation function.

Valid Custom Function Types

Your Custom Function can specify several different types of Event Handler. The Edit button is provided to help you manage and reuse your Custom Functions.

If you wish to enter any of the other types of Event Handlers, simply type them into the Event Textbox.

Link to another screen

To link to another screen, simply specify the Screen Name in Square Brackets:

 Function: [CUSTEDIT]
 
 or (specify a position)
 
 Function: [CUSTEDIT(2,4)]
 
 or (pass in other values)
 
 Function: [CUSTEDIT]key$=CurrentKey$

You can specify the row and column position to place the new screen using the shorthand notation specified above, placing the row and column in parenthesis inside the square brackets, after the screen name.

You can pass values into the screen you are about to call by specifying them after the name of the screen as in the example above.

You can pass Key$ and ParentKey$, Displayonly, ParentWindow, Dontredolistview, and Record.

CurrentKey$

CurrentKey$ always matches the Currently Selected Key from this current screen. If the current screen is a listview, then CurrentKey$ will always match the currently selected row of the listview. This can be used anywhere in your custom functions that you want to know the key for the currently selected or currently edited record.

By saying "Key$=CurrentKey$" in the above example, we are telling the CUSTEDIT screen to use the currently selected listview item as the key for Editing.

ThisParentKey$

ThisParentKey$ always matches the parentkey passed into the screen. In most of your custom functions you can just use "ParentKey$" to get this value. However, when calling another screen automatically, if you want to pass the current ParentKey$ into the screen you're calling, you'll need to use ThisParentKey$.

If you say "ParentKey$=ThisParentKey$" then you're telling screenio to use the ParentKey$ from this screen to set the ParentKey$ in the new child screen. This is useful when you need to pass your ParentKey$ or part of it into a child screen as the parentkey for that child screen.

Chain statement

If the first character of your function is a %, then the rest of your function is interpreted to be a chain statement.

 %menu.br

This example will chain to the BR program called "menu.br".

Any single BR command

For most events, anything else you type is interpreted as a regular BR statement and executed with the execute command.

The only exception to this is the Conversion Function. If you type anything else in the Conversion Function, then it will be interpreted as a BR Field Spec to be used with the CNVRT$ function.

You can launch a web page or a system command here, or you can modify the status of the current screen. You might have a Save button with a click event that says:

 let ExitMode=SaveAndQuit

ExitMode is the ScreenIO variable that determines when we are done processing your screen. If you set ExitMode to the constant "SaveAndQuit" then your screen will exit and save the data on its way out.

Any valid BR Field Spec (Conversion Function Only)

If you type anything in the Conversion Function thats not a library call or a custom function reference, then it will be interpreted as a BR Field Spec to be used with the CNVRT$ function. Any valid field spec, including FMT and PIC and DATE are acceptable here.

ScreenIO will use this value to convert the data as best it can both onto the screen and back onto the disk. If you are using Julian Date values on the disk, you'll probably want to specify a "DATE(" conversion function to automatically have those displayed and edited as readable dates. You can also use this for numeric formatting, and listview sorting if you put it in a listview column.

Listview numeric column sorting is only available in BR 4.2. BR 4.1 and earlier will sort the numeric fields alphabetically which does not always produce the desired results.

Link to a Custom Screen Function

To link to a Custom Screen Function, use the Edit Button. Your selected Custom Screen Function will be placed within Curly Braces {}.

 {AddNewCustomer}

More details about Custom Screen Functions follow.

Entering / Selecting your custom handler

To select the Custom Screen Function for a given ScreenIO Event, simply go to the correct place and click the "Edit" button. This button brings up the ScreenIO Select Custom Screen Function dialog.

At the top left you'll see a list of all your available Custom Screen Functions. At the bottom left is a search box, that can be used to hunt quickly through the list of Custom Screen Functions, as well as to specify the name for new Custom Screen Functions that you might create. At the right of the dialog is a multi-line text box displaying the first part of the source code for the currently selected Custom Screen Function.

You can select any Custom Function from the list and click the "Ok" button to accept it.

Link to a Library Function

You may also link directly to a library function from any of your Screen Events. To do this, type a "#" followed by the library name and the function, separated by a ":"

 #libname:fnFunctionName(parm1,parm2$,parm3)

Example: Assume your library is called "run.br" and your function is called fnRun(screenname$).

 #run:fnRun('customer')

Example 2: Assume your library is called "thing.dll" and your function is called fnDoSomething(thing$,otherthing$)

 #thing.dll:fnDoSomething(thing$,'constant')

Note: Notice the use of single quotes when passing string constants into your library functions. This is necessary at this time because of the way ScreenIO compiles your custom helper libraries.

Writing Screen Helper Functions

To create a new Custom Screen Function, enter a name into the search box at the bottom left and click the "Add New" button. ScreenIO automatically creates a new .brs file containing a blank custom screen function, and opens it in your Windows Default Editor for .BRS files. If you don't have a default editor specified yet, then select MyEDIT or some other editor capable of working with .BRS files.

You will notice that your new blank Custom Screen Function doesn't have any line numbers in it. This is important. When ScreenIO compiles all your individual Custom Screen Functions into one Autogenerated Screen Helper Library for each Screen, it has to add the line numbers itself, to make sure that none of them conflict with each other. Therefore, when you write Custom Screen Functions, it is important to remember not to use line numbers in your code.

Custom Screen Function Parameters

ScreenIO Provides several parameters automatically that you can use in your Screen Functions. If you wish to make use of a parameter, all you have to do is add it as a required parameter in your Custom Function Definition statement. ScreenIO actually checks your custom function statements to see which variables they are expecting and provides them with all the variables they ask for, as long as they are on this list:

• Function$ - The Function we are Calling
• Mat F$ - The Strings for the FileIO Record Object
• Mat F - The Numbers for the FileIO Record Object
• Mat S$ - Your Screen Record Object
• Mat Form$ - Your FileIO Forms Array
• All your Screen Information
  • Mat Screenio$ - Your Screen Header information (Strings)
  • Mat Screenio - Your Screen Lines information (Numbers)
  • mat ControlName$ - Array of the control names for all the controls on your screen.
  • mat FieldName$ - Array of the Field Names for the associated fields of all the controls on your screen.
  • mat Description$ - Array of the Descriptions or Caption Fields for all the controls on your screen.
  • mat VPosition - Array of the Verticle Position for all the controls on your screen.
  • mat HPosition - Array of the Horizontal Position for all the controls on your screen.
  • mat FieldType$ - Array of the Field Types for all the controls on your screen.
  • mat SpecWidth - Array of the Spec Widths for all the controls on your screen.
  • mat Width - Array of the Widths for all the controls on your screen.
  • mat Height - Array of the Heights for all the controls on your screen.
  • mat TrueValue$ - Array of the Truth Values for all the controls on your screen.
  • mat FalseValue$ - Array of the Falsehood Values for all the controls on your screen.
  • mat Function$ - Array of the Function triggers for all the controls on your screen.
  • mat Picture$ - Array of the Picture Files for all the controls on your screen.
  • mat Parent$ - Array of the Parent Attribute for all the controls on your screen.
  • mat FGColor$ - Array of the Foreground Colors for all the controls on your screen.
  • mat BGColor$ - Array of the Background Colors for all the controls on your screen.
  • mat Justify$ - Array of the Justification Specs for all the controls on your screen.
  • mat Attr$ - Array of the Additional Attribute Specs for all the controls on your screen.
  • mat Protected - Array of boolean flag indicating weather or not each of your controls are protected.
  • mat Invisible - Array of boolean flag indicating weather or not each of your controls are invisible.
  • mat Tooltip$ - Array of the tooltip help text for all the controls on your screen.
  • mat ConvrtIn$ - Array of the conversion values for all the controls on your screen.
  • mat ConvrtOut$ - Not currently used.
  • mat MultiSelect - Array of values indicating weather or not your Listviews have Multiselect Enabled.
  • mat Userdata$ - Array of data passed into your screen that can be used for any reason
• mat Subscripts$ - This array contains your FileIO Subscripts and your ScreenIO Subscripts and the sio_ subscripts for all your controls that are not tied to a field and are instead living inside your mat S$ array.
• Key$ - This is the Key that we called the screen with
• ExitMode - Set ExitMode to non-zero to cause your screen to exit.
• RepopulateListviews - Set this value to True in your function to cause ScreenIO to redraw the listviews when its done processing your custom function code.
• Prefix$ - Prefix for your FileIO Data File
• Currentkey$ - Currently selected key from your data file
• rec(datafile) - this is obvious, but if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
• mat SelectedKeys$ - If you have a listview with multiselect enabled, use this array to access the keys of all selected records. If Multiselect is not enabled, then this array will have only one element and it will be equivlent to CurrentKey$ above. Therefore you can use Mat SelectedKeys$ to write functions that work for both multi-select listviews and single selection listviews.
• mat SelectedRecords - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records. If Multiselect is not enabled, then this array will have only one element and it will be equivlent to rec(Datafile) above. Therefore you can use Mat SelectedRecords to write functions that work for both multi-select listviews and single selection listviews.
• mat Save_F$ - this is an automatic copy of Mat F$ that is made upon entering the screen and can be used to determine weather or not the user has changed anything sense reading or adding the record.
• mat Save_F - this is an automatic copy of Mat F that is made upon entering the screen and can be used to determine weather or not the user has changed anything sense reading or adding the record.
• mat Save_S$ - this is an automatic copy of mat S$ that is made upon entering the screen and can be used to determine weather or not the user has changed anything sense reading or adding the record.
• mat PassedData$ - this array can be used for any purpose you desire. It represents an array of data you can pass into your screen with the call to fnfm. You can query it and use it in your custom functions in whatever way you desire.
• Parentkey$ - The Parent Key that may have been passed into your screen when it was called. This is a value that you can pass into your screens that has no purpose except to be used in your screen functions. You can use it to filter your listview to show only records for the current Customer or whatver ParentKey makes sense to you.
• LockUser$ - This value is only available in the Record Locked event. It will tell you the user name of the user who has the record locked.
• Datafile - This is the file number of the data file
• Window - This is the window number of the screenio screen
• FileIO Subscripts - All your fileio subscripts are set for you so you may use your file just as if you'd opened it yourself.
• ScreenIO Subscripts - Any of your screen controls that belong in MAT S$ have a screen subscript that you can use to access them.
• ScreenIO Control Subscripts - Every Control on your screen with a control name has a subscript that can be used to access its properties in the Screen Control Arrays above. For example, if you have a text box named "Customer" and you want to make it invisible in one of your custom helper functions, then give the command: "let Invisible(ctl_customer)=1"
• CurrentRow - this variable contains and controls the currently selected listview element. You can use it to determine which listview item is currently selected, and if you change this value it will change the current row in the listview. You can use this value to control the cursor on a listview screen.
• Currentfield - This is the CurFld Value of the field which the cursor is in. If you change it, it will move the cursor around.
• Currentfield$ - This is Control Name of the Control for the field which the cursor is in. You can move the cursor by setting CurrentField$ to the ControlName$ of the field you want to move it to. This is case insensitive. If you change both CurrentField$ and CurrentField, the CurrentField$ change takes precedence.
• Only Available in Validate and Conversion Functions - these next parameters are only available in Validate and Conversion functions. Most of them are read only (any changes to them will be ignored) and they should be used to make your custom Validation and Conversion functions reusable:
  • Fieldtext$ - This is the text in the field being validated/converted.
  • Fieldindex (read only) - This is the CurFld value of the field being validated/converted. You could use this to put the cursor in the bad field by saying "CurrentField=FieldIndex".
  • ControlIndex (read only) - This is the index (matches ctl_controlname) of the Control for the field being validated/converted. You can use this anywhere that you can use ctl_controlname, for example to access the Attributes arrays of the control. For example, you can make the control invisible by saying "Invisible(ControlIndex)=1".

Accessing Control Properties from within your Helper Functions

If you wish to access any of your controls' attributes from a custom helper function, you first have to define the control by giving it a ControlName in the Control Attributes Window. Then, all you have to do is reference the array of the attribute you're looking for, with the control name for a subscript, prefixed by "ctl_". For example, to make the customer control invisible, simply type:

 let Invisible(ctl_customer)=1

#Include Statement

Sometimes it is necessary to reference one of your custom helper functions from another one. But when you do, you need a way to ensure that its always included in any screens that call the first custom helper function. The way to do that is with the #Include statement. You use this statement in a comment, so that BR will ignore it. Simply say:

 ! #Include {functionname}

in a comment somewhere in your program and the specified custom helper function will be included. The "{}"s are mandatory and are part of the syntax for specifying a Custom Helper Function anywhere in ScreenIO.

Examples

Validate Field Function

NOTE: ScreenIO has this functionality built in now, so you shouldn't need to validate your dates this way. Its only included here as an example for how a validate function works.

For more information on the proper way to work with dates in ScreenIO, see the Conversion Function section.

 ! function\validatedate.brs
 !
 ! Created on 01/12/2009
 !
 ! This function would be placed in every field in the SageLive system that accepts a date.
 ! 
 !
 def fnvalidatedate(&fieldtext$;___,DateValue)  
    let DateValue=days(fieldtext$,"mm/dd/ccyy") conv BadDateEntered
 
    let fieldtext$=date$(DateValue,"m/d/ccyy")
    let fnvalidatedate=1 ! Date Save Successful  
 
    BadDateEntered: ! a bad date was entered. Return False so that ScreenIO Places the old value back.
 fnend

Listview Filter Function

 ! function\filtertasks.brs
 ! Created on 04/17/2009
 !
 ! fnFilterTasks - This Function Filters the Tasks List to show only
 !  tasks for the Current Employee that are not completed or cancelled. 
 !  It also colors the tasks, and sets the task_status Listview Column.
 !
 ! This function is the filter event for the Todo List listview in the SageLive System
 !
 dim CurrentEmployee$
 
 def fnFilterTasks$(mat f$,mat f,ParentKey$,prefix$,mat Subscripts$,mat S$)
    
    if CurrentEmployee$="" then
       library "timelib" : fnCurrentEmployee$
       let CurrentEmployee$=fnCurrentEmployee$
    end if
    if uprc$(ParentKey$(1:7))="SHOWALL" then
       if f$(todo_employee)=CurrentEmployee$ then
          let fnFilterTasks$="/#00FF00:#000000"
       else
          let fnFilterTasks$="/#0000FF:#000000"
       end if
    else if f$(todo_employee)=CurrentEmployee$ and f(todo_cancel)=0 and f(todo_complete)=0 then
       let fnFilterTasks$="/#33CC66:#000000"
       if sio_taskstatus then let s$(sio_taskstatus)="X" ! Open
    else if f$(todo_employee)=CurrentEmployee$ and f(todo_cancel)=0 and f(todo_complete)=days(date$) then
       let fnFilterTasks$="/#6699FF:#000000"
       if sio_taskstatus then let s$(sio_taskstatus)="Y" ! Completed
    else if f$(todo_employee)=CurrentEmployee$ and f(todo_cancel)=days(date$) and f(todo_complete)=0 then
       let fnFilterTasks$="/#AA0000:#000000"
       if sio_taskstatus then let s$(sio_taskstatus)="Z" ! Cancelled
    end if
 fnend

Click Event Function

 ! function\quickinvoiceacustomer.brs
 ! Created on 03/30/2009
 !
 ! fnQuickInvoiceACustomer - This Function automatically creates an invoice
 !  for a customer.
 !
 ! This function is placed in the Click Event for the "Invoice Customer" button on the
 !  Customer Listview Screen in the SageLive system.
 !
 ! It operates on the currently selected item in the listview by using the
 !  value of CurrentKey$
 ! 
 ! Most of the actual processing takes place in various libraries that are part
 !  of the SageLive system.
   
 dim Invoice$(1)*255,Invoice(1)
 
 def fnQuickInvoiceACustomer(CurrentKey$,DataFile,mat Form$)
    library "invclib" : fnBuildInvoiceHeader,fnAddCustomerToInvoice,fnImportCustomer, fnPrintInvoiceByData
 
    let Invoice=fnOpen("invoice",mat Invoice$,mat Invoice,mat Form$)
 
    let fnBuildInvoiceHeader(Invoice,mat Invoice$,mat Invoice)
    let fnAddCustomerToInvoice(CurrentKey$,mat Invoice$,mat Invoice,DataFile,mat form$)
    let fnImportCustomer(CurrentKey$,Invoice$(ih_id))
    let fnPrintInvoiceByData(mat Invoice$,mat Invoice,1)
 
    write #Invoice, using form$(Invoice) : mat Invoice$, mat Invoice
    let fnCloseFile(Invoice,"invoice")
 
    let fnfm('INVCEDIT',Invoice$(ih_id))
 fnend

The first function called, fnBuildInvoiceHeader, populates the Invoice Header information with the current date and the next available invoice number, etc.

The next two functions, fnAddCustomerToInvoice and fnImportCustomer add the customer to the invoice, automatically searching the database for any billable work that has been completed, and adding it to the invoice. They also mark the timelog records as "Billed", and mark the invoice number in the timelog record showing which invoice each timelog entry ended up on. At the same time, they populate the Invoice Header record with important information such as Billing Address, Shipping Information, Payment Terms, etc.

The next function, fnPrintInvoiceByData generates the invoice as a PDF file. It automatically detects if we're running BR 4.2 or 4.1. If we're running BR 4.1, then it generates the PDF file using the CutePDF Printer Driver and a short AutoIt Script. If its BR 4.2, then it uses the built in PDF generation ability. The optional parameter 1 at the end specifies to generate the PDF file. The same function could be used to print the invoice on a standard printer using Print Preview and the windows Printer selection dialog.

After that we write the new invoice to the database, and the file is closed.

Finally, the Edit Invoice screen is called, and the new invoice is displayed to be reviewed and emailed to the customer.

When the user is finished looking at the invoice, we return to what we were doing in the customer screen.

Mainloop Function

Now lets take a look at how to use the Mainloop Function to respond to various keys.

 ! function\tabsmainloop.brs
 ! Created on 02/21/2010
 !
 ! fnTabsMainloop - This Function This Function updates the Current Potential
 !  elements of the Screen (if they exist)
 !
 ! This function appears in many of the SageLive screens, to enable the Windows Dropdown Menu.
 !  it also does a few other things for some of the screens it sits in.
 !
 ! #Include {executetask}
 ! #Include {tabwindowsmenu}
 
   def fnTabsMainloop
      if fkey=98 then let fnProcessWindowsMenu  ! Fkey 98 is Windows Menu Click
      if fkey=0 or fkey=201 then let fnSelect   ! Fkey 0 is Enter and Fkey 201 is Double Click
 
      if sio_current_potential or sio_current_week_now or sio_current_week_poten then let fnUpdateCurrentPotential
   fnend
  
   def fnSelect
      if lwrc$(screenio$(si_screencode))="tabwork" then
         let fnfm("projedit",CurrentKey$)
      else if lwrc$(screenio$(si_screencode))="tabtodo" then
         if todo_function and len(trim$(f$(todo_function))) then
            let fnExecuteTask
         else
            let fnfm("taskedit",CurrentKey$)
         end if
      else if lwrc$(screenio$(si_screencode))="tabincome" then
         let fnfm("invcedit",CurrentKey$)
      else if lwrc$(screenio$(si_screencode))="tabexpense" then
         let fnfm("expnedit",CurrentKey$)
      else if lwrc$(screenio$(si_screencode))="tabcustomer" then
         let fnfm("custedit",CurrentKey$)
      end if
      if fkey<>93 then let fkey(-1) ! Reset Fkey after whatever they've done except Windows X
      let Function=-1
      let ExitMode=0 ! Don't exit after procesing Enter Key
   fnend

The fnTabsMainLoop function is used here to check for various special function keys that we want to do something special for, as well as to do any processing that we wish to run as often as possible.

The first thing it does is test for and respond to a Windows Dropdown Menu click (fkey 98). If a selection is made from the Windows Dropdown Menu, the SageLive Windows Menu handler is called. This Windows Menu Handler function resides in another Custom Function which we include using the #Include screenio command. This command is used any time one of your custom functions depends on another custom function.

After that we check for the Enter Key (fkey 0) or a Double Click (fkey 201). The default action in ScreenIO for the enter key, is to select the current item from the list and return it to the calling code, exiting the screen. But for many of the listveiws in the SageLive system, we wanted to do something different. In many cases we wanted to view or edit the item selected, and in one case, the SageLive Todo List, we wanted to do something really special.

We're testing for fkey 201 because I also want double clicking on a listview item to preform our special "Selection" routine.

Because this function is used in many different screens, and they each display different information and require a different action, I chose to place the code that handles the event inside another function, fnSelect.

FnSelect tests the value of the ScreenCode in mat ScreenIO$ to see which screen we're in, and handles the click accordingly. For example, if we're on the Customer screen, then double clicking launches the Customer Edit screen, displaying the current customer record. If we're on the Expense Screen, then we want to launch the Expense Edit screen to view or edit the Expense Record.

The SageLive Todo List contains one special feature. Todo List Items can have code in them, a function that gets executed automatically to help with the task. For example, the automatic task that comes up each month to remind me to enter the electric bill has code in it that helps me enter the electric bill as an expense into the system.

When I run that task, SageLive automatically launches my electric bills website for me, right at the login prompt. Then it waits with an autoit script for me to print the latest bill from their webpage. I select "Print Bill" from the electric companies website, and the bill is snatched right from the print stream and uploaded into SageLive. I read and enter the amount on the bill, and the rest is done for me.

Here you see where we call the ExecuteTask function responsible for that piece of magic, whenever an item is selected on the SageLive Todo List. If the Task we selected has code in it, then we run the code, executing the task. If it does not have code in it, then we simply launch the Task View screen where the text in the Todo List item can be read in a multi-line text box.

At the end of the fnSelect Routine is code to reset the fkey value and to cancel the default action for the Enter key (which is to select and quit). Fkey 93 is the Windows X, and in ScreenIO it means to exit every screen that we're in (prompting to save any changes) and if your original calling program that launched the first screen responds to it properly, close BR. So we want to leave fkey 93 alone but cancel any other fkey values that might have come back from the screen we jumped into.

After handling the special keys, our fnTabsMainLoop function handles the fnUpdateCurrentPotential. Some of the screens in the SageLive system have a little place where they show the Current Employee's Current Potential Earnings. This function is called from lots of screens and only a few of those have the Current Potential Display, so the first thing we do is test to see if the screen we're currently in has the Current Potential fields on it.

The Current Potential Fields is a calculated approximation of how much money the Current Employee has earned so far today, and how much money they can potentially earn if they continue to work until 6pm.

It was intended to be a motivational tool, but its mentioned here as an example of a situation where you might want to update some data on the screen as often as possible. Because the Current Earnings are always going up whenever the employee is currently logged in on a project, and the Potential Earnings are always going down whenever the employee is not logged in on a project, we want to try to update it as often as we can.

The mainloop is called every single time ScreenIO gets control and the RINPUT FIELDS statement ends. The Screens with Current Potential fields are all listview screens with the X attribute specified for the listview, making it so that any time the user scrolls around the list, presses the fkey, clicks on any button or does just about anything at all, the Current Potential is updated. You can even use this in combination with the Wait Time value to force a regular update of the screen.

ScreenIO Built In functions

ScreenIO has a built in function for use in your events.

FnFindSubscript

FnFindSubscript(mat Subscripts$,Prefix$,String$) This function searches through the array mat Subscripts$ looking for the subscript that matches the given Prefix$ and Subname$. It returns the index of this subscript.

Use this function to programmatically interrogate mat Subscripts$ from your Custom Functions in order to help make them more reusable.

Mat S$

Lets go over a couple of ScreenIO Concepts one more time.

Most of the controls on the screen are tied directly to a field in the data file. In your Custom Validation Functions, you can refer to that data by its FileIO Name.

 let msgbox("Customer Name is "&f$(cu_Name))

The value in your mat F$ and mat F is the same as the value on the screen. It is the value of the disk record in memory. When the record is saved, mat F$ and mat F are rewritten back to the data file.

However, any of your controls that are NOT tied to a data file, (but still have a control name) get placed in another array: Mat S$

A Control is tied to the data file if it has a value for its FieldName. Mat S$ contains the data for all the controls that have no value for "FieldName" but do have a value for "ControlName".

You can access them the data in Mat S$ by giving the screenIO subscript for the control, which is sio_ControlName where ControlName is the actual name of your control.

 read #CustomerFile, using form$(CustomerFile), key=f$(ih_customer) : mat Customer$, mat Customer
 let S$(sio_CustomerName)=Customer$(cu_FirstName)&" "&Customer$(cu_LastName)

You can use this feature to have additional input fields that the end user is able to interact with that don't necessarily correspond directly with a field in the data file. Your Custom Functions can react to the mat S$ fields and they can also update the Mat S$ fields.

You can use a Mat S$ field to set the picture file for a picture control, to something that is calculated in a Custom Function at runtime.

ExitMode

One common thing you might do in a custom function, or directly in one of your controls Function properties is set ExitMode. ExitMode is a variable you can change with your custom functions. It governs when your screen is finished executing.

ExitMode can have the following values:

• ExitMode=0 .... When ExitMode is 0 the screen keeps running. You can cancel an ExitMode by setting it back to 0.
• ExitMode=SaveAndQuit .... When ExitMode is SaveAndQuit then the screen stops running and the data is saved and the key of the new record is returned. Use this on an Add/Edit Screen.
• ExitMode=SelectAndQuit .... When ExitMode is SelectAndQuit then the screen stops running and the key of the currently selected listview item is returned. Use this on a Listview Screen.
• ExitMode=QuitOnly .... When ExitMode is QuitOnly the screen stops running and the users data is not saved, and nothing is returned.
• ExitMode=QuitOther .... QuitOther works the same as SelectAndQuit. You can use it if you need to implement your own custom Exit logic.
• ExitMode=AskSaveAndQuit .... AskSaveAndQuit will check to see if the user has changed anything. If they have, it will ask the user if they'd like to Save or just Quit, and behave accordingly. If the user hasn't changed anything, it will just quit.

To set ExitMode in one of your functions, simply assign it a value from the list above.

ScreenIO ExitMode Constants

SaveAndQuit, SelectAndQuit and all the other values above are ScreenIO ExitMode Constants. The ScreenIO ExitMode Constants are set for you in your custom helper library in order to help facilitate the readability of your ScreenIO Code. The values are set with code such as the following, and even inside ScreenIO they're tested for by name.

 let Quitonly=1
 let Saveandquit=2
 let Selectandquit=3
 let Quitother=4
 let Asksaveandquit=5

Working with the ScreenIO Loading Icon

ScreenIO comes with an Animated Loading Icon that automatically appears whenever a listview takes a long time to load. This tells the user that something is happening, so they know its not just hung.

You don't have to do anything to your screens to use the loading animation. It automatically happens whenever a listview takes more then a couple seconds to load.

Changing the Loading Icon

ScreenIO comes with two different animtated loading icons: A Modern Clock and a Grandfather Clock.

If you look in the "clocks" folder that came with ScreenIO, you'll see three folders: "clock", "grandfather clock" and "kitchen clock". ScreenIO ignores all the other folders, and only looks inside the "clock" folder.

To change which clock you want to use, simply delete the contents of the "clock" folder and replace them with the contents of the one of the other folders, the one containing the clock of your choice.

Making your own clock animations

Its very simple to make your own clock animations. All you have to do is place a bunch of image files in a folder, depicting the different steps of the animation. They can be either jpg's or gif's. You can have as many files as you want, and they can be any resolution you want, but keep in mind that large animations may run slow in network or internet environments. If you intend to run your software over a network share, or over Client Server, you may wish to stick to reasonably sized files. You can get plenty of detail for a loading animation out of a 2k image file.

Gif files are particularly nice to work with because they support transparency, so your loading clock doesn't have to be square.

ScreenIO reads all the images in the clocks\clock folder and sorts them alphabetically, then plays them in a loop. The timing and size and color of the animation window is controlled via the clock.ini settings file.

The clock.ini settings file

In your clock folders, you'll see a clock.ini settings file. Its a very short csv file containing five fields in order. All of the fields are optional. The Clock.ini file itself is optional, in fact. If the file is not found, or any of the values are missing, then default values are used.

The five parameters, and their default values are as follows:

1. ) Animation Speed (.5) - This is the Animation Speed, in seconds of delay. The default value will update the animation every half second. Use a lower value for a smoother animation, but be careful, if you use too low of a value you can slow down the processing of the listview. This number should be specific to the animation you're using. If your frames are very different from each other you'll want a high value like .5 or .6. If the frames are only changed slightly from each other, and you have a lot of them, then you might want the animation to play faster, like .1 or .2. An animation speed of 0 will force it to update as often as possible, which is one frame each time another chunk of data is sent to the listview.
2. ) Rows (5) - The size of the animation window in Rows.
3. ) Cols (10) - The size of the animation window in Columns.
4. ) Color$ (inherited) - The BR color for the animation window. If present, this parameter is what goes in the "N=" part of the open statement. The default of none causes BR to use the default or inherited colors for the animation window.
5. ) Border$ (no border) - The BR border string for the animation window. This can be used to add or color a BR border.

Submitting your clock animations

If you've made a nice clock, and you'd like to submit it to be included in future releases of ScreenIO, please zip the entire clocks folder and email it to me at gabriel.bakker@gmail.com. I welcome and encourage your submissions, and I look forward to seeing the beautiful loading clocks that you come up with.

Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)

When using ScreenIO, there are several ways to control the designer with the keyboard. Almost any function can be accessed from the Windows Dropdown Menu, which you can get to from the keyboard by using the Alt key in combination with the underlined letters in the Menu, and with the arrow keys.

You can also use following keyboard shortcuts any time in the ScreenIO Designer.

 Ctrl-V .. Paste Controls
 Ctrl-X .. Cut Controls
 Ctrl-C .. Copy Controls
 Alt-Z ... Undo
 Alt-R ... Redo

You can use standard keys for Copy, Cut, and Paste in screenio. Copy and Cut act on the current controls and copy them to the clipboard. They are copied to the clipboard in plain text, so its possible to paste them in notepad and then later select them and copy and paste them back into another ScreenIO screen. You can use the clipboard the same way you would expect to use it in any windows program.

Alt-Z and Alt-R Undo and Redo the last operations. You can use them any time in ScreenIO. The only reason its not the standard Ctrl-Z and Ctrl-R is because BR reacts better to Alt-Z and Alt-R.

Screen Control Movement Mode

The following controls work in Control Movement Mode Only

 Lf ...... Move the control left
 Rt ...... Move the control to the right
 Up ...... Move the control up
 Dn ...... Move the control down
 Space ... Make the control Wider
 BkSp .... Make the control narrower
 PgDn .... Make the control taller
 PgUp .... Make the control shorter
 Enter ... Cycle through the Control Attributes and Movement Mode
 Del ..... Delete the selected control from the screen
 Ctrl-S .. Toggle Selection for current control
 Ctrl-T .. Select All Textboxes
 Esc ..... Unselect all or exit the current control
 Ctrl-E .. Make all Left Edges of selected controls match the current control
 Ctrl-R .. Make all Right Edges of Selected Controls match the current control
 Ctrl-W .. Make all Widths of selected controls match the current control

Selecting Multiple Controls

You can use CTRL-S to toggle the selection of the current control, turning it Green, building a group of selected controls. Once you have a bunch of controls selected you can change their attributes or position as a group, instead of having to work with them one at a time.

To select a group of controls, simply click on the controls you want to select one at a time, and press CTRL-S between each click to select them.

The easiest way to learn about control grouping is to try it out. Save your screen and experiment with selecting several controls to see what happens.

The current control will always appear in yellow, and all the controls in the currently selected group will appear in green.

If you move any control, the other selected controls will move with you. You can retain the selection outside of control movement mode but you must be in control movement mode in order to change the selection. Outside of control movement mode the only effects that are shared with the group Copy and Cut, and changing properties. If you change any control properties while there is a selected control group, then a message box will appear asking if you would like to copy the changes to all selected controls in the group.

You can also move controls around the screen with the mouse. For more information on Mouse Movement, see the chapter on Mouse Movement.

Update Process

If you used an older version of ScreenIO and updated it to a newer version and you recieved a message from ScreenIO saying that it needs to recompile your helper libraries and update your folder structure, thats because we have recently moved all your ScreenIO Helper Libraries into their own subdirectory, in order to keep from cluttering up your main installation directory as much as possible.

If you do not get this message when updating, don't worry about it. Chances are you were already running with a newer version of ScreenIO. But if you do get this message, then here is a little more information about what it is and what it means.

Your ScreenIO Helper Libraries have been moved into a new folder called 'screenio\'. If you referenced any of these files in your existing code, you may need to update those references. We have generated this brconfig file of substitution statements to aid in this process. To use it simply add 'include screenio\screenio.sys' to your brconfig.sys file.

WARNING: If any of the following substitution statements conflict with one of your file names you will not be able to use them. Carefully inspect these files to ensure they do not conflict with the names of any of your data files. If they do, you will not be able to use the substitution statements because they will affect your data files as well as your program name references. You will have to remove those lines from this file before using this file, and manually fix all the references in your existing code to any programs who's names conflict with your data files.

If you have any questions about this process, contact Gabriel Bakker at gabriel.bakker@gmail.com.

Future Changes

A partial list of future changes for ScreenIO has been added here. If any of you have a feature in mind that you'd like to see and its not already listed here, feel free to add it. I will remove the features from the list as they are implemented in ScreenIO.

New Future Change Requests

All currently requested features have been implemented. If you have a feature in mind you'd like to see, feel free to post it here, and also please notify gabriel.bakker@gmail.com. When I have finished implementing the feature, i'll remove it from the list that you make here.

• Add your Feature
• Requests Here

Completed Future Change Requests

The following list of change requests has been completed.

• Additional Parameters in fnfm for Interacting with Screens, that get passed both in and out of your new screen.
• Non-Data Screens - the ability to call fnfm with your own mat F$ and mat F and have it work with your passed in data instead of automatically reading and writing from your data file.
• True Numeric Fields in Listviews supported with BR 4.2
• Numeric Fields on regular Text Box Controls
• Mainloop event to support custom keys
• Error Handling Improvement
• Animated "Loading Icon" for populating Large Listviews
• Group Movement/Alignment of controls
• Copy and Paste of Controls from one screen to another screen
• Group Copy and Paste of Controls
• ScreenIO Helper Libraries in a special folder
• ScreenIO itself in a special folder
• Add the "-d" option to the ScreenIO Screenfld file to keep it from growing huge after some time
• Additional Field level Properties in Screenflds for Programmers to use for things
• Support for TIMEOUT and WAIT in BR - Perhaps these should be events as well
• Advanced Filtering of a Listview - using the proper index to make it run faster