BR Wiki - User contributions [en]

Main Page

2026-02-13T15:36:43Z

Laura: fixed forum link

{| cellspacing="12" cellpadding="15" border="0" align="center"
|-
| [[File:Business_Rules_Corp_Logo.png]]
|}

Welcome to the '''{{SITENAME}}'''. This wiki is dedicated to the '''[[Business Rules!]]''' programming language (a.k.a. BR) and the software developers who use it. Business Rules is formerly known as Workstation Basic. Currently containing [[Special:Statistics|{{NUMBEROFARTICLES}}]] articles, this growing wiki is a great place to find information about the Business Rules! programming language. Our goal is to provide Business Rules! developers a convenient source of reference as well as an easy-to-use platform for documentation development.

We encourage members of the '''[https://brulescorp.com/brforum.live/ Business Rules! community]''' to contribute their own knowledge to the Wiki by messaging an editor. A list of editors can be found ''[http://brwiki2.brulescorp.com/index.php?title=Special:ListUsers&group=editor here]''. '''New user registration''' is also performed by editors upon request. Registered users can create discussion pages and send email to other users.

This entire site can be viewed by guests (no login required), while editing content is restricted to the [http://brwiki2.brulescorp.com/index.php?title=Special:ListUsers&group=editor editors group]. Contact ''support@brulescorp.com'' if you wish to become an editor, or wish to know more about the [http://brforum.brulescorp.com Business Rules! community].

If you come here often, you may be interested in just [[Special:Newpages|new pages]] or [[Special:Recentchanges|recent changes]].

== For New Users ==

*[http://meta.wikimedia.org/wiki/Help:Contents Help Using the Wiki]
*[[Special:Userlogin|Register]]
*[[BR Tutorial]]
*[http://brforum.brulescorp.com BR Forum]

== Main Links ==

*[[Business Rules!|Introduction]]
*[[BR Reference]]
*[[Backward Compatibility]]
*[[:Category:Utilities Third Party|Utilities Third Party]]
*[http://www.brulescorp.com/brules/download.html#BRUTILITIES Old BR Utilities]
*[[Export|Exporting the Wiki]]
*[[Common Categories]]

== Categories ==

Most of this wiki is categorized. An individual article may belong to multiple categories. The [[Special:Uncategorizedcategories|Top Level Categories]] are a nice way to browse this wiki. In the table below are the most popular categories.

{| width="50%" cellspacing="2" cellpadding="5" border="1" align="center"
|-
| '''[[:Category:Basics|The Basics]]'''
*[[:Category:Variable|Variables]]
*[[:Category:Operations|Operations]]
*[[:Category:Arrays|Arrays]]
*[[:Category:Control_Structures|Control Structures]]
*[[:Category:External_Editors|External Editors]]
*[[:Category:User_Defined_Functions_and_Libraries|User Defined Functions / Libraries]]
| '''[[:Category:GUI|GUI]]'''
* [[:Category:Widget|Widgets]]
| '''[[:Category:Release Notes|Release Notes]]'''
|-
| '''[[:Category:Commands|Commands]]'''
| '''[[:Category:Statements|Statements]]'''
| '''[[:Category:Internal Functions|Internal Functions]]'''
|-
| '''[[:Category:Config|Config (Configuration and Environmental Settings)]]
| '''[[:Category:Terminology|Terminology]]'''
| '''[[:Category:Error|Error]]'''
*[[:Category:Error|Error Handling]]
*[[:Category:Error Codes|Error Codes]]
|-
| '''[[:Category:Files|Files]]'''
*[[:Category:File_Operations|File Operations]]
*[[:Category:Sorting_and_Indexing|Sorting and Indexing]]
| [[BR Tutorial]]s
| ...
|-
| '''[[:Category:Printing|Printing]]'''
| '''[[:Category:Ftp.brulescorp.com|ftp.brulescorp.com]]'''
| '''[[:Category:Utilities Third Party|Utilities Third Party]]'''
|-
| '''[[:Category:Procedure Commands|Procedures]]'''
| '''[[:Category:Client Server|Client Server]]'''
| ...
*[[:Category:Field Specifications|Field Specifications]]
*[[:Category:Definitions|Definitions]]
*[[:Category:Properties_Events_and_Methods|Properties, Events and Methods]]
*[[:Category:HTTP|HTTP]]
|}

==Other Business Rules! Pages on External Links==
Here are a few places to find other Business Rules! related pages maintained by others. These are not official pages maintained by [Business Rules Corp].

*[http://www.sageax.com/ Sage AX's BR page]
*[http://br32.com/ BR32.com]
*[http://www.luisgomez.net/br/ Luis Gomez's BR page]
*[http://planetacs.net/br/ Advanced Computer Services LLC's Business Rules! page]
*[http://planetacs.net/br/npp/index.html Advanced Computer Services LLC's Notepad++ for Business Rules! page]

==Common Category Trees==

[[Common Categories]]

ScreenIO Library

2019-11-19T21:22:07Z

Laura: /* Radio Button */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#Useful ScreenIO Functions|Useful ScreenIO Functions]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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.

*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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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 also 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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0
setting_load_filter=0
setting_functionsel_filter=1

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

===Load Filter===

Controls weather there should be a filter box or a search box on the "Load Screen" dialog (2.3).

===setting_functionsel_filter===

Controls weather there is a filter box or a search box on the the "Function Select" dialog screen.

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.

If you're using color attributes, use N=, for example when [BackgroundColor] is set in a config attributes file, use N=[BackgroundColor].

====== 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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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~" (but no quotes). This will instruct ScreenIO to ignore the falsevalue, saving the truevalue from the currently selected radio button.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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. Fieldtext$ refers to the field that changed and is being validated.

===== 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.

Implement Read and Return keys in the Window Attribute Section because a 0 Read Key will default to a Relative Read.

===== 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.

====== Special ScreenIO Date processing ======
If you use DATE then it will convert the value from its format on disk, into the date format you specify, and when its writing it back to the disk, it will convert it back to its format on disk, before writing it. This works in conjunction with the new [[#Support_for_New_Fileio_Dates|FileIO Date]] features, to allow you to specify the DATE format on disk for Date Fields.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

This also works in listviews to display the dates in any format you want, while still making sure they're numerically sortable.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

As of ScreenIO v91, with the introduction of fnInit_ and fnFinal_ functions, listview Preopulate is no longer the preferred method.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|Listview Filter Function]].

====== fnInit_ and fnFinal_ ======
''Added in ScreenIO v91''

fnInit_ and fnFinal_ are new custom functions for Priming and Clearing your listview, that are better to use then [[#Listview_Prepopulate|Listview Pre/Post Populate]], and that exist along side your filter function, in the same file.

fnInit_ is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_ is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Postpopulate|Listview Postpopulate]]).

The name of the fnInit_ and fnFinal_ functions are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters. fnFilterList$ becomes fnInit_FilterList and fnFinal_FilterList. fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new [[#Filter_Event|Filter Function]] in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

Because the Listview Pre and Post populate functions are almost exclusively used for things that have to do with the filter function, it is easier and more organized to keep the code together in one place.

See [[#Listview_Filter_Function|Example]].

====== 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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''Prefix$''' - Prefix for your FileIO Data File
*'''Currentkey$''' - Currently selected key from your data file
*'''rec(datafile)''' - if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
*'''[[#Working_with_Listviews|mat SelectedKeys$]]''' - If you have a listview with multiselect enabled, use this array to access the keys of all selected records.
*'''[[#Working_with_Listviews|mat SelectedRecords]]''' - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records.
*'''[[#Working_with_Listviews|mat VisibleKeys$]]''' - All the keys that are currently visible in the listview. (v91,Requires BR 4.3+)
*'''[[#Working_with_Listviews|mat VisibleRecords]]''' - All the records that are currently visible in the listview (v91,Requires BR 4.3+)
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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.

===== Prewritten Functions =====
ScreenIO includes a few useful functions for working with listviews and other common operations, right out of the box. Most of them are pretty self explanatory, and include a comment right at the top of the function explaining what it does and how to use it. I'll mention a couple of them here.

*'''deletelistviewrecord''' - Displays a confirmation dialog, and then deletes the currently selected record in a listview.
*'''deleterecord''' - Displays a confirmation dialog, and then deletes the current record in an add/edit screen.
*'''enforcerecord1''' - Use this as your enter event of an add/edit screen to force the screen to edit only record 1 of a data file, for example in a system configuration file that has only 1 record.
*'''enterselectionlistview, filterselection, and toggleselection''' - These three functions work together to make listview screens where the user can toggle on and off a selection of them.
*'''listviewcombo[...]''' - The functions that start with listviewcombo are used for making combination listview/add edit screens (Experimental feature) and are used automatically by the screen generator when you generate one.
*'''pause''' - assign this function to a button in your screen in order to pause your screen in the memory space of your custom helper library in order to debug things.
*'''printlistview''' - This powerful function calls George Tisdales function to print the current listview, including current sorts and filters, to the printer. It requires George Tisdale's rtflib to be installed in a vol002 folder in your app. It can be downloaded from the Sage AX Website here: [[http://www.sageax.com/downloads/vol002.zip]].
*'''exportlistviewcsv''' - This powerful function calls Laura Smiths fileio function to export everything in the current listview to a CSV and open it in the default editor (example excel).
*'''exportcurrentfilecsv''' - This export function calls the fileio Export to CSV function on the given file, for whichever columns the user wants from the file (there's a column selection dialog), and it exports just the specific rows that are currently visible in the currently filtered and sorted listview. '''''Note: '''If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.''

====== ======

===== 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|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$)
mat Employee$=("") : mat Employee=(0)

read #Employee, using form$(Employee), key=f$(todo_employee) : mat Employee$, mat Employee nokey Ignore
let s$(sio_EmployeeName)=Employee$(em_name)

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

dim Employee$(1)*1023,Employee(1),Employee

def fnInit_FilterTasks
let Employee=fnOpen("employee",mat Employee$,mat Employee,mat Form$,1)
fnend
def fnFinal_FilterTasks
Close #Employee:
fnend

fnInit_FilterTasks is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_FilterTasks is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Prepopulate|Listview Postpopulate]]).

The name of the [[#fnInit_and_fnFinal|fnInit_ and fnFinal_ functions]] are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters, so fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new Filter Function in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

These are the preferred method for populating listviews. They're better then [[#Listview_Prepopulate|Listview Prepopulate]] and [[#Listview_Prepopulate|Listview Postpopulate]]. However, [[#Listview_Prepopulate|Listview Pre/Post Populate]] will continue to work, for compatibility with existing programs.

fnInit_ and fnFilter_ were added in ScreenIO v91.

====== 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 several [[#Functions_to_use_in_your_ScreenIO_Functions|built in functions]] for use in your events.

===== 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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Working with Listviews =====
ScreenIO does a number of things to make writing custom functions to work with listviews easier. The currently selected record in the listview is always in mat F$ and mat F, and the primary key of that record is in CurrentKey$. You can use the standard BR system function rec(DataFile) to determine the current record of the data file.

You can also use mat SelectedRecords and mat SelectedKeys$ to determine which row(s) are currently selected by the end user. This makes it a lot easier to work with multi-select listviews. And even if a listview does not allow multi-select, these arrays still work. They contain a single element and it points to the currently selected single row - the same thing you would find in CurrentKey$ and rec(Datafile). That makes it easy to create functions that work both for multi-select and non-multi-select listviews.

BR 4.3 introduced Filter boxes. In BR 4.3 you can use mat VisibleRecords and mat VisibleKeys$, to see which records are currently displayed. They'll contain every row if the listview hasn't been filtered or sorted. But if the user has filtered or sorted the listview, by clicking on the column headings or typing something into a filter box, then these arrays will contain only the rows that are currently visible on the list, and in what order.

=== 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.

However, if you like, you can use these animations in your own programs, by calling the [[#Animations|ScreenIO Animation Functions]].

==== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

=== Support for New Fileio Dates ===

ScreenIO Supports the [[FileIO_Library#Support_for_Dates|FileIO Date features]] and if a field has a Date format specified, ScreenIO will automatically use that information to read and write the date correctly, even if its stored in a date other then Julian. This enables you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

== Useful ScreenIO Functions ==

ScreenIO comes with many useful functions that you can use in your helper functions to interact with ScreenIO, and even a few that you can use in your non-ScreenIO programs. ScreenIO's Loading Animations, for example, are available for use in any of your BR programs.

=== Functions to use in your ScreenIO Functions ===

These functions are designed to be run from one of your helper functions, to interrogate the current screen and get additional information.

==== fnFunctionBase ====

fnFunctionBase returns the Function Base of the current screen. Use it for interpreting which control was clicked on, in your Mainloop Event.

This function is designed to run from within your screen, from one of your custom functions.

Example:
if fkey-fnFunctionBase=ctl_Name then
! Name field was clicked on

end if

==== fnIsOutputSpec and fnIsInputSpec ====

<boolean>=fnIsOutputSpec(FieldType$)
<boolean>=fnIsInputSpec(FieldType$)

These functions are used to tell if ScreenIO would treat the given control as an Input Spec or an output Spec

They are designed to run from within your screen, from one of your custom functions.

Example:
if fnIsOutputSpec(FieldType$(ControlIndex)) then
! the current control this Validation or Click Event function is running under is a control that ScreenIO would treat as Output Only
end if

*Control Index always returns the current control that a Validate or Click event function is running under.

==== fnGetUniqueName$ ====

In ScreenIO, your controls can all be referenced in Code by their control names. If more then one control share the same control name, ScreenIO creates a unique name by adding the Count to that name. This function returns the Unique Name for a given control, no matter what it is. This does the inverse of fnFindSubscript below, which takes the name and returns the Index.

Example:
let msgbox("The current control has a unique name of "&fnGetUniqueName$(mat ControlName$,ControlIndex)

*Control Index always returns the current control that a Validate or Click event function is running under.

==== fnFindSubscript ====

fnFindSubscript(MAT Subscripts$,Prefix$,String$*40)

Used to find the Subscript of the control you're searching for, when you have that controls name as a String. It searches the Subscripts array. This does the inverse of fnGetUniqueName$ above.

Example:
let index=fnFindSubscript(mat Subscripts$,"ctl_",TheNameOfTheControl$)

=== Functions for use in your own programs ===

These functions can be used in any of your programs. They are not specific to any screen and are designed to be called from anywhere.

==== Animations ====

let fnPrepareAnimation
let fnAnimate(;Text$*60)
let fnCloseAnimation

The [[#Working with the ScreenIO Loading Icon|ScreenIO Loading Animations]] can be used in your own programs.

Example:
let fnPrepareAnimation
for SomeReallyLongTask=1 to 1000
let fnAnimate(str$(int(100*SomeReallyLongTask/1000))&" percent complete!")
! Do some long slow thing

next SomeReallyLongTask
let fnCloseAnimation

==== fnDays ====

fnDays(UserEnteredDate$*255;DateSpec$*255)

Calls the ScreenIO Days Validation function, which will interpret a wide range of user entered date formats into their corresponding Days value. The DateSpec given is just a general idea - it represents the date spec the user would have seen, and is used to determine the most likely order that the user would have entered the date in, in the event there is ambiguity in the entered data. However, the function is very flexible and will accept a wide variety of date formats entered.

==== fnBr42 and fnBr43 ====

fnBr42
fnBr43

These functions return true if the current copy of BR is equal to or greater then the called function. Internally, ScreenIO uses these functions to disable BR 4.3 only features, when running under BR 4.2. Now, you can use these functions in your programs too.

==== fnListSpec$ ====

fnListSpec$*255(SPECIN$*255)

This function takes a given BR Fields listview spec, and strips off everything after the first 3 commas. It is used to calculate the Listview Base spec when interacting with a listview manually.

=== Functions to interact with the ScreenIO Designer ===

These next few functions can be used to run and interface with the screenio designer directly.

==== fnDesignScreen ====

fnDesignScreen(;ScreenName$)

This function runs the ScreenIO Designer. If the optional Screen name is given, then that screen is loaded for editing.

==== fnSelectEvent$ ====

fnSelectEvent$*255(Current$*255;&ReturnFkey)

This function loads the ScreenIO Select Event Function dialog. You pass in whatever the current user selection is, and it allows the user to change that selection using the standard Event Function selection dialog and returns the result.

==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 [mailto:gabriel.bakker@gmail.com 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 shows some of the change requests that have been completed.

For a complete list, see the recentChanges.txt file that comes with ScreenIO, which can be found by going to the ScreenIO windows dropdown Help menu, and choosing "Recent Changes".

*Filter Functions now include the ability to specify an "Init" and a "Final" function, all within the same filter function file. Init is called automatically, just prior to populating the listview, and Final is called just after. This is similar to the Listview Pre and Post Populate functions but its a lot easier to work with them all in the same .brs file with the filter function that they apply to. When you generate a new filter function it automatically makes shells of these functions for you. Just put whatever code you want in them (v2.5).

*ScreenIO now closes the screenio and screenfld data files right after reading them. This makes it possible to update your customers without kicking them out of the system. You no longer have to worry about a file sharing error on these files when installing updates (v2.49).

*Added support for FileIO's new date field types. If a field is a date field then ScreenIO automatically treats it like a date and sets it as a Date field. Additionally, ScreenIO now supports a new custom function parameter showing which fields from the file are Date fields (v2.48).
*Added mat VisibleKeys$ and mat VisibleRecords to tell which rows are currently visible in the filtered listview (Requires BR 4.3+)

*Fixed the Generate Screen function to use Filter Boxes (v2.47).
*Changed Date processing so that if a year is not entered, it defaults to closest date rather then current year (v2.46).
*Fixed a bug with large fields larger then 255 bytes that was introduced with new Number processing functionality (v2.45).
*Added feature where putting "N" in for the CNVRT spec property forces them to enter only valid numbers (v2.42).
*Added ability to put in just "N" instead of having to put the whole spec "N 10" for the CNVRT spec property (v2.42).
*Fixed a bug in the Orphaned Functions list (v2.4)

Spring Conference 2017 Release, v2.3:

*Added filter boxes for Screen Selection and Function Select
*Added options to ini file to enable or disable them
setting_Load_Filter
setting_FunctionSel_Filter
*Added Version Number to Comments in Program
*Made fnDesignScreen callable as a function
*Made File Layout List redraw every time so it reflects recent Layout Changes
*Fixed a bug in the "Launch Screen in New Window" code
*Added Screen Version field
*Implemeneted fnClearLayoutCash (new Fileio Feature) to get realtime Updates to File Layouts
*Fixed a compatibility issue for using Substitute to rearrange your folder structure
*Added a better message for Out Of Date Helper Libraries
*Began Tracking ScreenIO Version Carefully

Previous Changes:

*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

[[Category:Utilities_Third_Party]]

ScreenIO Library

2019-09-16T22:28:30Z

Laura: /* Validation */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#Useful ScreenIO Functions|Useful ScreenIO Functions]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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.

*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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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 also 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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0
setting_load_filter=0
setting_functionsel_filter=1

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

===Load Filter===

Controls weather there should be a filter box or a search box on the "Load Screen" dialog (2.3).

===setting_functionsel_filter===

Controls weather there is a filter box or a search box on the the "Function Select" dialog screen.

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.

If you're using color attributes, use N=, for example when [BackgroundColor] is set in a config attributes file, use N=[BackgroundColor].

====== 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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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. Fieldtext$ refers to the field that changed and is being validated.

===== 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.

Implement Read and Return keys in the Window Attribute Section because a 0 Read Key will default to a Relative Read.

===== 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.

====== Special ScreenIO Date processing ======
If you use DATE then it will convert the value from its format on disk, into the date format you specify, and when its writing it back to the disk, it will convert it back to its format on disk, before writing it. This works in conjunction with the new [[#Support_for_New_Fileio_Dates|FileIO Date]] features, to allow you to specify the DATE format on disk for Date Fields.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

This also works in listviews to display the dates in any format you want, while still making sure they're numerically sortable.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

As of ScreenIO v91, with the introduction of fnInit_ and fnFinal_ functions, listview Preopulate is no longer the preferred method.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|Listview Filter Function]].

====== fnInit_ and fnFinal_ ======
''Added in ScreenIO v91''

fnInit_ and fnFinal_ are new custom functions for Priming and Clearing your listview, that are better to use then [[#Listview_Prepopulate|Listview Pre/Post Populate]], and that exist along side your filter function, in the same file.

fnInit_ is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_ is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Postpopulate|Listview Postpopulate]]).

The name of the fnInit_ and fnFinal_ functions are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters. fnFilterList$ becomes fnInit_FilterList and fnFinal_FilterList. fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new [[#Filter_Event|Filter Function]] in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

Because the Listview Pre and Post populate functions are almost exclusively used for things that have to do with the filter function, it is easier and more organized to keep the code together in one place.

See [[#Listview_Filter_Function|Example]].

====== 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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''Prefix$''' - Prefix for your FileIO Data File
*'''Currentkey$''' - Currently selected key from your data file
*'''rec(datafile)''' - if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
*'''[[#Working_with_Listviews|mat SelectedKeys$]]''' - If you have a listview with multiselect enabled, use this array to access the keys of all selected records.
*'''[[#Working_with_Listviews|mat SelectedRecords]]''' - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records.
*'''[[#Working_with_Listviews|mat VisibleKeys$]]''' - All the keys that are currently visible in the listview. (v91,Requires BR 4.3+)
*'''[[#Working_with_Listviews|mat VisibleRecords]]''' - All the records that are currently visible in the listview (v91,Requires BR 4.3+)
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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.

===== Prewritten Functions =====
ScreenIO includes a few useful functions for working with listviews and other common operations, right out of the box. Most of them are pretty self explanatory, and include a comment right at the top of the function explaining what it does and how to use it. I'll mention a couple of them here.

*'''deletelistviewrecord''' - Displays a confirmation dialog, and then deletes the currently selected record in a listview.
*'''deleterecord''' - Displays a confirmation dialog, and then deletes the current record in an add/edit screen.
*'''enforcerecord1''' - Use this as your enter event of an add/edit screen to force the screen to edit only record 1 of a data file, for example in a system configuration file that has only 1 record.
*'''enterselectionlistview, filterselection, and toggleselection''' - These three functions work together to make listview screens where the user can toggle on and off a selection of them.
*'''listviewcombo[...]''' - The functions that start with listviewcombo are used for making combination listview/add edit screens (Experimental feature) and are used automatically by the screen generator when you generate one.
*'''pause''' - assign this function to a button in your screen in order to pause your screen in the memory space of your custom helper library in order to debug things.
*'''printlistview''' - This powerful function calls George Tisdales function to print the current listview, including current sorts and filters, to the printer. It requires George Tisdale's rtflib to be installed in a vol002 folder in your app. It can be downloaded from the Sage AX Website here: [[http://www.sageax.com/downloads/vol002.zip]].
*'''exportlistviewcsv''' - This powerful function calls Laura Smiths fileio function to export everything in the current listview to a CSV and open it in the default editor (example excel).
*'''exportcurrentfilecsv''' - This export function calls the fileio Export to CSV function on the given file, for whichever columns the user wants from the file (there's a column selection dialog), and it exports just the specific rows that are currently visible in the currently filtered and sorted listview. '''''Note: '''If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.''

====== ======

===== 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|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$)
mat Employee$=("") : mat Employee=(0)

read #Employee, using form$(Employee), key=f$(todo_employee) : mat Employee$, mat Employee nokey Ignore
let s$(sio_EmployeeName)=Employee$(em_name)

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

dim Employee$(1)*1023,Employee(1),Employee

def fnInit_FilterTasks
let Employee=fnOpen("employee",mat Employee$,mat Employee,mat Form$,1)
fnend
def fnFinal_FilterTasks
Close #Employee:
fnend

fnInit_FilterTasks is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_FilterTasks is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Prepopulate|Listview Postpopulate]]).

The name of the [[#fnInit_and_fnFinal|fnInit_ and fnFinal_ functions]] are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters, so fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new Filter Function in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

These are the preferred method for populating listviews. They're better then [[#Listview_Prepopulate|Listview Prepopulate]] and [[#Listview_Prepopulate|Listview Postpopulate]]. However, [[#Listview_Prepopulate|Listview Pre/Post Populate]] will continue to work, for compatibility with existing programs.

fnInit_ and fnFilter_ were added in ScreenIO v91.

====== 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 several [[#Functions_to_use_in_your_ScreenIO_Functions|built in functions]] for use in your events.

===== 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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Working with Listviews =====
ScreenIO does a number of things to make writing custom functions to work with listviews easier. The currently selected record in the listview is always in mat F$ and mat F, and the primary key of that record is in CurrentKey$. You can use the standard BR system function rec(DataFile) to determine the current record of the data file.

You can also use mat SelectedRecords and mat SelectedKeys$ to determine which row(s) are currently selected by the end user. This makes it a lot easier to work with multi-select listviews. And even if a listview does not allow multi-select, these arrays still work. They contain a single element and it points to the currently selected single row - the same thing you would find in CurrentKey$ and rec(Datafile). That makes it easy to create functions that work both for multi-select and non-multi-select listviews.

BR 4.3 introduced Filter boxes. In BR 4.3 you can use mat VisibleRecords and mat VisibleKeys$, to see which records are currently displayed. They'll contain every row if the listview hasn't been filtered or sorted. But if the user has filtered or sorted the listview, by clicking on the column headings or typing something into a filter box, then these arrays will contain only the rows that are currently visible on the list, and in what order.

=== 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.

However, if you like, you can use these animations in your own programs, by calling the [[#Animations|ScreenIO Animation Functions]].

==== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

=== Support for New Fileio Dates ===

ScreenIO Supports the [[FileIO_Library#Support_for_Dates|FileIO Date features]] and if a field has a Date format specified, ScreenIO will automatically use that information to read and write the date correctly, even if its stored in a date other then Julian. This enables you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

== Useful ScreenIO Functions ==

ScreenIO comes with many useful functions that you can use in your helper functions to interact with ScreenIO, and even a few that you can use in your non-ScreenIO programs. ScreenIO's Loading Animations, for example, are available for use in any of your BR programs.

=== Functions to use in your ScreenIO Functions ===

These functions are designed to be run from one of your helper functions, to interrogate the current screen and get additional information.

==== fnFunctionBase ====

fnFunctionBase returns the Function Base of the current screen. Use it for interpreting which control was clicked on, in your Mainloop Event.

This function is designed to run from within your screen, from one of your custom functions.

Example:
if fkey-fnFunctionBase=ctl_Name then
! Name field was clicked on

end if

==== fnIsOutputSpec and fnIsInputSpec ====

<boolean>=fnIsOutputSpec(FieldType$)
<boolean>=fnIsInputSpec(FieldType$)

These functions are used to tell if ScreenIO would treat the given control as an Input Spec or an output Spec

They are designed to run from within your screen, from one of your custom functions.

Example:
if fnIsOutputSpec(FieldType$(ControlIndex)) then
! the current control this Validation or Click Event function is running under is a control that ScreenIO would treat as Output Only
end if

*Control Index always returns the current control that a Validate or Click event function is running under.

==== fnGetUniqueName$ ====

In ScreenIO, your controls can all be referenced in Code by their control names. If more then one control share the same control name, ScreenIO creates a unique name by adding the Count to that name. This function returns the Unique Name for a given control, no matter what it is. This does the inverse of fnFindSubscript below, which takes the name and returns the Index.

Example:
let msgbox("The current control has a unique name of "&fnGetUniqueName$(mat ControlName$,ControlIndex)

*Control Index always returns the current control that a Validate or Click event function is running under.

==== fnFindSubscript ====

fnFindSubscript(MAT Subscripts$,Prefix$,String$*40)

Used to find the Subscript of the control you're searching for, when you have that controls name as a String. It searches the Subscripts array. This does the inverse of fnGetUniqueName$ above.

Example:
let index=fnFindSubscript(mat Subscripts$,"ctl_",TheNameOfTheControl$)

=== Functions for use in your own programs ===

These functions can be used in any of your programs. They are not specific to any screen and are designed to be called from anywhere.

==== Animations ====

let fnPrepareAnimation
let fnAnimate(;Text$*60)
let fnCloseAnimation

The [[#Working with the ScreenIO Loading Icon|ScreenIO Loading Animations]] can be used in your own programs.

Example:
let fnPrepareAnimation
for SomeReallyLongTask=1 to 1000
let fnAnimate(str$(int(100*SomeReallyLongTask/1000))&" percent complete!")
! Do some long slow thing

next SomeReallyLongTask
let fnCloseAnimation

==== fnDays ====

fnDays(UserEnteredDate$*255;DateSpec$*255)

Calls the ScreenIO Days Validation function, which will interpret a wide range of user entered date formats into their corresponding Days value. The DateSpec given is just a general idea - it represents the date spec the user would have seen, and is used to determine the most likely order that the user would have entered the date in, in the event there is ambiguity in the entered data. However, the function is very flexible and will accept a wide variety of date formats entered.

==== fnBr42 and fnBr43 ====

fnBr42
fnBr43

These functions return true if the current copy of BR is equal to or greater then the called function. Internally, ScreenIO uses these functions to disable BR 4.3 only features, when running under BR 4.2. Now, you can use these functions in your programs too.

==== fnListSpec$ ====

fnListSpec$*255(SPECIN$*255)

This function takes a given BR Fields listview spec, and strips off everything after the first 3 commas. It is used to calculate the Listview Base spec when interacting with a listview manually.

=== Functions to interact with the ScreenIO Designer ===

These next few functions can be used to run and interface with the screenio designer directly.

==== fnDesignScreen ====

fnDesignScreen(;ScreenName$)

This function runs the ScreenIO Designer. If the optional Screen name is given, then that screen is loaded for editing.

==== fnSelectEvent$ ====

fnSelectEvent$*255(Current$*255;&ReturnFkey)

This function loads the ScreenIO Select Event Function dialog. You pass in whatever the current user selection is, and it allows the user to change that selection using the standard Event Function selection dialog and returns the result.

==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 [mailto:gabriel.bakker@gmail.com 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 shows some of the change requests that have been completed.

For a complete list, see the recentChanges.txt file that comes with ScreenIO, which can be found by going to the ScreenIO windows dropdown Help menu, and choosing "Recent Changes".

*Filter Functions now include the ability to specify an "Init" and a "Final" function, all within the same filter function file. Init is called automatically, just prior to populating the listview, and Final is called just after. This is similar to the Listview Pre and Post Populate functions but its a lot easier to work with them all in the same .brs file with the filter function that they apply to. When you generate a new filter function it automatically makes shells of these functions for you. Just put whatever code you want in them (v2.5).

*ScreenIO now closes the screenio and screenfld data files right after reading them. This makes it possible to update your customers without kicking them out of the system. You no longer have to worry about a file sharing error on these files when installing updates (v2.49).

*Added support for FileIO's new date field types. If a field is a date field then ScreenIO automatically treats it like a date and sets it as a Date field. Additionally, ScreenIO now supports a new custom function parameter showing which fields from the file are Date fields (v2.48).
*Added mat VisibleKeys$ and mat VisibleRecords to tell which rows are currently visible in the filtered listview (Requires BR 4.3+)

*Fixed the Generate Screen function to use Filter Boxes (v2.47).
*Changed Date processing so that if a year is not entered, it defaults to closest date rather then current year (v2.46).
*Fixed a bug with large fields larger then 255 bytes that was introduced with new Number processing functionality (v2.45).
*Added feature where putting "N" in for the CNVRT spec property forces them to enter only valid numbers (v2.42).
*Added ability to put in just "N" instead of having to put the whole spec "N 10" for the CNVRT spec property (v2.42).
*Fixed a bug in the Orphaned Functions list (v2.4)

Spring Conference 2017 Release, v2.3:

*Added filter boxes for Screen Selection and Function Select
*Added options to ini file to enable or disable them
setting_Load_Filter
setting_FunctionSel_Filter
*Added Version Number to Comments in Program
*Made fnDesignScreen callable as a function
*Made File Layout List redraw every time so it reflects recent Layout Changes
*Fixed a bug in the "Launch Screen in New Window" code
*Added Screen Version field
*Implemeneted fnClearLayoutCash (new Fileio Feature) to get realtime Updates to File Layouts
*Fixed a compatibility issue for using Substitute to rearrange your folder structure
*Added a better message for Out Of Date Helper Libraries
*Began Tracking ScreenIO Version Carefully

Previous Changes:

*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

[[Category:Utilities_Third_Party]]

ScreenIO Library

2019-09-15T18:37:37Z

Laura: /* Filter */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#Useful ScreenIO Functions|Useful ScreenIO Functions]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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.

*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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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 also 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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0
setting_load_filter=0
setting_functionsel_filter=1

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

===Load Filter===

Controls weather there should be a filter box or a search box on the "Load Screen" dialog (2.3).

===setting_functionsel_filter===

Controls weather there is a filter box or a search box on the the "Function Select" dialog screen.

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.

If you're using color attributes, use N=, for example when [BackgroundColor] is set in a config attributes file, use N=[BackgroundColor].

====== 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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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.

Implement Read and Return keys in the Window Attribute Section because a 0 Read Key will default to a Relative Read.

===== 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.

====== Special ScreenIO Date processing ======
If you use DATE then it will convert the value from its format on disk, into the date format you specify, and when its writing it back to the disk, it will convert it back to its format on disk, before writing it. This works in conjunction with the new [[#Support_for_New_Fileio_Dates|FileIO Date]] features, to allow you to specify the DATE format on disk for Date Fields.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

This also works in listviews to display the dates in any format you want, while still making sure they're numerically sortable.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

As of ScreenIO v91, with the introduction of fnInit_ and fnFinal_ functions, listview Preopulate is no longer the preferred method.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|Listview Filter Function]].

====== fnInit_ and fnFinal_ ======
''Added in ScreenIO v91''

fnInit_ and fnFinal_ are new custom functions for Priming and Clearing your listview, that are better to use then [[#Listview_Prepopulate|Listview Pre/Post Populate]], and that exist along side your filter function, in the same file.

fnInit_ is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_ is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Postpopulate|Listview Postpopulate]]).

The name of the fnInit_ and fnFinal_ functions are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters. fnFilterList$ becomes fnInit_FilterList and fnFinal_FilterList. fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new [[#Filter_Event|Filter Function]] in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

Because the Listview Pre and Post populate functions are almost exclusively used for things that have to do with the filter function, it is easier and more organized to keep the code together in one place.

See [[#Listview_Filter_Function|Example]].

====== 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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''Prefix$''' - Prefix for your FileIO Data File
*'''Currentkey$''' - Currently selected key from your data file
*'''rec(datafile)''' - if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
*'''[[#Working_with_Listviews|mat SelectedKeys$]]''' - If you have a listview with multiselect enabled, use this array to access the keys of all selected records.
*'''[[#Working_with_Listviews|mat SelectedRecords]]''' - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records.
*'''[[#Working_with_Listviews|mat VisibleKeys$]]''' - All the keys that are currently visible in the listview. (v91,Requires BR 4.3+)
*'''[[#Working_with_Listviews|mat VisibleRecords]]''' - All the records that are currently visible in the listview (v91,Requires BR 4.3+)
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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.

===== Prewritten Functions =====
ScreenIO includes a few useful functions for working with listviews and other common operations, right out of the box. Most of them are pretty self explanatory, and include a comment right at the top of the function explaining what it does and how to use it. I'll mention a couple of them here.

*'''deletelistviewrecord''' - Displays a confirmation dialog, and then deletes the currently selected record in a listview.
*'''deleterecord''' - Displays a confirmation dialog, and then deletes the current record in an add/edit screen.
*'''enforcerecord1''' - Use this as your enter event of an add/edit screen to force the screen to edit only record 1 of a data file, for example in a system configuration file that has only 1 record.
*'''enterselectionlistview, filterselection, and toggleselection''' - These three functions work together to make listview screens where the user can toggle on and off a selection of them.
*'''listviewcombo[...]''' - The functions that start with listviewcombo are used for making combination listview/add edit screens (Experimental feature) and are used automatically by the screen generator when you generate one.
*'''pause''' - assign this function to a button in your screen in order to pause your screen in the memory space of your custom helper library in order to debug things.
*'''printlistview''' - This powerful function calls George Tisdales function to print the current listview, including current sorts and filters, to the printer. It requires George Tisdale's rtflib to be installed in a vol002 folder in your app. It can be downloaded from the Sage AX Website here: [[http://www.sageax.com/downloads/vol002.zip]].
*'''exportlistviewcsv''' - This powerful function calls Laura Smiths fileio function to export everything in the current listview to a CSV and open it in the default editor (example excel).
*'''exportcurrentfilecsv''' - This export function calls the fileio Export to CSV function on the given file, for whichever columns the user wants from the file (there's a column selection dialog), and it exports just the specific rows that are currently visible in the currently filtered and sorted listview. '''''Note: '''If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.''

====== ======

===== 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|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$)
mat Employee$=("") : mat Employee=(0)

read #Employee, using form$(Employee), key=f$(todo_employee) : mat Employee$, mat Employee nokey Ignore
let s$(sio_EmployeeName)=Employee$(em_name)

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

dim Employee$(1)*1023,Employee(1),Employee

def fnInit_FilterTasks
let Employee=fnOpen("employee",mat Employee$,mat Employee,mat Form$,1)
fnend
def fnFinal_FilterTasks
Close #Employee:
fnend

fnInit_FilterTasks is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_FilterTasks is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Prepopulate|Listview Postpopulate]]).

The name of the [[#fnInit_and_fnFinal|fnInit_ and fnFinal_ functions]] are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters, so fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new Filter Function in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

These are the preferred method for populating listviews. They're better then [[#Listview_Prepopulate|Listview Prepopulate]] and [[#Listview_Prepopulate|Listview Postpopulate]]. However, [[#Listview_Prepopulate|Listview Pre/Post Populate]] will continue to work, for compatibility with existing programs.

fnInit_ and fnFilter_ were added in ScreenIO v91.

====== 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 several [[#Functions_to_use_in_your_ScreenIO_Functions|built in functions]] for use in your events.

===== 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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Working with Listviews =====
ScreenIO does a number of things to make writing custom functions to work with listviews easier. The currently selected record in the listview is always in mat F$ and mat F, and the primary key of that record is in CurrentKey$. You can use the standard BR system function rec(DataFile) to determine the current record of the data file.

You can also use mat SelectedRecords and mat SelectedKeys$ to determine which row(s) are currently selected by the end user. This makes it a lot easier to work with multi-select listviews. And even if a listview does not allow multi-select, these arrays still work. They contain a single element and it points to the currently selected single row - the same thing you would find in CurrentKey$ and rec(Datafile). That makes it easy to create functions that work both for multi-select and non-multi-select listviews.

BR 4.3 introduced Filter boxes. In BR 4.3 you can use mat VisibleRecords and mat VisibleKeys$, to see which records are currently displayed. They'll contain every row if the listview hasn't been filtered or sorted. But if the user has filtered or sorted the listview, by clicking on the column headings or typing something into a filter box, then these arrays will contain only the rows that are currently visible on the list, and in what order.

=== 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.

However, if you like, you can use these animations in your own programs, by calling the [[#Animations|ScreenIO Animation Functions]].

==== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

=== Support for New Fileio Dates ===

ScreenIO Supports the [[FileIO_Library#Support_for_Dates|FileIO Date features]] and if a field has a Date format specified, ScreenIO will automatically use that information to read and write the date correctly, even if its stored in a date other then Julian. This enables you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

== Useful ScreenIO Functions ==

ScreenIO comes with many useful functions that you can use in your helper functions to interact with ScreenIO, and even a few that you can use in your non-ScreenIO programs. ScreenIO's Loading Animations, for example, are available for use in any of your BR programs.

=== Functions to use in your ScreenIO Functions ===

These functions are designed to be run from one of your helper functions, to interrogate the current screen and get additional information.

==== fnFunctionBase ====

fnFunctionBase returns the Function Base of the current screen. Use it for interpreting which control was clicked on, in your Mainloop Event.

This function is designed to run from within your screen, from one of your custom functions.

Example:
if fkey-fnFunctionBase=ctl_Name then
! Name field was clicked on

end if

==== fnIsOutputSpec and fnIsInputSpec ====

<boolean>=fnIsOutputSpec(FieldType$)
<boolean>=fnIsInputSpec(FieldType$)

These functions are used to tell if ScreenIO would treat the given control as an Input Spec or an output Spec

They are designed to run from within your screen, from one of your custom functions.

Example:
if fnIsOutputSpec(FieldType$(ControlIndex)) then
! the current control this Validation or Click Event function is running under is a control that ScreenIO would treat as Output Only
end if

*Control Index always returns the current control that a Validate or Click event function is running under.

==== fnGetUniqueName$ ====

In ScreenIO, your controls can all be referenced in Code by their control names. If more then one control share the same control name, ScreenIO creates a unique name by adding the Count to that name. This function returns the Unique Name for a given control, no matter what it is. This does the inverse of fnFindSubscript below, which takes the name and returns the Index.

Example:
let msgbox("The current control has a unique name of "&fnGetUniqueName$(mat ControlName$,ControlIndex)

*Control Index always returns the current control that a Validate or Click event function is running under.

==== fnFindSubscript ====

fnFindSubscript(MAT Subscripts$,Prefix$,String$*40)

Used to find the Subscript of the control you're searching for, when you have that controls name as a String. It searches the Subscripts array. This does the inverse of fnGetUniqueName$ above.

Example:
let index=fnFindSubscript(mat Subscripts$,"ctl_",TheNameOfTheControl$)

=== Functions for use in your own programs ===

These functions can be used in any of your programs. They are not specific to any screen and are designed to be called from anywhere.

==== Animations ====

let fnPrepareAnimation
let fnAnimate(;Text$*60)
let fnCloseAnimation

The [[#Working with the ScreenIO Loading Icon|ScreenIO Loading Animations]] can be used in your own programs.

Example:
let fnPrepareAnimation
for SomeReallyLongTask=1 to 1000
let fnAnimate(str$(int(100*SomeReallyLongTask/1000))&" percent complete!")
! Do some long slow thing

next SomeReallyLongTask
let fnCloseAnimation

==== fnDays ====

fnDays(UserEnteredDate$*255;DateSpec$*255)

Calls the ScreenIO Days Validation function, which will interpret a wide range of user entered date formats into their corresponding Days value. The DateSpec given is just a general idea - it represents the date spec the user would have seen, and is used to determine the most likely order that the user would have entered the date in, in the event there is ambiguity in the entered data. However, the function is very flexible and will accept a wide variety of date formats entered.

==== fnBr42 and fnBr43 ====

fnBr42
fnBr43

These functions return true if the current copy of BR is equal to or greater then the called function. Internally, ScreenIO uses these functions to disable BR 4.3 only features, when running under BR 4.2. Now, you can use these functions in your programs too.

==== fnListSpec$ ====

fnListSpec$*255(SPECIN$*255)

This function takes a given BR Fields listview spec, and strips off everything after the first 3 commas. It is used to calculate the Listview Base spec when interacting with a listview manually.

=== Functions to interact with the ScreenIO Designer ===

These next few functions can be used to run and interface with the screenio designer directly.

==== fnDesignScreen ====

fnDesignScreen(;ScreenName$)

This function runs the ScreenIO Designer. If the optional Screen name is given, then that screen is loaded for editing.

==== fnSelectEvent$ ====

fnSelectEvent$*255(Current$*255;&ReturnFkey)

This function loads the ScreenIO Select Event Function dialog. You pass in whatever the current user selection is, and it allows the user to change that selection using the standard Event Function selection dialog and returns the result.

==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 [mailto:gabriel.bakker@gmail.com 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 shows some of the change requests that have been completed.

For a complete list, see the recentChanges.txt file that comes with ScreenIO, which can be found by going to the ScreenIO windows dropdown Help menu, and choosing "Recent Changes".

*Filter Functions now include the ability to specify an "Init" and a "Final" function, all within the same filter function file. Init is called automatically, just prior to populating the listview, and Final is called just after. This is similar to the Listview Pre and Post Populate functions but its a lot easier to work with them all in the same .brs file with the filter function that they apply to. When you generate a new filter function it automatically makes shells of these functions for you. Just put whatever code you want in them (v2.5).

*ScreenIO now closes the screenio and screenfld data files right after reading them. This makes it possible to update your customers without kicking them out of the system. You no longer have to worry about a file sharing error on these files when installing updates (v2.49).

*Added support for FileIO's new date field types. If a field is a date field then ScreenIO automatically treats it like a date and sets it as a Date field. Additionally, ScreenIO now supports a new custom function parameter showing which fields from the file are Date fields (v2.48).
*Added mat VisibleKeys$ and mat VisibleRecords to tell which rows are currently visible in the filtered listview (Requires BR 4.3+)

*Fixed the Generate Screen function to use Filter Boxes (v2.47).
*Changed Date processing so that if a year is not entered, it defaults to closest date rather then current year (v2.46).
*Fixed a bug with large fields larger then 255 bytes that was introduced with new Number processing functionality (v2.45).
*Added feature where putting "N" in for the CNVRT spec property forces them to enter only valid numbers (v2.42).
*Added ability to put in just "N" instead of having to put the whole spec "N 10" for the CNVRT spec property (v2.42).
*Fixed a bug in the Orphaned Functions list (v2.4)

Spring Conference 2017 Release, v2.3:

*Added filter boxes for Screen Selection and Function Select
*Added options to ini file to enable or disable them
setting_Load_Filter
setting_FunctionSel_Filter
*Added Version Number to Comments in Program
*Made fnDesignScreen callable as a function
*Made File Layout List redraw every time so it reflects recent Layout Changes
*Fixed a bug in the "Launch Screen in New Window" code
*Added Screen Version field
*Implemeneted fnClearLayoutCash (new Fileio Feature) to get realtime Updates to File Layouts
*Fixed a compatibility issue for using Substitute to rearrange your folder structure
*Added a better message for Out Of Date Helper Libraries
*Began Tracking ScreenIO Version Carefully

Previous Changes:

*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

[[Category:Utilities_Third_Party]]

ScreenIO Library

2019-08-27T20:40:34Z

Laura: /* Attributes */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#Useful ScreenIO Functions|Useful ScreenIO Functions]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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.

*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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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 also 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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0
setting_load_filter=0
setting_functionsel_filter=1

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

===Load Filter===

Controls weather there should be a filter box or a search box on the "Load Screen" dialog (2.3).

===setting_functionsel_filter===

Controls weather there is a filter box or a search box on the the "Function Select" dialog screen.

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.

If you're using color attributes, use N=, for example when [BackgroundColor] is set in a config attributes file, use N=[BackgroundColor].

====== 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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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.

====== Special ScreenIO Date processing ======
If you use DATE then it will convert the value from its format on disk, into the date format you specify, and when its writing it back to the disk, it will convert it back to its format on disk, before writing it. This works in conjunction with the new [[#Support_for_New_Fileio_Dates|FileIO Date]] features, to allow you to specify the DATE format on disk for Date Fields.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

This also works in listviews to display the dates in any format you want, while still making sure they're numerically sortable.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

As of ScreenIO v91, with the introduction of fnInit_ and fnFinal_ functions, listview Preopulate is no longer the preferred method.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|Listview Filter Function]].

====== fnInit_ and fnFinal_ ======
''Added in ScreenIO v91''

fnInit_ and fnFinal_ are new custom functions for Priming and Clearing your listview, that are better to use then [[#Listview_Prepopulate|Listview Pre/Post Populate]], and that exist along side your filter function, in the same file.

fnInit_ is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_ is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Postpopulate|Listview Postpopulate]]).

The name of the fnInit_ and fnFinal_ functions are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters. fnFilterList$ becomes fnInit_FilterList and fnFinal_FilterList. fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new [[#Filter_Event|Filter Function]] in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

Because the Listview Pre and Post populate functions are almost exclusively used for things that have to do with the filter function, it is easier and more organized to keep the code together in one place.

See [[#Listview_Filter_Function|Example]].

====== 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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''Prefix$''' - Prefix for your FileIO Data File
*'''Currentkey$''' - Currently selected key from your data file
*'''rec(datafile)''' - if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
*'''[[#Working_with_Listviews|mat SelectedKeys$]]''' - If you have a listview with multiselect enabled, use this array to access the keys of all selected records.
*'''[[#Working_with_Listviews|mat SelectedRecords]]''' - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records.
*'''[[#Working_with_Listviews|mat VisibleKeys$]]''' - All the keys that are currently visible in the listview. (v91,Requires BR 4.3+)
*'''[[#Working_with_Listviews|mat VisibleRecords]]''' - All the records that are currently visible in the listview (v91,Requires BR 4.3+)
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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.

===== Prewritten Functions =====
ScreenIO includes a few useful functions for working with listviews and other common operations, right out of the box. Most of them are pretty self explanatory, and include a comment right at the top of the function explaining what it does and how to use it. I'll mention a couple of them here.

*'''deletelistviewrecord''' - Displays a confirmation dialog, and then deletes the currently selected record in a listview.
*'''deleterecord''' - Displays a confirmation dialog, and then deletes the current record in an add/edit screen.
*'''enforcerecord1''' - Use this as your enter event of an add/edit screen to force the screen to edit only record 1 of a data file, for example in a system configuration file that has only 1 record.
*'''enterselectionlistview, filterselection, and toggleselection''' - These three functions work together to make listview screens where the user can toggle on and off a selection of them.
*'''listviewcombo[...]''' - The functions that start with listviewcombo are used for making combination listview/add edit screens (Experimental feature) and are used automatically by the screen generator when you generate one.
*'''pause''' - assign this function to a button in your screen in order to pause your screen in the memory space of your custom helper library in order to debug things.
*'''printlistview''' - This powerful function calls George Tisdales function to print the current listview, including current sorts and filters, to the printer. It requires George Tisdale's rtflib to be installed in a vol002 folder in your app. It can be downloaded from the Sage AX Website here: [[http://www.sageax.com/downloads/vol002.zip]].
*'''exportlistviewcsv''' - This powerful function calls Laura Smiths fileio function to export everything in the current listview to a CSV and open it in the default editor (example excel).
*'''exportcurrentfilecsv''' - This export function calls the fileio Export to CSV function on the given file, for whichever columns the user wants from the file (there's a column selection dialog), and it exports just the specific rows that are currently visible in the currently filtered and sorted listview. '''''Note: '''If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.''

====== ======

===== 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|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$)
mat Employee$=("") : mat Employee=(0)

read #Employee, using form$(Employee), key=f$(todo_employee) : mat Employee$, mat Employee nokey Ignore
let s$(sio_EmployeeName)=Employee$(em_name)

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

dim Employee$(1)*1023,Employee(1),Employee

def fnInit_FilterTasks
let Employee=fnOpen("employee",mat Employee$,mat Employee,mat Form$,1)
fnend
def fnFinal_FilterTasks
Close #Employee:
fnend

fnInit_FilterTasks is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_FilterTasks is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Prepopulate|Listview Postpopulate]]).

The name of the [[#fnInit_and_fnFinal|fnInit_ and fnFinal_ functions]] are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters, so fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new Filter Function in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

These are the preferred method for populating listviews. They're better then [[#Listview_Prepopulate|Listview Prepopulate]] and [[#Listview_Prepopulate|Listview Postpopulate]]. However, [[#Listview_Prepopulate|Listview Pre/Post Populate]] will continue to work, for compatibility with existing programs.

fnInit_ and fnFilter_ were added in ScreenIO v91.

====== 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 several [[#Functions_to_use_in_your_ScreenIO_Functions|built in functions]] for use in your events.

===== 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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Working with Listviews =====
ScreenIO does a number of things to make writing custom functions to work with listviews easier. The currently selected record in the listview is always in mat F$ and mat F, and the primary key of that record is in CurrentKey$. You can use the standard BR system function rec(DataFile) to determine the current record of the data file.

You can also use mat SelectedRecords and mat SelectedKeys$ to determine which row(s) are currently selected by the end user. This makes it a lot easier to work with multi-select listviews. And even if a listview does not allow multi-select, these arrays still work. They contain a single element and it points to the currently selected single row - the same thing you would find in CurrentKey$ and rec(Datafile). That makes it easy to create functions that work both for multi-select and non-multi-select listviews.

BR 4.3 introduced Filter boxes. In BR 4.3 you can use mat VisibleRecords and mat VisibleKeys$, to see which records are currently displayed. They'll contain every row if the listview hasn't been filtered or sorted. But if the user has filtered or sorted the listview, by clicking on the column headings or typing something into a filter box, then these arrays will contain only the rows that are currently visible on the list, and in what order.

=== 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.

However, if you like, you can use these animations in your own programs, by calling the [[#Animations|ScreenIO Animation Functions]].

==== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

=== Support for New Fileio Dates ===

ScreenIO Supports the [[FileIO_Library#Support_for_Dates|FileIO Date features]] and if a field has a Date format specified, ScreenIO will automatically use that information to read and write the date correctly, even if its stored in a date other then Julian. This enables you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

== Useful ScreenIO Functions ==

ScreenIO comes with many useful functions that you can use in your helper functions to interact with ScreenIO, and even a few that you can use in your non-ScreenIO programs. ScreenIO's Loading Animations, for example, are available for use in any of your BR programs.

=== Functions to use in your ScreenIO Functions ===

These functions are designed to be run from one of your helper functions, to interrogate the current screen and get additional information.

==== fnFunctionBase ====

fnFunctionBase returns the Function Base of the current screen. Use it for interpreting which control was clicked on, in your Mainloop Event.

This function is designed to run from within your screen, from one of your custom functions.

Example:
if fkey-fnFunctionBase=ctl_Name then
! Name field was clicked on

end if

==== fnIsOutputSpec and fnIsInputSpec ====

<boolean>=fnIsOutputSpec(FieldType$)
<boolean>=fnIsInputSpec(FieldType$)

These functions are used to tell if ScreenIO would treat the given control as an Input Spec or an output Spec

They are designed to run from within your screen, from one of your custom functions.

Example:
if fnIsOutputSpec(FieldType$(ControlIndex)) then
! the current control this Validation or Click Event function is running under is a control that ScreenIO would treat as Output Only
end if

*Control Index always returns the current control that a Validate or Click event function is running under.

==== fnGetUniqueName$ ====

In ScreenIO, your controls can all be referenced in Code by their control names. If more then one control share the same control name, ScreenIO creates a unique name by adding the Count to that name. This function returns the Unique Name for a given control, no matter what it is. This does the inverse of fnFindSubscript below, which takes the name and returns the Index.

Example:
let msgbox("The current control has a unique name of "&fnGetUniqueName$(mat ControlName$,ControlIndex)

*Control Index always returns the current control that a Validate or Click event function is running under.

==== fnFindSubscript ====

fnFindSubscript(MAT Subscripts$,Prefix$,String$*40)

Used to find the Subscript of the control you're searching for, when you have that controls name as a String. It searches the Subscripts array. This does the inverse of fnGetUniqueName$ above.

Example:
let index=fnFindSubscript(mat Subscripts$,"ctl_",TheNameOfTheControl$)

=== Functions for use in your own programs ===

These functions can be used in any of your programs. They are not specific to any screen and are designed to be called from anywhere.

==== Animations ====

let fnPrepareAnimation
let fnAnimate(;Text$*60)
let fnCloseAnimation

The [[#Working with the ScreenIO Loading Icon|ScreenIO Loading Animations]] can be used in your own programs.

Example:
let fnPrepareAnimation
for SomeReallyLongTask=1 to 1000
let fnAnimate(str$(int(100*SomeReallyLongTask/1000))&" percent complete!")
! Do some long slow thing

next SomeReallyLongTask
let fnCloseAnimation

==== fnDays ====

fnDays(UserEnteredDate$*255;DateSpec$*255)

Calls the ScreenIO Days Validation function, which will interpret a wide range of user entered date formats into their corresponding Days value. The DateSpec given is just a general idea - it represents the date spec the user would have seen, and is used to determine the most likely order that the user would have entered the date in, in the event there is ambiguity in the entered data. However, the function is very flexible and will accept a wide variety of date formats entered.

==== fnBr42 and fnBr43 ====

fnBr42
fnBr43

These functions return true if the current copy of BR is equal to or greater then the called function. Internally, ScreenIO uses these functions to disable BR 4.3 only features, when running under BR 4.2. Now, you can use these functions in your programs too.

==== fnListSpec$ ====

fnListSpec$*255(SPECIN$*255)

This function takes a given BR Fields listview spec, and strips off everything after the first 3 commas. It is used to calculate the Listview Base spec when interacting with a listview manually.

=== Functions to interact with the ScreenIO Designer ===

These next few functions can be used to run and interface with the screenio designer directly.

==== fnDesignScreen ====

fnDesignScreen(;ScreenName$)

This function runs the ScreenIO Designer. If the optional Screen name is given, then that screen is loaded for editing.

==== fnSelectEvent$ ====

fnSelectEvent$*255(Current$*255;&ReturnFkey)

This function loads the ScreenIO Select Event Function dialog. You pass in whatever the current user selection is, and it allows the user to change that selection using the standard Event Function selection dialog and returns the result.

==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 [mailto:gabriel.bakker@gmail.com 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 shows some of the change requests that have been completed.

For a complete list, see the recentChanges.txt file that comes with ScreenIO, which can be found by going to the ScreenIO windows dropdown Help menu, and choosing "Recent Changes".

*Filter Functions now include the ability to specify an "Init" and a "Final" function, all within the same filter function file. Init is called automatically, just prior to populating the listview, and Final is called just after. This is similar to the Listview Pre and Post Populate functions but its a lot easier to work with them all in the same .brs file with the filter function that they apply to. When you generate a new filter function it automatically makes shells of these functions for you. Just put whatever code you want in them (v2.5).

*ScreenIO now closes the screenio and screenfld data files right after reading them. This makes it possible to update your customers without kicking them out of the system. You no longer have to worry about a file sharing error on these files when installing updates (v2.49).

*Added support for FileIO's new date field types. If a field is a date field then ScreenIO automatically treats it like a date and sets it as a Date field. Additionally, ScreenIO now supports a new custom function parameter showing which fields from the file are Date fields (v2.48).
*Added mat VisibleKeys$ and mat VisibleRecords to tell which rows are currently visible in the filtered listview (Requires BR 4.3+)

*Fixed the Generate Screen function to use Filter Boxes (v2.47).
*Changed Date processing so that if a year is not entered, it defaults to closest date rather then current year (v2.46).
*Fixed a bug with large fields larger then 255 bytes that was introduced with new Number processing functionality (v2.45).
*Added feature where putting "N" in for the CNVRT spec property forces them to enter only valid numbers (v2.42).
*Added ability to put in just "N" instead of having to put the whole spec "N 10" for the CNVRT spec property (v2.42).
*Fixed a bug in the Orphaned Functions list (v2.4)

Spring Conference 2017 Release, v2.3:

*Added filter boxes for Screen Selection and Function Select
*Added options to ini file to enable or disable them
setting_Load_Filter
setting_FunctionSel_Filter
*Added Version Number to Comments in Program
*Made fnDesignScreen callable as a function
*Made File Layout List redraw every time so it reflects recent Layout Changes
*Fixed a bug in the "Launch Screen in New Window" code
*Added Screen Version field
*Implemeneted fnClearLayoutCash (new Fileio Feature) to get realtime Updates to File Layouts
*Fixed a compatibility issue for using Substitute to rearrange your folder structure
*Added a better message for Out Of Date Helper Libraries
*Began Tracking ScreenIO Version Carefully

Previous Changes:

*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

[[Category:Utilities_Third_Party]]

2280

2019-05-22T18:06:35Z

Laura:

{{Error
|2280
|[[Library]] not executable
|A [[Load]] [[Resident]] [[command]] was issued for a library [[program]] that is not executable. The Load operation was not performed.
|Fix the bug in the library [[program]], execute [[Clear Resident]] and run your program again.
If you get this in a screenio screen, then load and replace it (lo screenio\screenname, rep) to find the real location of the error.
}}
[[Category:Error Codes]]

2280

2019-05-22T17:54:56Z

Laura:

{{Error
|2280
|[[Library]] not executable
|A [[Load]] [[Resident]] [[command]] was issued for a library [[program]] that is not executable. The Load operation was not performed.
|Fix the bug in the library [[program]], execute [[Clear Resident]] and run your program again.
If you get this in a screenio screen, then load and replace it to find the real location of the error.
}}
[[Category:Error Codes]]

ScreenIO Library

2018-09-20T16:38:39Z

Laura: /* Load Filter */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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 also 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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0
setting_load_filter=0
setting_functionsel_filter=1

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

===Load Filter===

Controls weather there should be a filter box or a search box on the "Load Screen" dialog (2.3).

===setting_functionsel_filter===

Controls weather there is a filter box or a search box on the the "Function Select" dialog screen.

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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.

====== Special ScreenIO Date processing ======
If you use DATE then it will convert the value from its format on disk, into the date format you specify, and when its writing it back to the disk, it will convert it back to its format on disk, before writing it. This works in conjunction with the new [[#Support_for_New_Fileio_Dates|FileIO Date]] features, to allow you to specify the DATE format on disk for Date Fields.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

This also works in listviews to display the dates in any format you want, while still making sure they're numerically sortable.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

As of ScreenIO v91, with the introduction of fnInit_ and fnFinal_ functions, listview Preopulate is no longer the preferred method.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|Listview Filter Function]].

====== fnInit_ and fnFinal_ ======
''Added in ScreenIO v91''

fnInit_ and fnFinal_ are new custom functions for Priming and Clearing your listview, that are better to use then [[#Listview_Prepopulate|Listview Pre/Post Populate]], and that exist along side your filter function, in the same file.

fnInit_ is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_ is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Postpopulate|Listview Postpopulate]]).

The name of the fnInit_ and fnFinal_ functions are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters. fnFilterList$ becomes fnInit_FilterList and fnFinal_FilterList. fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new [[#Filter_Event|Filter Function]] in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

Because the Listview Pre and Post populate functions are almost exclusively used for things that have to do with the filter function, it is easier and more organized to keep the code together in one place.

See [[#Listview_Filter_Function|Example]].

====== 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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''Prefix$''' - Prefix for your FileIO Data File
*'''Currentkey$''' - Currently selected key from your data file
*'''rec(datafile)''' - if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
*'''[[#Working_with_Listviews|mat SelectedKeys$]]''' - If you have a listview with multiselect enabled, use this array to access the keys of all selected records.
*'''[[#Working_with_Listviews|mat SelectedRecords]]''' - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records.
*'''[[#Working_with_Listviews|mat VisibleKeys$]]''' - All the keys that are currently visible in the listview. (v91,Requires BR 4.3+)
*'''[[#Working_with_Listviews|mat VisibleRecords]]''' - All the records that are currently visible in the listview (v91,Requires BR 4.3+)
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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.

===== Prewritten Functions =====
ScreenIO includes a few useful functions for working with listviews and other common operations, right out of the box. Most of them are pretty self explanatory, and include a comment right at the top of the function explaining what it does and how to use it. I'll mention a couple of them here.

*'''deletelistviewrecord''' - Displays a confirmation dialog, and then deletes the currently selected record in a listview.
*'''deleterecord''' - Displays a confirmation dialog, and then deletes the current record in an add/edit screen.
*'''enforcerecord1''' - Use this as your enter event of an add/edit screen to force the screen to edit only record 1 of a data file, for example in a system configuration file that has only 1 record.
*'''enterselectionlistview, filterselection, and toggleselection''' - These three functions work together to make listview screens where the user can toggle on and off a selection of them.
*'''listviewcombo[...]''' - The functions that start with listviewcombo are used for making combination listview/add edit screens (Experimental feature) and are used automatically by the screen generator when you generate one.
*'''pause''' - assign this function to a button in your screen in order to pause your screen in the memory space of your custom helper library in order to debug things.
*'''printlistview''' - This powerful function calls George Tisdales function to print the current listview, including current sorts and filters, to the printer.
*'''exportlistviewcsv''' - This powerful function calls Laura Smiths fileio function to export everything in the current listview to a CSV and open it in the default editor (example excel).
*'''exportcurrentfilecsv''' - This export function calls the fileio Export to CSV function on the given file, for whichever columns the user wants from the file (there's a column selection dialog), and it exports just the specific rows that are currently visible in the currently filtered and sorted listview. '''''Note: '''If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.''

====== ======

===== 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|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$)
mat Employee$=("") : mat Employee=(0)

read #Employee, using form$(Employee), key=f$(todo_employee) : mat Employee$, mat Employee nokey Ignore
let s$(sio_EmployeeName)=Employee$(em_name)

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

dim Employee$(1)*1023,Employee(1),Employee

def fnInit_FilterTasks
let Employee=fnOpen("employee",mat Employee$,mat Employee,mat Form$,1)
fnend
def fnFinal_FilterTasks
Close #Employee:
fnend

fnInit_FilterTasks is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_FilterTasks is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Prepopulate|Listview Postpopulate]]).

The name of the [[#fnInit_and_fnFinal|fnInit_ and fnFinal_ functions]] are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters, so fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new Filter Function in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

These are the preferred method for populating listviews. They're better then [[#Listview_Prepopulate|Listview Prepopulate]] and [[#Listview_Prepopulate|Listview Postpopulate]]. However, [[#Listview_Prepopulate|Listview Pre/Post Populate]] will continue to work, for compatibility with existing programs.

fnInit_ and fnFilter_ were added in ScreenIO v91.

====== 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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Working with Listviews =====
ScreenIO does a number of things to make writing custom functions to work with listviews easier. The currently selected record in the listview is always in mat F$ and mat F, and the primary key of that record is in CurrentKey$. You can use the standard BR system function rec(DataFile) to determine the current record of the data file.

You can also use mat SelectedRecords and mat SelectedKeys$ to determine which row(s) are currently selected by the end user. This makes it a lot easier to work with multi-select listviews. And even if a listview does not allow multi-select, these arrays still work. They contain a single element and it points to the currently selected single row - the same thing you would find in CurrentKey$ and rec(Datafile). That makes it easy to create functions that work both for multi-select and non-multi-select listviews.

BR 4.3 introduced Filter boxes. In BR 4.3 you can use mat VisibleRecords and mat VisibleKeys$, to see which records are currently displayed. They'll contain every row if the listview hasn't been filtered or sorted. But if the user has filtered or sorted the listview, by clicking on the column headings or typing something into a filter box, then these arrays will contain only the rows that are currently visible on the list, and in what order.

=== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

=== Support for New Fileio Dates ===

ScreenIO Supports the [[FileIO_Library#Support_for_Dates|FileIO Date features]] and if a field has a Date format specified, ScreenIO will automatically use that information to read and write the date correctly, even if its stored in a date other then Julian. This enables you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

==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 [mailto:gabriel.bakker@gmail.com 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.

*Filter Functions now include the ability to specify an "Init" and a "Final" function, all within the same filter function file. Init is called automatically, just prior to populating the listview, and Final is called just after. This is similar to the Listview Pre and Post Populate functions but its a lot easier to work with them all in the same .brs file with the filter function that they apply to. When you generate a new filter function it automatically makes shells of these functions for you. Just put whatever code you want in them (v2.5).

*ScreenIO now closes the screenio and screenfld data files right after reading them. This makes it possible to update your customers without kicking them out of the system. You no longer have to worry about a file sharing error on these files when installing updates (v2.49).

*Added support for FileIO's new date field types. If a field is a date field then ScreenIO automatically treats it like a date and sets it as a Date field. Additionally, ScreenIO now supports a new custom function parameter showing which fields from the file are Date fields (v2.48).
*Added mat VisibleKeys$ and mat VisibleRecords to tell which rows are currently visible in the filtered listview (Requires BR 4.3+)

*Fixed the Generate Screen function to use Filter Boxes (v2.47).
*Changed Date processing so that if a year is not entered, it defaults to closest date rather then current year (v2.46).
*Fixed a bug with large fields larger then 255 bytes that was introduced with new Number processing functionality (v2.45).
*Added feature where putting "N" in for the CNVRT spec property forces them to enter only valid numbers (v2.42).
*Added ability to put in just "N" instead of having to put the whole spec "N 10" for the CNVRT spec property (v2.42).
*Fixed a bug in the Orphaned Functions list (v2.4)

Spring Conference 2017 Release, v2.3:

*Added filter boxes for Screen Selection and Function Select
*Added options to ini file to enable or disable them
setting_Load_Filter
setting_FunctionSel_Filter
*Added Version Number to Comments in Program
*Made fnDesignScreen callable as a function
*Made File Layout List redraw every time so it reflects recent Layout Changes
*Fixed a bug in the "Launch Screen in New Window" code
*Added Screen Version field
*Implemeneted fnClearLayoutCash (new Fileio Feature) to get realtime Updates to File Layouts
*Fixed a compatibility issue for using Substitute to rearrange your folder structure
*Added a better message for Out Of Date Helper Libraries
*Began Tracking ScreenIO Version Carefully

Previous Changes:

*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

[[Category:Utilities_Third_Party]]

ScreenIO Library

2018-09-20T16:38:28Z

Laura: /* setting_functionsel_filter */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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 also 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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0
setting_load_filter=0
setting_functionsel_filter=1

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

===Load Filter===

Control weather there should be a filter box or a search box on the "Load Screen" dialog (2.3).

===setting_functionsel_filter===

Controls weather there is a filter box or a search box on the the "Function Select" dialog screen.

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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.

====== Special ScreenIO Date processing ======
If you use DATE then it will convert the value from its format on disk, into the date format you specify, and when its writing it back to the disk, it will convert it back to its format on disk, before writing it. This works in conjunction with the new [[#Support_for_New_Fileio_Dates|FileIO Date]] features, to allow you to specify the DATE format on disk for Date Fields.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

This also works in listviews to display the dates in any format you want, while still making sure they're numerically sortable.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

As of ScreenIO v91, with the introduction of fnInit_ and fnFinal_ functions, listview Preopulate is no longer the preferred method.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|Listview Filter Function]].

====== fnInit_ and fnFinal_ ======
''Added in ScreenIO v91''

fnInit_ and fnFinal_ are new custom functions for Priming and Clearing your listview, that are better to use then [[#Listview_Prepopulate|Listview Pre/Post Populate]], and that exist along side your filter function, in the same file.

fnInit_ is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_ is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Postpopulate|Listview Postpopulate]]).

The name of the fnInit_ and fnFinal_ functions are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters. fnFilterList$ becomes fnInit_FilterList and fnFinal_FilterList. fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new [[#Filter_Event|Filter Function]] in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

Because the Listview Pre and Post populate functions are almost exclusively used for things that have to do with the filter function, it is easier and more organized to keep the code together in one place.

See [[#Listview_Filter_Function|Example]].

====== 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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''Prefix$''' - Prefix for your FileIO Data File
*'''Currentkey$''' - Currently selected key from your data file
*'''rec(datafile)''' - if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
*'''[[#Working_with_Listviews|mat SelectedKeys$]]''' - If you have a listview with multiselect enabled, use this array to access the keys of all selected records.
*'''[[#Working_with_Listviews|mat SelectedRecords]]''' - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records.
*'''[[#Working_with_Listviews|mat VisibleKeys$]]''' - All the keys that are currently visible in the listview. (v91,Requires BR 4.3+)
*'''[[#Working_with_Listviews|mat VisibleRecords]]''' - All the records that are currently visible in the listview (v91,Requires BR 4.3+)
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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.

===== Prewritten Functions =====
ScreenIO includes a few useful functions for working with listviews and other common operations, right out of the box. Most of them are pretty self explanatory, and include a comment right at the top of the function explaining what it does and how to use it. I'll mention a couple of them here.

*'''deletelistviewrecord''' - Displays a confirmation dialog, and then deletes the currently selected record in a listview.
*'''deleterecord''' - Displays a confirmation dialog, and then deletes the current record in an add/edit screen.
*'''enforcerecord1''' - Use this as your enter event of an add/edit screen to force the screen to edit only record 1 of a data file, for example in a system configuration file that has only 1 record.
*'''enterselectionlistview, filterselection, and toggleselection''' - These three functions work together to make listview screens where the user can toggle on and off a selection of them.
*'''listviewcombo[...]''' - The functions that start with listviewcombo are used for making combination listview/add edit screens (Experimental feature) and are used automatically by the screen generator when you generate one.
*'''pause''' - assign this function to a button in your screen in order to pause your screen in the memory space of your custom helper library in order to debug things.
*'''printlistview''' - This powerful function calls George Tisdales function to print the current listview, including current sorts and filters, to the printer.
*'''exportlistviewcsv''' - This powerful function calls Laura Smiths fileio function to export everything in the current listview to a CSV and open it in the default editor (example excel).
*'''exportcurrentfilecsv''' - This export function calls the fileio Export to CSV function on the given file, for whichever columns the user wants from the file (there's a column selection dialog), and it exports just the specific rows that are currently visible in the currently filtered and sorted listview. '''''Note: '''If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.''

====== ======

===== 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|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$)
mat Employee$=("") : mat Employee=(0)

read #Employee, using form$(Employee), key=f$(todo_employee) : mat Employee$, mat Employee nokey Ignore
let s$(sio_EmployeeName)=Employee$(em_name)

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

dim Employee$(1)*1023,Employee(1),Employee

def fnInit_FilterTasks
let Employee=fnOpen("employee",mat Employee$,mat Employee,mat Form$,1)
fnend
def fnFinal_FilterTasks
Close #Employee:
fnend

fnInit_FilterTasks is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_FilterTasks is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Prepopulate|Listview Postpopulate]]).

The name of the [[#fnInit_and_fnFinal|fnInit_ and fnFinal_ functions]] are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters, so fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new Filter Function in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

These are the preferred method for populating listviews. They're better then [[#Listview_Prepopulate|Listview Prepopulate]] and [[#Listview_Prepopulate|Listview Postpopulate]]. However, [[#Listview_Prepopulate|Listview Pre/Post Populate]] will continue to work, for compatibility with existing programs.

fnInit_ and fnFilter_ were added in ScreenIO v91.

====== 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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Working with Listviews =====
ScreenIO does a number of things to make writing custom functions to work with listviews easier. The currently selected record in the listview is always in mat F$ and mat F, and the primary key of that record is in CurrentKey$. You can use the standard BR system function rec(DataFile) to determine the current record of the data file.

You can also use mat SelectedRecords and mat SelectedKeys$ to determine which row(s) are currently selected by the end user. This makes it a lot easier to work with multi-select listviews. And even if a listview does not allow multi-select, these arrays still work. They contain a single element and it points to the currently selected single row - the same thing you would find in CurrentKey$ and rec(Datafile). That makes it easy to create functions that work both for multi-select and non-multi-select listviews.

BR 4.3 introduced Filter boxes. In BR 4.3 you can use mat VisibleRecords and mat VisibleKeys$, to see which records are currently displayed. They'll contain every row if the listview hasn't been filtered or sorted. But if the user has filtered or sorted the listview, by clicking on the column headings or typing something into a filter box, then these arrays will contain only the rows that are currently visible on the list, and in what order.

=== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

=== Support for New Fileio Dates ===

ScreenIO Supports the [[FileIO_Library#Support_for_Dates|FileIO Date features]] and if a field has a Date format specified, ScreenIO will automatically use that information to read and write the date correctly, even if its stored in a date other then Julian. This enables you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

==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 [mailto:gabriel.bakker@gmail.com 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.

*Filter Functions now include the ability to specify an "Init" and a "Final" function, all within the same filter function file. Init is called automatically, just prior to populating the listview, and Final is called just after. This is similar to the Listview Pre and Post Populate functions but its a lot easier to work with them all in the same .brs file with the filter function that they apply to. When you generate a new filter function it automatically makes shells of these functions for you. Just put whatever code you want in them (v2.5).

*ScreenIO now closes the screenio and screenfld data files right after reading them. This makes it possible to update your customers without kicking them out of the system. You no longer have to worry about a file sharing error on these files when installing updates (v2.49).

*Added support for FileIO's new date field types. If a field is a date field then ScreenIO automatically treats it like a date and sets it as a Date field. Additionally, ScreenIO now supports a new custom function parameter showing which fields from the file are Date fields (v2.48).
*Added mat VisibleKeys$ and mat VisibleRecords to tell which rows are currently visible in the filtered listview (Requires BR 4.3+)

*Fixed the Generate Screen function to use Filter Boxes (v2.47).
*Changed Date processing so that if a year is not entered, it defaults to closest date rather then current year (v2.46).
*Fixed a bug with large fields larger then 255 bytes that was introduced with new Number processing functionality (v2.45).
*Added feature where putting "N" in for the CNVRT spec property forces them to enter only valid numbers (v2.42).
*Added ability to put in just "N" instead of having to put the whole spec "N 10" for the CNVRT spec property (v2.42).
*Fixed a bug in the Orphaned Functions list (v2.4)

Spring Conference 2017 Release, v2.3:

*Added filter boxes for Screen Selection and Function Select
*Added options to ini file to enable or disable them
setting_Load_Filter
setting_FunctionSel_Filter
*Added Version Number to Comments in Program
*Made fnDesignScreen callable as a function
*Made File Layout List redraw every time so it reflects recent Layout Changes
*Fixed a bug in the "Launch Screen in New Window" code
*Added Screen Version field
*Implemeneted fnClearLayoutCash (new Fileio Feature) to get realtime Updates to File Layouts
*Fixed a compatibility issue for using Substitute to rearrange your folder structure
*Added a better message for Out Of Date Helper Libraries
*Began Tracking ScreenIO Version Carefully

Previous Changes:

*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

[[Category:Utilities_Third_Party]]

ScreenIO Library

2018-09-20T16:37:50Z

Laura: /* setting_load_filter */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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 also 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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0
setting_load_filter=0
setting_functionsel_filter=1

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

===Load Filter===

Control weather there should be a filter box or a search box on the "Load Screen" dialog (2.3).

===setting_functionsel_filter===

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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.

====== Special ScreenIO Date processing ======
If you use DATE then it will convert the value from its format on disk, into the date format you specify, and when its writing it back to the disk, it will convert it back to its format on disk, before writing it. This works in conjunction with the new [[#Support_for_New_Fileio_Dates|FileIO Date]] features, to allow you to specify the DATE format on disk for Date Fields.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

This also works in listviews to display the dates in any format you want, while still making sure they're numerically sortable.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

As of ScreenIO v91, with the introduction of fnInit_ and fnFinal_ functions, listview Preopulate is no longer the preferred method.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|Listview Filter Function]].

====== fnInit_ and fnFinal_ ======
''Added in ScreenIO v91''

fnInit_ and fnFinal_ are new custom functions for Priming and Clearing your listview, that are better to use then [[#Listview_Prepopulate|Listview Pre/Post Populate]], and that exist along side your filter function, in the same file.

fnInit_ is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_ is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Postpopulate|Listview Postpopulate]]).

The name of the fnInit_ and fnFinal_ functions are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters. fnFilterList$ becomes fnInit_FilterList and fnFinal_FilterList. fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new [[#Filter_Event|Filter Function]] in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

Because the Listview Pre and Post populate functions are almost exclusively used for things that have to do with the filter function, it is easier and more organized to keep the code together in one place.

See [[#Listview_Filter_Function|Example]].

====== 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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''Prefix$''' - Prefix for your FileIO Data File
*'''Currentkey$''' - Currently selected key from your data file
*'''rec(datafile)''' - if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
*'''[[#Working_with_Listviews|mat SelectedKeys$]]''' - If you have a listview with multiselect enabled, use this array to access the keys of all selected records.
*'''[[#Working_with_Listviews|mat SelectedRecords]]''' - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records.
*'''[[#Working_with_Listviews|mat VisibleKeys$]]''' - All the keys that are currently visible in the listview. (v91,Requires BR 4.3+)
*'''[[#Working_with_Listviews|mat VisibleRecords]]''' - All the records that are currently visible in the listview (v91,Requires BR 4.3+)
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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.

===== Prewritten Functions =====
ScreenIO includes a few useful functions for working with listviews and other common operations, right out of the box. Most of them are pretty self explanatory, and include a comment right at the top of the function explaining what it does and how to use it. I'll mention a couple of them here.

*'''deletelistviewrecord''' - Displays a confirmation dialog, and then deletes the currently selected record in a listview.
*'''deleterecord''' - Displays a confirmation dialog, and then deletes the current record in an add/edit screen.
*'''enforcerecord1''' - Use this as your enter event of an add/edit screen to force the screen to edit only record 1 of a data file, for example in a system configuration file that has only 1 record.
*'''enterselectionlistview, filterselection, and toggleselection''' - These three functions work together to make listview screens where the user can toggle on and off a selection of them.
*'''listviewcombo[...]''' - The functions that start with listviewcombo are used for making combination listview/add edit screens (Experimental feature) and are used automatically by the screen generator when you generate one.
*'''pause''' - assign this function to a button in your screen in order to pause your screen in the memory space of your custom helper library in order to debug things.
*'''printlistview''' - This powerful function calls George Tisdales function to print the current listview, including current sorts and filters, to the printer.
*'''exportlistviewcsv''' - This powerful function calls Laura Smiths fileio function to export everything in the current listview to a CSV and open it in the default editor (example excel).
*'''exportcurrentfilecsv''' - This export function calls the fileio Export to CSV function on the given file, for whichever columns the user wants from the file (there's a column selection dialog), and it exports just the specific rows that are currently visible in the currently filtered and sorted listview. '''''Note: '''If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.''

====== ======

===== 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|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$)
mat Employee$=("") : mat Employee=(0)

read #Employee, using form$(Employee), key=f$(todo_employee) : mat Employee$, mat Employee nokey Ignore
let s$(sio_EmployeeName)=Employee$(em_name)

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

dim Employee$(1)*1023,Employee(1),Employee

def fnInit_FilterTasks
let Employee=fnOpen("employee",mat Employee$,mat Employee,mat Form$,1)
fnend
def fnFinal_FilterTasks
Close #Employee:
fnend

fnInit_FilterTasks is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_FilterTasks is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Prepopulate|Listview Postpopulate]]).

The name of the [[#fnInit_and_fnFinal|fnInit_ and fnFinal_ functions]] are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters, so fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new Filter Function in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

These are the preferred method for populating listviews. They're better then [[#Listview_Prepopulate|Listview Prepopulate]] and [[#Listview_Prepopulate|Listview Postpopulate]]. However, [[#Listview_Prepopulate|Listview Pre/Post Populate]] will continue to work, for compatibility with existing programs.

fnInit_ and fnFilter_ were added in ScreenIO v91.

====== 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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Working with Listviews =====
ScreenIO does a number of things to make writing custom functions to work with listviews easier. The currently selected record in the listview is always in mat F$ and mat F, and the primary key of that record is in CurrentKey$. You can use the standard BR system function rec(DataFile) to determine the current record of the data file.

You can also use mat SelectedRecords and mat SelectedKeys$ to determine which row(s) are currently selected by the end user. This makes it a lot easier to work with multi-select listviews. And even if a listview does not allow multi-select, these arrays still work. They contain a single element and it points to the currently selected single row - the same thing you would find in CurrentKey$ and rec(Datafile). That makes it easy to create functions that work both for multi-select and non-multi-select listviews.

BR 4.3 introduced Filter boxes. In BR 4.3 you can use mat VisibleRecords and mat VisibleKeys$, to see which records are currently displayed. They'll contain every row if the listview hasn't been filtered or sorted. But if the user has filtered or sorted the listview, by clicking on the column headings or typing something into a filter box, then these arrays will contain only the rows that are currently visible on the list, and in what order.

=== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

=== Support for New Fileio Dates ===

ScreenIO Supports the [[FileIO_Library#Support_for_Dates|FileIO Date features]] and if a field has a Date format specified, ScreenIO will automatically use that information to read and write the date correctly, even if its stored in a date other then Julian. This enables you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

==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 [mailto:gabriel.bakker@gmail.com 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.

*Filter Functions now include the ability to specify an "Init" and a "Final" function, all within the same filter function file. Init is called automatically, just prior to populating the listview, and Final is called just after. This is similar to the Listview Pre and Post Populate functions but its a lot easier to work with them all in the same .brs file with the filter function that they apply to. When you generate a new filter function it automatically makes shells of these functions for you. Just put whatever code you want in them (v2.5).

*ScreenIO now closes the screenio and screenfld data files right after reading them. This makes it possible to update your customers without kicking them out of the system. You no longer have to worry about a file sharing error on these files when installing updates (v2.49).

*Added support for FileIO's new date field types. If a field is a date field then ScreenIO automatically treats it like a date and sets it as a Date field. Additionally, ScreenIO now supports a new custom function parameter showing which fields from the file are Date fields (v2.48).
*Added mat VisibleKeys$ and mat VisibleRecords to tell which rows are currently visible in the filtered listview (Requires BR 4.3+)

*Fixed the Generate Screen function to use Filter Boxes (v2.47).
*Changed Date processing so that if a year is not entered, it defaults to closest date rather then current year (v2.46).
*Fixed a bug with large fields larger then 255 bytes that was introduced with new Number processing functionality (v2.45).
*Added feature where putting "N" in for the CNVRT spec property forces them to enter only valid numbers (v2.42).
*Added ability to put in just "N" instead of having to put the whole spec "N 10" for the CNVRT spec property (v2.42).
*Fixed a bug in the Orphaned Functions list (v2.4)

Spring Conference 2017 Release, v2.3:

*Added filter boxes for Screen Selection and Function Select
*Added options to ini file to enable or disable them
setting_Load_Filter
setting_FunctionSel_Filter
*Added Version Number to Comments in Program
*Made fnDesignScreen callable as a function
*Made File Layout List redraw every time so it reflects recent Layout Changes
*Fixed a bug in the "Launch Screen in New Window" code
*Added Screen Version field
*Implemeneted fnClearLayoutCash (new Fileio Feature) to get realtime Updates to File Layouts
*Fixed a compatibility issue for using Substitute to rearrange your folder structure
*Added a better message for Out Of Date Helper Libraries
*Began Tracking ScreenIO Version Carefully

Previous Changes:

*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

[[Category:Utilities_Third_Party]]

ScreenIO Library

2018-09-20T16:28:23Z

Laura: /* Screenio.ini */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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 also 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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0
setting_load_filter=0
setting_functionsel_filter=1

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

===setting_load_filter===

===setting_functionsel_filter===

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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.

====== Special ScreenIO Date processing ======
If you use DATE then it will convert the value from its format on disk, into the date format you specify, and when its writing it back to the disk, it will convert it back to its format on disk, before writing it. This works in conjunction with the new [[#Support_for_New_Fileio_Dates|FileIO Date]] features, to allow you to specify the DATE format on disk for Date Fields.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

This also works in listviews to display the dates in any format you want, while still making sure they're numerically sortable.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

As of ScreenIO v91, with the introduction of fnInit_ and fnFinal_ functions, listview Preopulate is no longer the preferred method.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|Listview Filter Function]].

====== fnInit_ and fnFinal_ ======
''Added in ScreenIO v91''

fnInit_ and fnFinal_ are new custom functions for Priming and Clearing your listview, that are better to use then [[#Listview_Prepopulate|Listview Pre/Post Populate]], and that exist along side your filter function, in the same file.

fnInit_ is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_ is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Postpopulate|Listview Postpopulate]]).

The name of the fnInit_ and fnFinal_ functions are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters. fnFilterList$ becomes fnInit_FilterList and fnFinal_FilterList. fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new [[#Filter_Event|Filter Function]] in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

Because the Listview Pre and Post populate functions are almost exclusively used for things that have to do with the filter function, it is easier and more organized to keep the code together in one place.

See [[#Listview_Filter_Function|Example]].

====== 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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''Prefix$''' - Prefix for your FileIO Data File
*'''Currentkey$''' - Currently selected key from your data file
*'''rec(datafile)''' - if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
*'''[[#Working_with_Listviews|mat SelectedKeys$]]''' - If you have a listview with multiselect enabled, use this array to access the keys of all selected records.
*'''[[#Working_with_Listviews|mat SelectedRecords]]''' - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records.
*'''[[#Working_with_Listviews|mat VisibleKeys$]]''' - All the keys that are currently visible in the listview. (v91,Requires BR 4.3+)
*'''[[#Working_with_Listviews|mat VisibleRecords]]''' - All the records that are currently visible in the listview (v91,Requires BR 4.3+)
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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.

===== Prewritten Functions =====
ScreenIO includes a few useful functions for working with listviews and other common operations, right out of the box. Most of them are pretty self explanatory, and include a comment right at the top of the function explaining what it does and how to use it. I'll mention a couple of them here.

*'''deletelistviewrecord''' - Displays a confirmation dialog, and then deletes the currently selected record in a listview.
*'''deleterecord''' - Displays a confirmation dialog, and then deletes the current record in an add/edit screen.
*'''enforcerecord1''' - Use this as your enter event of an add/edit screen to force the screen to edit only record 1 of a data file, for example in a system configuration file that has only 1 record.
*'''enterselectionlistview, filterselection, and toggleselection''' - These three functions work together to make listview screens where the user can toggle on and off a selection of them.
*'''listviewcombo[...]''' - The functions that start with listviewcombo are used for making combination listview/add edit screens (Experimental feature) and are used automatically by the screen generator when you generate one.
*'''pause''' - assign this function to a button in your screen in order to pause your screen in the memory space of your custom helper library in order to debug things.
*'''printlistview''' - This powerful function calls George Tisdales function to print the current listview, including current sorts and filters, to the printer.
*'''exportlistviewcsv''' - This powerful function calls Laura Smiths fileio function to export everything in the current listview to a CSV and open it in the default editor (example excel).
*'''exportcurrentfilecsv''' - This export function calls the fileio Export to CSV function on the given file, for whichever columns the user wants from the file (there's a column selection dialog), and it exports just the specific rows that are currently visible in the currently filtered and sorted listview. '''''Note: '''If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.''

====== ======

===== 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|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$)
mat Employee$=("") : mat Employee=(0)

read #Employee, using form$(Employee), key=f$(todo_employee) : mat Employee$, mat Employee nokey Ignore
let s$(sio_EmployeeName)=Employee$(em_name)

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

dim Employee$(1)*1023,Employee(1),Employee

def fnInit_FilterTasks
let Employee=fnOpen("employee",mat Employee$,mat Employee,mat Form$,1)
fnend
def fnFinal_FilterTasks
Close #Employee:
fnend

fnInit_FilterTasks is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_FilterTasks is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Prepopulate|Listview Postpopulate]]).

The name of the [[#fnInit_and_fnFinal|fnInit_ and fnFinal_ functions]] are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters, so fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new Filter Function in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

These are the preferred method for populating listviews. They're better then [[#Listview_Prepopulate|Listview Prepopulate]] and [[#Listview_Prepopulate|Listview Postpopulate]]. However, [[#Listview_Prepopulate|Listview Pre/Post Populate]] will continue to work, for compatibility with existing programs.

fnInit_ and fnFilter_ were added in ScreenIO v91.

====== 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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Working with Listviews =====
ScreenIO does a number of things to make writing custom functions to work with listviews easier. The currently selected record in the listview is always in mat F$ and mat F, and the primary key of that record is in CurrentKey$. You can use the standard BR system function rec(DataFile) to determine the current record of the data file.

You can also use mat SelectedRecords and mat SelectedKeys$ to determine which row(s) are currently selected by the end user. This makes it a lot easier to work with multi-select listviews. And even if a listview does not allow multi-select, these arrays still work. They contain a single element and it points to the currently selected single row - the same thing you would find in CurrentKey$ and rec(Datafile). That makes it easy to create functions that work both for multi-select and non-multi-select listviews.

BR 4.3 introduced Filter boxes. In BR 4.3 you can use mat VisibleRecords and mat VisibleKeys$, to see which records are currently displayed. They'll contain every row if the listview hasn't been filtered or sorted. But if the user has filtered or sorted the listview, by clicking on the column headings or typing something into a filter box, then these arrays will contain only the rows that are currently visible on the list, and in what order.

=== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

=== Support for New Fileio Dates ===

ScreenIO Supports the [[FileIO_Library#Support_for_Dates|FileIO Date features]] and if a field has a Date format specified, ScreenIO will automatically use that information to read and write the date correctly, even if its stored in a date other then Julian. This enables you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

==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 [mailto:gabriel.bakker@gmail.com 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.

*Filter Functions now include the ability to specify an "Init" and a "Final" function, all within the same filter function file. Init is called automatically, just prior to populating the listview, and Final is called just after. This is similar to the Listview Pre and Post Populate functions but its a lot easier to work with them all in the same .brs file with the filter function that they apply to. When you generate a new filter function it automatically makes shells of these functions for you. Just put whatever code you want in them (v2.5).

*ScreenIO now closes the screenio and screenfld data files right after reading them. This makes it possible to update your customers without kicking them out of the system. You no longer have to worry about a file sharing error on these files when installing updates (v2.49).

*Added support for FileIO's new date field types. If a field is a date field then ScreenIO automatically treats it like a date and sets it as a Date field. Additionally, ScreenIO now supports a new custom function parameter showing which fields from the file are Date fields (v2.48).
*Added mat VisibleKeys$ and mat VisibleRecords to tell which rows are currently visible in the filtered listview (Requires BR 4.3+)

*Fixed the Generate Screen function to use Filter Boxes (v2.47).
*Changed Date processing so that if a year is not entered, it defaults to closest date rather then current year (v2.46).
*Fixed a bug with large fields larger then 255 bytes that was introduced with new Number processing functionality (v2.45).
*Added feature where putting "N" in for the CNVRT spec property forces them to enter only valid numbers (v2.42).
*Added ability to put in just "N" instead of having to put the whole spec "N 10" for the CNVRT spec property (v2.42).
*Fixed a bug in the Orphaned Functions list (v2.4)

Spring Conference 2017 Release, v2.3:

*Added filter boxes for Screen Selection and Function Select
*Added options to ini file to enable or disable them
setting_Load_Filter
setting_FunctionSel_Filter
*Added Version Number to Comments in Program
*Made fnDesignScreen callable as a function
*Made File Layout List redraw every time so it reflects recent Layout Changes
*Fixed a bug in the "Launch Screen in New Window" code
*Added Screen Version field
*Implemeneted fnClearLayoutCash (new Fileio Feature) to get realtime Updates to File Layouts
*Fixed a compatibility issue for using Substitute to rearrange your folder structure
*Added a better message for Out Of Date Helper Libraries
*Began Tracking ScreenIO Version Carefully

Previous Changes:

*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

[[Category:Utilities_Third_Party]]

FileIO Library

2018-09-20T15:46:51Z

Laura: /* fnReadFormAndSubs */

The '''FileIO''' Library began as a project to find a way to reduce the headache associated with making changes to data files. In my experiences working for [[BRC]], I had to make a change to the commun file, a data file that stores information about communication with EDI VANs. I added some new fields, and removed a couple of old fields, and then I began searching through the BRC program suite to find and modify each program that referenced this data file in order to update it with the proper new form statement. This task quickly became daunting as I noticed that out of BRC’s program suite of over 600 programs, more than one third of them referenced the commun file. With 223 programs to modify, the task was given up as hopeless and tabled indefinitely.

I am happy to announce that we have solved this problem. When I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define your file layouts in an ASCII text file layout file that I will tell you about in a minute. The FileIO Library will actually parse through your file layouts, and it will instruct your programs how to read the data file, so that you don’t have to. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it even contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and initializing of the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

You will need to define one array for all forms and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store all the numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these to:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string arrays to 1000. This is the length of one field in the color file. It needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

You will also need a variable to store the form statement associated with reading the files. This form statement will be dynamically generated whenever a new file is opened. It will say:

01020 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement and BR limits all form statements to 255 bytes compiled anyway, so 255 is enough for the Forms$ array.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add a snippet of code to interface with the library.

Because BR libraries do not share variables with the programs they are called from, we will need to execute a proc file whenever we open a file to set the names of all our variables after we return. Add the following snippet of code into your program. It will create an FnOpen function that calls the library version and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]:
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
These statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and read it to find out what the Color File looks like. Then Open the Color File, and set MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers into (subscripts) these arrays to access the data we after reading it, and it will place the file handle into a variable called colorfile.

The second open above will do the same thing to the color category file, except the 1 parameter tells the function to open readonly. The subscripts array will be executed, creating the subscripts in memory, and the pointers (subscripts) will be set in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

== File Layouts ==
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm File, a unique string to prefix all of your subscript pointers, and the file version number. The subscript value is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, ITEM
price.ky2, FARM
price.ky3, ITEM/FARM/GRADE
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1).
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

If I wanted to implement the above example, I would say:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnEmpty & fnEmptyS ====
These functions are for testing optional arrays that may or may not have been passed into your function. BR will give an error if your code attempts to use an optional array that wasn't passed in, so you can use these functions to test if the user actually passed in the optional array or not.

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OptionalArray)
if ~fnEmpty(mat OptionalArray) then
! mat Optional array was given, process it here.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;ParentWindow)''

The screen size is returned in the first two parameters, and the third parameter tells the function which window to interrogate. If not given, it assumes window 0.

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load Program2$")
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load Program2$")
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile''

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the display length of.

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

ScreenIO Library

2018-09-20T14:58:39Z

Laura: /* Completed Future Change Requests */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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 also 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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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.

====== Special ScreenIO Date processing ======
If you use DATE then it will convert the value from its format on disk, into the date format you specify, and when its writing it back to the disk, it will convert it back to its format on disk, before writing it. This works in conjunction with the new [[#Support_for_New_Fileio_Dates|FileIO Date]] features, to allow you to specify the DATE format on disk for Date Fields.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

This also works in listviews to display the dates in any format you want, while still making sure they're numerically sortable.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

As of ScreenIO v91, with the introduction of fnInit_ and fnFinal_ functions, listview Preopulate is no longer the preferred method.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|Listview Filter Function]].

====== fnInit_ and fnFinal_ ======
''Added in ScreenIO v91''

fnInit_ and fnFinal_ are new custom functions for Priming and Clearing your listview, that are better to use then [[#Listview_Prepopulate|Listview Pre/Post Populate]], and that exist along side your filter function, in the same file.

fnInit_ is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_ is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Postpopulate|Listview Postpopulate]]).

The name of the fnInit_ and fnFinal_ functions are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters. fnFilterList$ becomes fnInit_FilterList and fnFinal_FilterList. fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new [[#Filter_Event|Filter Function]] in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

Because the Listview Pre and Post populate functions are almost exclusively used for things that have to do with the filter function, it is easier and more organized to keep the code together in one place.

See [[#Listview_Filter_Function|Example]].

====== 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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''Prefix$''' - Prefix for your FileIO Data File
*'''Currentkey$''' - Currently selected key from your data file
*'''rec(datafile)''' - if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
*'''[[#Working_with_Listviews|mat SelectedKeys$]]''' - If you have a listview with multiselect enabled, use this array to access the keys of all selected records.
*'''[[#Working_with_Listviews|mat SelectedRecords]]''' - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records.
*'''[[#Working_with_Listviews|mat VisibleKeys$]]''' - All the keys that are currently visible in the listview. (v91,Requires BR 4.3+)
*'''[[#Working_with_Listviews|mat VisibleRecords]]''' - All the records that are currently visible in the listview (v91,Requires BR 4.3+)
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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.

===== Prewritten Functions =====
ScreenIO includes a few useful functions for working with listviews and other common operations, right out of the box. Most of them are pretty self explanatory, and include a comment right at the top of the function explaining what it does and how to use it. I'll mention a couple of them here.

*'''deletelistviewrecord''' - Displays a confirmation dialog, and then deletes the currently selected record in a listview.
*'''deleterecord''' - Displays a confirmation dialog, and then deletes the current record in an add/edit screen.
*'''enforcerecord1''' - Use this as your enter event of an add/edit screen to force the screen to edit only record 1 of a data file, for example in a system configuration file that has only 1 record.
*'''enterselectionlistview, filterselection, and toggleselection''' - These three functions work together to make listview screens where the user can toggle on and off a selection of them.
*'''listviewcombo[...]''' - The functions that start with listviewcombo are used for making combination listview/add edit screens (Experimental feature) and are used automatically by the screen generator when you generate one.
*'''pause''' - assign this function to a button in your screen in order to pause your screen in the memory space of your custom helper library in order to debug things.
*'''printlistview''' - This powerful function calls George Tisdales function to print the current listview, including current sorts and filters, to the printer.
*'''exportlistviewcsv''' - This powerful function calls Laura Smiths fileio function to export everything in the current listview to a CSV and open it in the default editor (example excel).
*'''exportcurrentfilecsv''' - This export function calls the fileio Export to CSV function on the given file, for whichever columns the user wants from the file (there's a column selection dialog), and it exports just the specific rows that are currently visible in the currently filtered and sorted listview. '''''Note: '''If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.''

====== ======

===== 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|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$)
mat Employee$=("") : mat Employee=(0)

read #Employee, using form$(Employee), key=f$(todo_employee) : mat Employee$, mat Employee nokey Ignore
let s$(sio_EmployeeName)=Employee$(em_name)

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

dim Employee$(1)*1023,Employee(1),Employee

def fnInit_FilterTasks
let Employee=fnOpen("employee",mat Employee$,mat Employee,mat Form$,1)
fnend
def fnFinal_FilterTasks
Close #Employee:
fnend

fnInit_FilterTasks is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_FilterTasks is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Prepopulate|Listview Postpopulate]]).

The name of the [[#fnInit_and_fnFinal|fnInit_ and fnFinal_ functions]] are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters, so fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new Filter Function in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

These are the preferred method for populating listviews. They're better then [[#Listview_Prepopulate|Listview Prepopulate]] and [[#Listview_Prepopulate|Listview Postpopulate]]. However, [[#Listview_Prepopulate|Listview Pre/Post Populate]] will continue to work, for compatibility with existing programs.

fnInit_ and fnFilter_ were added in ScreenIO v91.

====== 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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Working with Listviews =====
ScreenIO does a number of things to make writing custom functions to work with listviews easier. The currently selected record in the listview is always in mat F$ and mat F, and the primary key of that record is in CurrentKey$. You can use the standard BR system function rec(DataFile) to determine the current record of the data file.

You can also use mat SelectedRecords and mat SelectedKeys$ to determine which row(s) are currently selected by the end user. This makes it a lot easier to work with multi-select listviews. And even if a listview does not allow multi-select, these arrays still work. They contain a single element and it points to the currently selected single row - the same thing you would find in CurrentKey$ and rec(Datafile). That makes it easy to create functions that work both for multi-select and non-multi-select listviews.

BR 4.3 introduced Filter boxes. In BR 4.3 you can use mat VisibleRecords and mat VisibleKeys$, to see which records are currently displayed. They'll contain every row if the listview hasn't been filtered or sorted. But if the user has filtered or sorted the listview, by clicking on the column headings or typing something into a filter box, then these arrays will contain only the rows that are currently visible on the list, and in what order.

=== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

=== Support for New Fileio Dates ===

ScreenIO Supports the [[FileIO_Library#Support_for_Dates|FileIO Date features]] and if a field has a Date format specified, ScreenIO will automatically use that information to read and write the date correctly, even if its stored in a date other then Julian. This enables you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

==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 [mailto:gabriel.bakker@gmail.com 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.

*Filter Functions now include the ability to specify an "Init" and a "Final" function, all within the same filter function file. Init is called automatically, just prior to populating the listview, and Final is called just after. This is similar to the Listview Pre and Post Populate functions but its a lot easier to work with them all in the same .brs file with the filter function that they apply to. When you generate a new filter function it automatically makes shells of these functions for you. Just put whatever code you want in them (v2.5).

*ScreenIO now closes the screenio and screenfld data files right after reading them. This makes it possible to update your customers without kicking them out of the system. You no longer have to worry about a file sharing error on these files when installing updates (v2.49).

*Added support for FileIO's new date field types. If a field is a date field then ScreenIO automatically treats it like a date and sets it as a Date field. Additionally, ScreenIO now supports a new custom function parameter showing which fields from the file are Date fields (v2.48).
*Added mat VisibleKeys$ and mat VisibleRecords to tell which rows are currently visible in the filtered listview (Requires BR 4.3+)

*Fixed the Generate Screen function to use Filter Boxes (v2.47).
*Changed Date processing so that if a year is not entered, it defaults to closest date rather then current year (v2.46).
*Fixed a bug with large fields larger then 255 bytes that was introduced with new Number processing functionality (v2.45).
*Added feature where putting "N" in for the CNVRT spec property forces them to enter only valid numbers (v2.42).
*Added ability to put in just "N" instead of having to put the whole spec "N 10" for the CNVRT spec property (v2.42).
*Fixed a bug in the Orphaned Functions list (v2.4)

Spring Conference 2017 Release, v2.3:

*Added filter boxes for Screen Selection and Function Select
*Added options to ini file to enable or disable them
setting_Load_Filter
setting_FunctionSel_Filter
*Added Version Number to Comments in Program
*Made fnDesignScreen callable as a function
*Made File Layout List redraw every time so it reflects recent Layout Changes
*Fixed a bug in the "Launch Screen in New Window" code
*Added Screen Version field
*Implemeneted fnClearLayoutCash (new Fileio Feature) to get realtime Updates to File Layouts
*Fixed a compatibility issue for using Substitute to rearrange your folder structure
*Added a better message for Out Of Date Helper Libraries
*Began Tracking ScreenIO Version Carefully

Previous Changes:

*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

[[Category:Utilities_Third_Party]]

ScreenIO Library

2018-09-20T14:57:07Z

Laura: /* Completed Future Change Requests */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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 also 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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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.

====== Special ScreenIO Date processing ======
If you use DATE then it will convert the value from its format on disk, into the date format you specify, and when its writing it back to the disk, it will convert it back to its format on disk, before writing it. This works in conjunction with the new [[#Support_for_New_Fileio_Dates|FileIO Date]] features, to allow you to specify the DATE format on disk for Date Fields.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

This also works in listviews to display the dates in any format you want, while still making sure they're numerically sortable.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

As of ScreenIO v91, with the introduction of fnInit_ and fnFinal_ functions, listview Preopulate is no longer the preferred method.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|Listview Filter Function]].

====== fnInit_ and fnFinal_ ======
''Added in ScreenIO v91''

fnInit_ and fnFinal_ are new custom functions for Priming and Clearing your listview, that are better to use then [[#Listview_Prepopulate|Listview Pre/Post Populate]], and that exist along side your filter function, in the same file.

fnInit_ is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_ is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Postpopulate|Listview Postpopulate]]).

The name of the fnInit_ and fnFinal_ functions are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters. fnFilterList$ becomes fnInit_FilterList and fnFinal_FilterList. fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new [[#Filter_Event|Filter Function]] in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

Because the Listview Pre and Post populate functions are almost exclusively used for things that have to do with the filter function, it is easier and more organized to keep the code together in one place.

See [[#Listview_Filter_Function|Example]].

====== 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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''Prefix$''' - Prefix for your FileIO Data File
*'''Currentkey$''' - Currently selected key from your data file
*'''rec(datafile)''' - if you need to know the current record in the primary data file you can use the BR system function REC to discover it.
*'''[[#Working_with_Listviews|mat SelectedKeys$]]''' - If you have a listview with multiselect enabled, use this array to access the keys of all selected records.
*'''[[#Working_with_Listviews|mat SelectedRecords]]''' - If you have a listview with multiselect enabled, use this array to access the record numbers of all selected records.
*'''[[#Working_with_Listviews|mat VisibleKeys$]]''' - All the keys that are currently visible in the listview. (v91,Requires BR 4.3+)
*'''[[#Working_with_Listviews|mat VisibleRecords]]''' - All the records that are currently visible in the listview (v91,Requires BR 4.3+)
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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.

===== Prewritten Functions =====
ScreenIO includes a few useful functions for working with listviews and other common operations, right out of the box. Most of them are pretty self explanatory, and include a comment right at the top of the function explaining what it does and how to use it. I'll mention a couple of them here.

*'''deletelistviewrecord''' - Displays a confirmation dialog, and then deletes the currently selected record in a listview.
*'''deleterecord''' - Displays a confirmation dialog, and then deletes the current record in an add/edit screen.
*'''enforcerecord1''' - Use this as your enter event of an add/edit screen to force the screen to edit only record 1 of a data file, for example in a system configuration file that has only 1 record.
*'''enterselectionlistview, filterselection, and toggleselection''' - These three functions work together to make listview screens where the user can toggle on and off a selection of them.
*'''listviewcombo[...]''' - The functions that start with listviewcombo are used for making combination listview/add edit screens (Experimental feature) and are used automatically by the screen generator when you generate one.
*'''pause''' - assign this function to a button in your screen in order to pause your screen in the memory space of your custom helper library in order to debug things.
*'''printlistview''' - This powerful function calls George Tisdales function to print the current listview, including current sorts and filters, to the printer.
*'''exportlistviewcsv''' - This powerful function calls Laura Smiths fileio function to export everything in the current listview to a CSV and open it in the default editor (example excel).
*'''exportcurrentfilecsv''' - This export function calls the fileio Export to CSV function on the given file, for whichever columns the user wants from the file (there's a column selection dialog), and it exports just the specific rows that are currently visible in the currently filtered and sorted listview. '''''Note: '''If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.''

====== ======

===== 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|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$)
mat Employee$=("") : mat Employee=(0)

read #Employee, using form$(Employee), key=f$(todo_employee) : mat Employee$, mat Employee nokey Ignore
let s$(sio_EmployeeName)=Employee$(em_name)

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

dim Employee$(1)*1023,Employee(1),Employee

def fnInit_FilterTasks
let Employee=fnOpen("employee",mat Employee$,mat Employee,mat Form$,1)
fnend
def fnFinal_FilterTasks
Close #Employee:
fnend

fnInit_FilterTasks is run just prior to populating the listview, (after [[#Listview_Prepopulate|Listview Prepopulate]], and before the first record is read). fnFinal_FilterTasks is run just after populating the listveiw, (after the final row is read, and before [[#Listview_Prepopulate|Listview Postpopulate]]).

The name of the [[#fnInit_and_fnFinal|fnInit_ and fnFinal_ functions]] are based on the name of the filter function, but they never have a $ or any parameters, and they're cut off at the BR function name length limit at 30 characters, so fnFilterReallyLongLongName$ would become fnInit_FilterReallyLongLongNam and fnFinal_FilterReallyLongLongNa.

When you create a new Filter Function in the newest versions of ScreenIO, they're automatically created for you, and you simply have to put whatever code you want to run in them. You can add them to your existing filter functions yourself, if you follow the same naming convention.

These are the preferred method for populating listviews. They're better then [[#Listview_Prepopulate|Listview Prepopulate]] and [[#Listview_Prepopulate|Listview Postpopulate]]. However, [[#Listview_Prepopulate|Listview Pre/Post Populate]] will continue to work, for compatibility with existing programs.

fnInit_ and fnFilter_ were added in ScreenIO v91.

====== 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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Working with Listviews =====
ScreenIO does a number of things to make writing custom functions to work with listviews easier. The currently selected record in the listview is always in mat F$ and mat F, and the primary key of that record is in CurrentKey$. You can use the standard BR system function rec(DataFile) to determine the current record of the data file.

You can also use mat SelectedRecords and mat SelectedKeys$ to determine which row(s) are currently selected by the end user. This makes it a lot easier to work with multi-select listviews. And even if a listview does not allow multi-select, these arrays still work. They contain a single element and it points to the currently selected single row - the same thing you would find in CurrentKey$ and rec(Datafile). That makes it easy to create functions that work both for multi-select and non-multi-select listviews.

BR 4.3 introduced Filter boxes. In BR 4.3 you can use mat VisibleRecords and mat VisibleKeys$, to see which records are currently displayed. They'll contain every row if the listview hasn't been filtered or sorted. But if the user has filtered or sorted the listview, by clicking on the column headings or typing something into a filter box, then these arrays will contain only the rows that are currently visible on the list, and in what order.

=== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

=== Support for New Fileio Dates ===

ScreenIO Supports the [[FileIO_Library#Support_for_Dates|FileIO Date features]] and if a field has a Date format specified, ScreenIO will automatically use that information to read and write the date correctly, even if its stored in a date other then Julian. This enables you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

==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 [mailto:gabriel.bakker@gmail.com 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.

*Filter Functions now include the ability to specify an "Init" and a "Final" function, all within the same filter function file. Init is called automatically, just prior to populating the listview, and Final is called just after. This is similar to the Listview Pre and Post Populate functions but its a lot easier to work with them all in the same .brs file with the filter function that they apply to. When you generate a new filter function it automatically makes shells of these functions for you. Just put whatever code you want in them (v2.5).
*ScreenIO now closes the screenio and screenfld data files right after reading them. This makes it possible to update your customers without kicking them out of the system. You no longer have to worry about a file sharing error on these files when installing updates (v2.49).
*Added support for FileIO's new date field types. If a field is a date field then ScreenIO automatically treats it like a date and sets it as a Date field. Additionally, ScreenIO now supports a new custom function parameter showing which fields from the file are Date fields (v2.48).
*Added mat VisibleKeys$ and mat VisibleRecords to tell which rows are currently visible in the filtered listview (Requires BR 4.3+)
*Fixed the Generate Screen function to use Filter Boxes (v2.47).
*Changed Date processing so that if a year is not entered, it defaults to closest date rather then current year (v2.46).
*Fixed a bug with large fields larger then 255 bytes that was introduced with new Number processing functionality (v2.45).
*Added feature where putting "N" in for the CNVRT spec property forces them to enter only valid numbers (v2.42).
*Added ability to put in just "N" instead of having to put the whole spec "N 10" for the CNVRT spec property (v2.42).
*Fixed a bug in the Orphaned Functions list (v2.4)

*(Spring Conference 2017 Release, v2.3)
Added filter boxes for Screen Selection and Function Select
Added options to ini file to enable or disable them
setting_Load_Filter
setting_FunctionSel_Filter
Added Version Number to Comments in Program
Made fnDesignScreen callable as a function
Made File Layout List redraw every time so it reflects recent Layout Changes
Fixed a bug in the "Launch Screen in New Window" code
Added Screen Version field
Implemeneted fnClearLayoutCash (new Fileio Feature) to get realtime Updates to File Layouts
Fixed a compatibility issue for using Substitute to rearrange your folder structure
Added a better message for Out Of Date Helper Libraries
Began Tracking ScreenIO Version Carefully
(Spring Conference 2017 Release)

*mat VisibleKeys$, mat VisibleRecords which handle the keys and record numbers of all rows on the current listview that are Currently Visible (v91)
*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

[[Category:Utilities_Third_Party]]

ScreenIO Library

2018-09-18T16:57:26Z

Laura: /* mat VisibleRecords and Mat VisibleKeys$ */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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.

====== Special ScreenIO Date processing ======
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.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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"''.
**'''Mat VisibleRecords and Mat VisibleKeys$''' to tell which rows are currently visible in the filtered listview (v91,Requires BR 4.3+)

===== 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|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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== Mat VisibleRecords and Mat VisibleKeys$ =====
ScreenIO (v91) now also provides your custom functions with two new arrays, mat VisibleRecords and mat VisibleKeys$. These arrays work on a listview screen, and they contain the keys and record numbers of all rows on the current listview that are Currently Visible. If the user uses a filter box to filter the listview, or sorts the columns in the list, these arrays update in real time, telling your functions exactly which records are currently visible in the list, and in what order.

Going along with that, there is a new function called ExportCurrentFileCSV, which exports any (user selectable) fields from the data file in a CSV format, for any records that are currently displayed on the list, taking into account the current filters and sorts. It works like the old ExportListviewCSV function except that it enables the end user to select which fields they want to export, and they can choose from any in the file.

(If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.)

=== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

== Support for New Fileio Dates ==

This update adds support for the new FileIO Dates to ScreenIO, and it also adds support for ScreenIO Date Processing to non-Julian date formats. This will enable you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

==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 [mailto:gabriel.bakker@gmail.com 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.

*Support for new FileIO Dates formatting (v91)
*mat VisibleKeys$, mat VisibleRecords which handle the keys and record numbers of all rows on the current listview that are Currently Visible (v91)
*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

[[Category:Utilities_Third_Party]]

ScreenIO Library

2018-09-18T16:57:03Z

Laura: /* ExitMode */

The '''ScreenIO Library''' is a Rapid Application Design tool that enables anyone to write complex user interfaces or complete custom programs, in a fraction of the time required by traditional development. We use it at [[Sage AX]] to write programs for our customers in record time, and we wanted to share it with you. For example, a fully functional File Maintenance program can now be created in half an hour. A zoom function or any other "single screen" program can be created in minutes.

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

[[#ScreenIO Runtime Engine Library Functions|ScreenIO's fnFm Parameter List]] 
[[#ScreenIO Events|Custom Function - Events]] 
[[#Writing Screen Helper Functions|Custom Function - Parameters]] 
[[#Keyboard Reference (Undo/Redo, Copy/Cut/Paste and more)|Keyboard Reference]] 
[[#Working with the ScreenIO Loading Icon|Animations]] 
[[#ExitMode|ExitMode]] 

Using ScreenIO, the programs you create, called "screen functions", integrate directly with your existing BR software and database and can be used to easily and impressively extend your existing software. Or you can use ScreenIO to design new software from the ground up, faster then you ever imagined possible.

They're called "Screen Functions" because each one represents a piece of your User Interface, and they can be called from your existing software as Functions or run as standalone BR programs.

You can run your Screen Functions in their own windows, or use them as part of an interface in your existing programs. Or you can place several screen functions together on tabs easily using the included run.br library. Some of our customers use Screen Functions to quickly spruce up the look and feel of programs designed and written for older versions of BR, with modern new gui controls.

The benefit of using ScreenIO to extend your Business Rules software is that you can quickly modernize your interface in your important programs and very rapidly develop new programs, while leaving the backbone of your software, all the unseen processes and rarely used programs, working exactly the way they have been reliably working until now. This lets you focus your development on your most important projects and get results now.

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 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.

== 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.

=== 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.

==== Calling your screen from an existing non-gui program ====

Calling a screen from a Non Gui program is the same as calling it from a GUI program. When a ScreenIO screen loads, the first thing it does is check if Gui is on. If its not, then it saves everything on the screen, and then turns GUI on to run your ScreenIO screen. When your screenio screen finishes running its closed, and the previous state of the screen is restored. GUI is turned off, and the text that was there is printed back on the screen.

If you're using BR 4.2 or higher, thats all you need to do. If you're using BR 4.1 and GUI OFF and you have a non-standard sized screen (not the default of 24 x 80), then you'll also have to set env$("screenrows") and env$("screencols").

==== 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|ExitMode]]" is triggered, either from one of the events, or by pressing the ESC key to trigger an [[#ExitMode|ExitMode]] of Cancel (by default), or the ENTER key to trigger an [[#ExitMode|ExitMode]] of Select (by Default).

Once a Screen Function Event has been triggered that sets [[#ExitMode|ExitMode]] to one of the various valid exit modes, the screen is exited, and depending on [[#ExitMode|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).
**TextBoxes
**CheckBoxes
**SearchBoxes
**Radio Buttons
**Filter Boxes
**Combo Boxes

*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|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.

== Screenio.ini ==
ScreenIO can be configured by creating a file named ScreenIO.ini and placing it either in the root folder or in the screenio folder.

Inside this text file you want to place a small snipped of BR code setting the values for each of the setting variables listed below.

Here is a list of all the screenio.ini settings (which can also be found at the top of the screenio source code), along with their default values.

Setting_EnableLogging=0
setting_FileIOPath$="fileio"
setting_ScreenIOPath$="screenio"
setting_ClockPath$="clocks\clock"
setting_ImagePath$="images"
setting_ScreenFolder$="screenio"
setting_ClickToMove=1
setting_PreviewListviews=1
setting_RealtimeFilters=0

If any of these are left out of your .ini file (or if your ini file is not found) then the defaults listed here are used instead.

=== EnableLogging ===
This enables automatic logging via fileio's log function. See the FileIO documentation for more details.

=== FileIOPath$ ===
This specifies the path to your copy of FileIO.

Note: Once you start using non-standard paths, it gets pretty tricky, so I would recommend sticking with the defaults. But if you have to change it, there are several other BR vendors who are successfully using it with nonstandard paths, by setting these settings properly.

=== ScreenIOPath$ ===
This is the path and filename of your copy of screenio. See note above regarding nonstandard paths.

=== ClockPath$ ===
This is the path to your clock files, used for the screenio loading animation.

=== ImagePath$ ===
This is the path to your screenio images folder, used for drawing the movement grid and the search icons.

=== ScreenFolder$ ===
This is the folder to store the compiled screen helper libraries.

=== ClickToMove ===
This allows you to turn off the automatic drawing of the movement grid, by setting it to 0. (You can always redraw the grid at any time by pressing the F6 key.) Also, you can turn it on for the duration of the current session by using the Windows Dropdown Menu "Tools".

=== PreviewListviews ===
This allows you to turn off the automatic preview of the listview data, to save time during design. You can always change this setting later using the Tools menu.

=== RealtimeFilters ===
This is the setting to use your listview filters when in design mode. You really should leave this setting off, because if there are any bugs in your filter functions, it'll make the designer crash, potentially causing you to loose the latest changes to the screen you're working on.

For that reason, this defaults to off, and I recommend you leave it off. If you want to test your filter functions, run your screen instead.

== 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) ===
[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]

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.

==== Saving Your Screen ====
As in any development tool, it is very important to save your work as often as you think of it. There is no automatic save functionality built into ScreenIO.

To save your screen, it has to at least have a Screen Name. Once you've entered a Screen Name, you can save your screen using the Windows "File" dropdown menu (described below). Just click "File", then select "Save".

Because of the nature of ScreenIO, often times you are typing in commands that get turned directly into BR code. As such it is impossible to guarantee that the ScreenIO designer will not ever encounter errors.

If you encounter an error in ScreenIO while designing your screen, you can often times get past the error by typing "continue". If you do, save your screen as soon as possible. Then use FileIO's datacrawler to fix the problem in the screen that led to the crash.

===== Screen Backups for Multi User Environments =====

In multiuser environments, even when source control is properly used, it is possible for one person to accidentally overwrite another persons screen. If that happens, do not fear. Look in the "backup" folder in the screenio copy on your local copy and you'll find a screenname.sio file that is a backup of your screen the last time you saved it.

By checking these backups into your Source Code Repository, you gain version history of your screenio screens.

At any time, you can "import" one of these ".sio" files back into ScreenIO by using the "Import" option in the Windows Dropdown Menus. You'll want to check the name of the imported screen, and then save it using File -> Save, right away.

==== 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.
*Save and Test
Save and Compile and Test your screen with one click.
*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 unnecessary 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.
*FileIO
This launches a copy of FileIO running in its own window, so you can interact with your data files if you need to, and so you can access the FileIO Template Code Generation Wizard.
*New Window
This launches another copy of ScreenIO running in its own window so that you can edit two screens at the same time, or take advantage of a multiple monitor environment.
*BR Console
This loads a new copy of BR by itself. (Note that it uses your standard brconfig.sys file so if you have any Startup Program instructions there, your startup program will still run.
*Explore Local Folder
This loads the current directory in Windows Explorer, so that you can interact with the file system, or make new file layouts, or whatever you need to do.
*Quit
Exits ScreenIO and closes BR.
===== 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.
===== Tools =====
Developer tools to help you with development in ScreenIO.
*Power Search
This is a powerful search tool, inspired and requested by Susan Smith. It searches all your custom functions, your screens themselves, and any additional folders of both compiled and noncompiled BR programs or even proc files, for any mention of the specified search string anywhere in your system.

Powersearch now also supports typing in any field from your database, in the format of prefix_subscriptname. For example, searching for cu_name in my copy of ScreenIO would return every piece of code and every screen element that uses the customer name field, and also the customer file layout itself.

*Code Explore
Opens a list showing all the custom functions that are used in your current screen. This is useful for getting an idea of exactly what the current screen contains/is built out of.
*Generate Screen
This wizard asks for a data file, then queries you for which fields to use, and generates a Listview, an Add/Edit, and/or a Combo Listview/Add/Edit screen with almost everything in place and done for you. You use the Generate Screen Wizard to get you most of the way there, and then all you have to do is modify the control positions, add validation functions if necessary, and test your screen.
*Generate Code
Generates the BR code to create a standard BR input fields statement to do your current screens input. Note that this does not create a ScreenIO Screen as BR code because it doesn't include your custom function processes.

This feature is primarily useful for when you have to design a piece of code the old way, and just want to use ScreenIO to help you get the appearance right, and then have ScreenIO Generate your field specs for the BR program you're writing.
*Orphaned Functions
Displays a list of all functions in your functions folder that are no longer in use by any screens.

===== 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 Add/Edit Buttons
This asks you for the target Edit screen and adds buttons to a Listview screen that tie to the selected target Edit screen, for Adding new records or Editing the current record.

You can accomplish the same thing by adding individual buttons and customizing their captions, positioning, and click event functions, but this does it all for you in one click.
*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 Combo Box
Adds an empty Combo Box to your screen. You'll need to specify a combo "Populate" function to populate the data in your combo box. This doubles as a validation function so you can also validate and respond to the user changing the selection in the same function. Other then the populate function, combo boxes are just like regular input fields.
*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 Filterbox (4.3+)
Adds a BR 4.3 Filter Box to your current screen. These work like Search Boxes, except they narrow the results in the listview in real time as the user types in the filter box.
*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.
*Add Frame
Adds a frame, which is actually a child window to your screen. The frame can have a border or not, and it can have a background image or not, which allows you to place fields on top of a background image.

If you move the frame, all the controls in the frame move too. Therefore I recommend building your frames first and then placing the fields in them.

You can always resize your screen to make it bigger temporarily, so you have space to work with when putting controls on your frame.
*Add Screen
This adds a ScreenIO Screen as a child screen on the current screen. The child screen is loaded and displayed when the current screen is run. If the user clicks on the child screen, then screenio calls the child screen for processing, and when its done, returns to the parent screen and updates properly.

If they're inside the child screen and click on a field in the parent screen, the child screen closes automatically and control is returned to the parent screen and whatever they click on is enacted.

*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
*Draw Movement Grid
This draws the Movement Grid to aid in moving your controls. This way you can disable the movement grid by setting the option in your ini file, and draw it only when needed. The F6 key is a shortcut to draw the movement grid.
*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.
*Configure Additional Info
This opens a window to configure additional screen level options that didn't fit on the main ScreenIO screen Attributes window.
*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.
====== 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.
====== 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.
====== 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
====== 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.

====== 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.

====== Combo Box ======
To add a combo box, simply click the Add Combo Box button. Then you can tie it to a field in your data file (if you like) or give it a name so it becomes an S$ field.

Then you'll need to write a Combo Box Populate Function so that ScreenIO can populate your new combo box.

This is a special function that accepts a parameter called mat ReturnData$. You size mat ReturnData$ to the number of elements you want in your combo box, and set the elements, and you're done. ScreenIO will run your populate function and everything you return will be placed inside the combo box.

One thing to be aware of, is your combo box populate function doubles as a traditional Validate function, so you'll want to return true in order to allow the user to change the combo box selection. You can also perform validations and return true only when they change it to something valid.

For example:

def fnPopulateApproval
mat returndata$(3)
let returndata$(1)="None"
let returndata$(2)="Approve"
let returndata$(3)="Hold"
let fnPopulateApproval=1
fnend

====== 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.
====== 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.
====== Filter Box (4.3+) ======
This button adds a BR 4.3 Filter Box to your screen and ties it to the current control. This filter box is just like a list box, except that as the user types, the list is shortened in realtime to display only matching elements.

By default, a case insensitive fullrow search is performed, but you can change that in the filter boxes attributes window.
====== 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.
====== Picture ======
This button adds a Picture object to your new screen. Pictures, like buttons, also have a click event.
====== Frame ======
This button adds a frame to your screen. Frames are built off of BR Child Windows, and you can place controls on them. They can optionally have a border, and/or a background image, allowing you to place fields on top of a picture.

It is recommended to place your frames first and then place controls in the frames. This is because, as you move the frames around the screen, they move any controls around with them. So if you place the controls first and try to move the frame on top of them, you'll collect all the controls on top of each other along the leading edge of the frame.
====== Screen ======
This button adds a child screen to your screen. This screen is displayed when the screen is drawn, and if the user clicks on it, its automatically called and run for you.

If the user then clicks on another control in the main screen, the child screen will be exited automatically (defaults to use AskSaveAndQuit if there's no listveiw on the child screen) and the action for the item they clicked on will be carried out in a natural fashion.
====== 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 Library]]s 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.

[[image:Designer_-_Add_Edit_Screen_-_Field_Selection_Mode.jpg|thumb|800px]]
==== 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.

[[image:ScreenIO_Designer_-_Movement_Mode.jpg|thumb|800px]]
==== 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|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|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.''

[[image:ScreenIO_Designer_-_Control_Attributes_Window.jpg|thumb|800px]]

==== 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.

[[image:ScreenIO_Designer_-_Control_Attributes_Window_-_Closeup.jpg]]

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.

====== Special ScreenIO Date processing ======
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.

This is a very robust way to handle dates in your system. This supports the user entering in any format they find natural, and if they leave off the year, current year is assumed.

If the first character is a + or a -, then the number they entered is assumed to be a relative date, so they can also type +5 to say "five days from now", or +2w to say "14 days from now", or +3m or -1y, etc.

===== 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.

==== Listview Columns Editing ====
If you added a listview to your screen, then when you're done setting the listviews attributes and you press enter (or click on the listview again), you'll be taken to Listview Columns Editing Mode. This mode turns the listview temporarily into a grid where you can set the attributes for the individual listivew columns.

If you just added your listview, it will have an empty column in place, to give you something to click on when you're trying to position it. The first thing to do, is place the cursor in that empty column, and click the Delete Column button to remove that column from the list.

Next, while remaining in Listview Column Mode, click on the Fields listview and select one or more fields to place as columns on the listview, by either Enter or Double Click.

Use the legend on the left to see what each row of the listview means, and specify the attributes for each column in the corresponding rows.

You can also use the keyboard shortcuts Ctrl-Left and Ctrl-Right to move the current column (the column the cursor is in) to the left or the right.

==== 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 and 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 Screen 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.

====== Listview Read Event ======
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|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|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|ExitMode]], forcing ScreenIO to continue to process and forcing the user to fix the error before continuing.
====== Merge Event ======
This function gets called only as a result of selecting the "Dont Lock" checkbox for one or more of your screens. When you select that checkbox, BR record locking is disabled, allowing multiple users to edit the same data records at the same time. If that happens, its possible for one users changes to clobber another users changes.

When ScreenIO detects that this has happened (the file record on disk at the time of save is different then what it was when the screen was loaded) it attempts to merge the changes together using one of three methodologies. If AutoMerge is selected, then it attempts to keep the latest version of all fields, keeping the changes made by both users, and if both users changed the same field, it just goes with the current users changes assuming they're newer because they clicked "save" last. It is recommended to only use the AutoMerge functionality for really simple data files.

If AutoMerge is not selected, it next looks to see if you specified a Merge Event function. Your Merge Event function will then be run to merge the two data elements together.

If you didn't select AutoMerge OR a Merge Event function, then it attempts to do a Postit Note Merge, by reloading the screen with the other persons changes, and listing all your changes in little postit notes next to the fields, that you can click on to enter your changes again.
====== NoKey Event ======
This function is run when a key cannot be found. Its here so that if you don't like the standard ScreenIO "key not found" error, you can write your own.

====== Listview Prepopulate ======
The listview prepopulate function runs before your listview is populated, so you can open related files, reset counters, or anything else you need to do every time prior to repopulating the listview.

====== Listview Postpopulate ======
The listview postpopulate function runs after your listview population is complete, so you can close those same files, evaluate the counters, or whatever else you need to do each time your listviews finish populating.

====== 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.
===== Default Event Functions =====
ScreenIO Now supports the specification of default event functions, which can be used by simply creating a folder called "defaults" under your "function" folder, (so "function\defaults") and placing the event functions you want in there with the appropriate name.

Make these default functions by creating a regular event function in one of your screens, so that ScreenIO sets it up the right way. Then clear it out from that screen and move it into your "function\defaults" folder and rename it to the correct name for the event type that you want it to be.

If the file is called enter.brs, for example, then it will be run IN ADDITION TO the normal enter event, for all of your screens.

This can be used in conjunction with the new screen level UserData$ field, to make system wide event functions that run for just the screens you want. Simply test the value of ScreenIO$(si_userdata) at the beginning of your function and react accordingly, then set UserData$ for each of your screens that you want the function to apply to.

Every Screen Level event function is supported:
*enter.brs
*init.brs
*read.brs
*load.brs
*write.brs
*wait.brs
*locked.brs
*merge.brs*
*mainloop.brs
*nokey.brs*
*prelist.brs
*postlist.brs
*exit.brs

<nowiki> * </nowiki>Nokey and Merge default event functions run only when the screen does not have a specific function selected. All of the others run ''In addition to'' any function selected in the screen.

===== 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|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|Validate Field Function]].
====== Filter Event ======
The Filter function is one of the most versatile functions. 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.

If your filter function returns a valid color code, (ex: "/#0000FF:000000" a hex code or "[HILITECOLOR]" an attribute substitution statement from your brconfig.sys), then the row is colored that color.

If your filter function returns the word "STOP", then screenio stops reading the data file and also doesn't include the record in the list. You can use this function to make listview functions run faster.

To do so, you want to read the record by an appropriate key. (Keep in mind you can set the Read Key for the screen in the Window Attributes in the top left corner.) Then, in your preListview event function, use a [[Restore_File|RESTORE]] command to position the file pointer at the first record to display. Finally, in your filter function, when you detect that you've moved past the last record that you want to display, return "STOP".

For an example of a listview filter function, See [[#Listview_Filter_Function|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|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.
*'''mat ControlSpec$''' - This is an array showing the calculated output spec for each of your controls. You can access it like: ControlSpec$(ctl_Listview) to get the control spec of a field named "listview".
*'''Key$''' - This is the Key that we called the screen with
*'''[[#ExitMode|ExitMode]]''' - Set [[#ExitMode|ExitMode]] to non-zero to cause your screen to exit.
*'''RepopulateListviews''' - Set this value to True in your function to cause ScreenIO to repopulate the listviews when its done processing your custom function code.
*'''RedrawListviews''' - Set this value to True in your function to cause ScreenIO to redraw the whole listview, from the headers on up, when its done processing your custom function code.
*'''RedrawFrames''' - Set this value to True in your function to cause ScreenIO to redraw the each of the frames on your screen.
*'''RedrawScreens''' - Set this value to True in your function to cause ScreenIO to redraw any child screens that are a part of your screen.
*'''RepopulateCombo''' - Set this value to True in your function to cause ScreenIO to rerun all your "RepopulateCombo" functions and repopulate all the combo boxes on your screen.
*'''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.
*'''DisplayOnly''' - This boolean flag tells if the screen is currently running (accepting input) or if its just being displayed. You can use it to trigger user interface changes to let your users know what part of the program is active at the given moment.
*'''Selecting''' - This is a parameter that can be passed into ScreenIO when calling a screen for your own purposes. Its not used by ScreenIO at all. You can use it to signal a multipurpose screen that it should be used in Selecting mode, and then make your custom functions react accordingly. Its available in your custom functions so that you can test its value.
*'''''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"''.
**'''Mat VisibleRecords and Mat VisibleKeys$''' to tell which rows are currently visible in the filtered listview (v91,Requires BR 4.3+)

===== 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|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.
*ExitMode=Reload... will not save but will reload the screen.
*ExitMode=AutoReload

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
let Reload=6
let AutoReload=7

===== mat VisibleRecords and Mat VisibleKeys$ =====
ScreenIO (v91) now also provides your custom functions with two new arrays, mat VisibleRecords and mat VisibleKeys$. These arrays work on a listview screen, and they contain the keys and record numbers of all rows on the current listview that are Currently Visible. If the user uses a filter box to filter the listview, or sorts the columns in the list, these arrays update in real time, telling your functions exactly which records are currently visible in the list, and in what order.

Going along with that, there is a new function called ExportCurrentFileCSV, which exports any (user selectable) fields from the data file in a CSV format, for any records that are currently displayed on the list, taking into account the current filters and sorts. It works like the old ExportListviewCSV function except that it enables the end user to select which fields they want to export, and they can choose from any in the file.

(If you want to only give them access to certain fields, make a copy of your layout and mark out whatever fields you want to hide by making them "X" fields. Then use this layout for your ScreenIO screen and they will only have access to the remaining fields listed in it.)

=== 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:

#) 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.
#) Rows (5) - The size of the animation window in Rows.
#) Cols (10) - The size of the animation window in Columns.
#) 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.
#) 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.

==== Listview Column Editing Mode ====
You can use the following keys to reorder the columns in your listview.

Ctrl-Lf ... Move the column to the left
Ctrl-Rt ... Move the column to the right

==== 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
F6 ...... Draw or Redraw the Movement Grid
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 [[#Click_to_Move_Control_Movement|Mouse Movement]].''

== Support for New Fileio Dates ==

This update adds support for the new FileIO Dates to ScreenIO, and it also adds support for ScreenIO Date Processing to non-Julian date formats. This will enable you to use ScreenIO Date fields for your legacy data files that stored their dates in another format.

There is now a new Control Attribute called "Disk Date Format" that, if specified, tells ScreenIO to unpack the field to Julian before processing it. It works along with the DATE Conversion Spec Control Attribute, (which previously only worked with dates stored as Julian), to enable a lot of useful date editing features.

[[File:Dates1.png]]

This works on listviews too, so you can now specify these two fields, to make dates show as, for example "January 24, 2018", even if they're saved on disk as "MMDDCCYY". Or, like in the following example, as "MM/DD/CCYY" even though they're saved on disk as "MDY". Specifying the date format this way, makes the listview column sort correctly in date order, no matter what the displayed format is.

[[File:Dates2.png]]

Note: If you specify the Date format in your file layout, following the instructions for FileIO above, then ScreenIO detects that and fills in these fields for you, automatically enabling Date processing.

ScreenIO also has a new INI setting you can control:
CODE: SELECT ALL
setting_DateFormatDisplay$="m/d/cy"

This determines the default date format to use when you add fields that are marked in FileIO as Date Fields. This is the format you want your end users to see and interact with.

==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 [mailto:gabriel.bakker@gmail.com 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.

*Support for new FileIO Dates formatting (v91)
*mat VisibleKeys$, mat VisibleRecords which handle the keys and record numbers of all rows on the current listview that are Currently Visible (v91)
*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

[[Category:Utilities_Third_Party]]