<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <title>StudioWorks - About (All Contents)</title> <meta name="keywords" content="omnis studio, raining data, studioworks documentation" /> <link rel="stylesheet" type="text/css" href="http://www.studiotips.net/css/codedoc.css" /> <link rel="stylesheet" type="text/css" href="http://www.studioworks-dev.net/css/codedoc.css" /> </head> <body> <div id="container"> <a href = ../index.html > Sw4 </a> &nbsp > &nbsp <a href = index.html > About </a> &nbsp > &nbsp About (All Contents) <a name="studioworks" /> <h2>StudioWorks</h2> StudioWorks version 4 is an exciting new release of StudioWorks. Writing the StudioWorks version 4 release took close to two man years. (In addition to several man years invested in the earlier versions of StudioWorks.) Omnis Studio version 4 provided some great new features which could be utilized in StudioWorks version 4. One example is the addition of a $userinfo property which was added to every class and object in Omnis Studio. StudioWorks version 4 stores meta-data for each schema class column in a row variable which is then stored in the $userinfo property of the schema class column. Many new time saving developer tools have been added to make StudioWorks version 4 a truly rapid application development framework. <a name="features" /> <h2>Features</h2> The following is an overview of the features in StudioWorks. This is not an all inclusive list of the features in StudioWorks. <a name="sqlmetadata" /> <h3>SQL Meta-Data</h3> The schema classes in Omnis are used to map list and row variables in your application to the SQL database. Each schema class is mapped to a database table and the schema class columns are mapped to database table's columns. The Omnis schema classes keeps track of the column name, datatype, whether on not the column is a primary key column, and whether or not null values are allowed. However, the Omnis schema classes are not able to keep track of whether or not the column is indexed, if it is a foriegn key and if so what table and column the foreign key references, and other column constraints. The StudioWorks SQL Meta-Data Editor allows you to store addition information (meta-data) about each schema class column. The meta-data is kept in a row variable which is stored in the $userinfo of each schema class column. <img src="./images/sqlmetadataeditor.gif" alt="sqlmetadataeditor.gif" /> The StudioWorks SQL Meta-Data Editor not only stores database meta-data, it also stores GUI meta-data. The GUI meta-data allows you to preset if and how the column will be displayed in lists and entry fields, when and how users can edit the field, whether to include the field in prompts, default sorting, etc. Even the label, tooltip, and abbreviation (for list and report column headings), are stored with the GUI meta-data. Storing the label and tooltip text in the meta-data ensures that where ever the column is displayed in a window or on a report the label will be consistent and if it is used in several windows you only need to change it in a single location. <a name="databaseadministrator" /> <h3>Database Administrator</h3> Setting up and keeping your database in sync with your Studio application can be a lot work. The Database Administrator tool makes it easy. Using the SQL meta-data the Database Administrator can intelligently add tables, add columns, alter column datatypes, add indexes, add primary and foreign keys, set constraints, and collations. <img src="./images/databaseadministrator.gif" alt="databaseadministrator.gif" /> In an ideal world the SQL92 standard would be the same for every DBMS, but unfortunately we aren't living in an ideal world. The SQL used to rename a column for one DBMS is not necessarily the same as the next. The database administrator is structured so that custom SQL can easily be added for each DBMS. <a name="signinwindow" /> <h3>Sign In Window</h3> StudioWorks provides you with a prebuilt Sign-In (Logon) window. <img src="./images/signinwindow.gif" alt="signinwindow.gif" /> The code that is included with the Sign-In window supports using the DBMS users security as well as the list of application users which you store a table in the database. The application users table is where you would store the user's formal name, group memberships, user security settings, email address, etc. The Sign-In window defaults to the last session. Users can change session settings. <a name="sessionsmanager" /> <h3>Sessions Manager</h3> Getting the session settings correct for different DBMS back ends can be difficult for developers, let alone end users. The StudioWorks Session Manager assists both developers and end users. <img src="./images/sessionsmgrfrontbase.gif" alt="sessionsmgrfrontbase.gif" /> Templates are provided for each DAM with text explaining what information to fill in which field. If the Omnis DAM is select the fields which don't apply are hidden and the host name field is resized accordingly. <img src="./images/sessionsmgromnis.gif" alt="sessionsmgrfrontbase.gif" /> Session settings are automatically saved to the local preference data file. <a name="concretizer" /> <h3>Concretizer</h3> StudioWorks reduces development and maintenance time by generating window instances on the fly based on the SQL meta-data. Lists, entry files, labels, and tooltips are added to windows the instance they are opened. The disadvantage of generating window instances on the fly is that window instantiation time suffers. There is a performance hit which the user experiences. To overcome this the Concretizer creates 'concrete window classes' for each of the window instances. Prior to releasing a runtime version you 'runtimize' the window instances. The runtimized window classes are put in a separate library which is then released with the development libraries. If a runtimized class is available it will be used. <img src="./images/concretizer.gif" alt="concretizer.gif" /> The Concretizer can also be used to create a developer window class that is mapped to a schema class or a query class. The developer simply selects the window instance in the Concretizer and clicks the Developerize button. A window class with all of the fields and labels is created in the same library as the schema or query class. The window class can then be modified by the developer. <a name="errorhandler" /> <h3>Error Handler</h3> Object-oriented programming places code in visual and non-visual classes. Visual classes are windows, menus, toolbars, reports, and remote forms. Non-visual classes are table classe, object classes, and task classes. By making a clear separation between visual and non-visual classes your classes can be much more reuseable. Non-visual classes used by a window class can also be used by a remote form, or even a web page that communicaes with a remote task. Non-visual classes can not have prompts, okay messages, working messages, or error messages. The dilema we run into is what to do inside a non-visual class method when it hits an error. How can it easily communicate the error back to the visual class that called the method in the non-visual class. The call quite often will have been passed through several different methods. One solution is to develop a large series of error codes and return the appropriate error code back to sender, however developing and remembering a table of error codes is a lot of work to create and maintain. And how do pass an error code back to a method which is expecting a list or a result value? The solution to all of this in StudioWorks is the error handler object. The error handler sits on the sidelines waiting for any method to log an error. The first parameter sent the log message is a reference to the method where the error occurred. Additionally the error message text, optional details, and an optional error code are sent by the method where the error occurred. The method where the error occured return false or null as may be appropriate to its sender. The error handler immediately writes the error to a log file and stores the error in a list. When the visual object where the request originated receives a returned false or null value it sends a message to the error handler asking it for the last error which was logged. The visual object then prompts the user with the error or makes an appropriate decision based on the error code. By making a clear distinction between visual and non-visual classes and using the StudioWorks error handler you are able to easily develop non-visual classes which can be used by different visual classes. <a name="iconsbrowser" /> <h3>Icons Browser</h3> Finding the icon you need in the Omnis icons can be tedious and time consuming. Keeping track of icons you create or trying to share icons among different libraries is a hassle. Remembering the icon by its number isn't much fun. The StudioWorks Icons Browers solves all of the above. <img src="./images/iconsbrowser.gif" alt="iconsbrowser.gif" /> The icons are stored in a single library. You assign a name and number to each icon. You can also assign search words and synonyms in a search list. When you need to find an icon, you open the Icons Browser, enter a search word, and hit return. The Icons Browser displays a list of icons which march or are related to your search word. An icons object in the StudioWorks icons library can be instantiated by any of your application's libraries. You can ask the icons object to return to you the iconid of any named icon. Do oIcon.$retIconID('BookPencil') Returns IconID ;; The iconid 2143 will be returned. The StudioWorks icons library makes it easy for StudioWorks members to add icons and share icons. <a name="preferences" /> <h3>Preferences</h3> Most applications need to store various user preferences on the local client computer. It make for a nicer user experience if your application remembers the last user ID, the last session settings, the last language, etc. when the user reopens your application. The StudioWorks preferences object provides you with this functionality. You simply add the preferences you wish to store on the local client computer to the preferences schema list definition. StudioWorks adds the appropriate getter and setter methods to the preferences object. When you close your application StudioWorks looks for a local preferences Omnis data file, and if necessary creates it, and then saves the preference values to the file. When you reopen your application StudioWorks loads the preferences from the local Omnis data file into the preferences object where they can easily be access by the your application code. The local preferences data file is stored away from your application to that reinstalling the application or updating it won't wipe out the user's preferences. <a name="prompts" /> <h3>Prompts</h3> The built in OK, Yes/No, No/Yes, Prompt for input prompts which come with Omnis Studio are a bit behind the times. With a 255 character limit your messages are often truncated. If you want to prompt the user with list, radio buttons, check boxes, mutliple inputs... you have to create your own prompt windows. StudioWorks version 4 has flexible prompt window which supports unlimited length text message, an option for including additonal message details in small text, list prompts, any mix of radio buttons, check boxes, and multiple inputs in a single prompt. Often used prompts such as Delete Record? or Save Changes? are already built for you and designed to look good on multiple platforms. <img src="./images/promptsave.gif" alt="promptsave.gif" /> The above prompt was opened with the following line of code: Do prmpt.$promptSave('Save Changes?) Returns ButtonPressed <a name="referencesmodule" /> <h3>References Module</h3> Often times in application development you need a simple lookup with optional or mandatory values which the user can enter in a field. (e.g. Mr, Ms, Mrs, Dr, Lord, Duke,...) Hard coding these into your application is not a a good idea. Creating a table in your database for each of these is overkill. Another scenario is that you might need a counter to keep track of the last purchase order, last invoice number, last customer ID, or last primary key assigned in each table. The References module is the solution for these and many more situations. You simply declare a unique group/subgroup combination of values (e.g. PO/PONum), a datatype (integer), and a reference type (counter). When you need the next PO number you simply an appropriate message to the references object: Do refs.$retNextNum('PO','PONum') Returns NextPO or for a lookup list of name titles Do refs.$retLookupList('NameTitles','UK') Returns UKNameTitlesList There's plenty more than you can do with the references library. Store user preferences for reports, user defined businesss rules, soft coded SQL query text for reports,... the list goes on and on. <a name="reportbuilder" /> <h3>Report Builder</h3> Making end user reports can be a time consuming job. Adding fields to a report class, positioning, sizing, and setting the field properties, adding report titles and column headings... use up your valuable time doing rather low level work. Time better spent elsewhere. The report builder object is able to generate reports on the fly for you. The StudioWorks Report Builder creates a report class and based the SQL meta-data of the schema or query class used to fetch the report records it adds the fields, labels, and titles to the report class and then prints the report. The developer can further customize the report class after it has been generated by the report builder. The column heading labels use the same text as the headed list heading which is all sources from the meta-data. <a name="security" /> <h3>Security</h3> Most applications require some form of security. Control over which users can access which windows and what reports. Which users can view, edit, insert, or delete records in which tables. If the DBMS supports grant and revoke privileges keeping your application's users in sync with the database privileges can be a lot work. Administering security on a user by user basis can be time consuming and require constant updating. Being able to put users into groups and then administernig security on a group by group basis is simpler and more practical. The StudioWorks Security Manager helps out with all of the above. Users can be added to groups. Both users and groups can be assigned schema class, window instance, and report instance privileges. The schema class privileges can be synchronized with the database. Users who are members of multiple groups are given the highest level of authority for each schema, window, and report for the summary of all the groups they are in. <img src="./images/securitymanager.gif" alt="securitymanager.gif" /> The Security Manager window provides you with simple user interface and can be instantiated as a subwindow in one of your own window classes. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />Report instance security and DBMS synchronization is not yet implemented as of 2005-04-20. </div> <a name="stringtables" /> <h3>String Tables</h3> If now or at some point in time you wish to sell your application in another county, or even different region of one country, you'll need to be translate the labels, tooltips, column headings, menus, and window titles throughout your application. This can be a huge job. StudioWorks utilizes OMST's string tables for the labels, tooltips, column headings, menus, and wnidow titles. For the first language you develop the text is stored in the SQL meta-data. <img src="./images/stringtablesviewer.gif" alt="stringtablesviewer.gif" /> When it comes time to translate your application to another language you simply export all of the string table IDs and the current language text to a tab delimited file. The translator simply needs to add a column for each additional language and enter the translated text in that column. The file with the additional columns of translated text is added to the startupsettings folder and loaded by StudioWorks during startup. End users can localize your StudioWorks application by changing labels and tooltips to suit their business. One business refers to 'clients', another calls them 'customers'. Localized labels and tooltips are stored directly in the customer's database and loaded during startup. <a name="quickstarttutorial" /> <h2>Quick Start Tutorial</h2> This section covers the steps to follow for getting started with writing a new application using StudioWorks. This quick start tutorial assumes that you have already installed Omnis Studio v4.x and are familiar with creating libraries, classes, and writing notation in Omnis Studio. If you are not familiar with Omnis Studio read the PDFs that come with Omnis Studio and go through the StudioTips Basics Tutorial. If are not familiar with SQL (Sequential Query Language) read some books on SQL to learn the basics of SQL. The StudioWorks framework will jump start writing new applications in Omnis Studio, but you need to know the basics. (Omnis Studio, writing notation, SQL) Print the StudioTips and StudioWorks Naming Conventions. Read them. Keep them handy near your desk. Learning, understanding, and using the StudioWorks naming and coding conventions will make it much easier to follow the code in StudioWorks. It is highly recommended that you print this tutorial from the on-line version before attemping to do it. You can check off the steps and add your own notes to your printed copy as go through the tutorial. <a name="settingfileandlibrarynames" /> <h3>Setting File And Library Names</h3> The first step is to set up the files and libraries for your new application. <ol> <li>Download and unzip the lastest StartNewApp zip file from the StudioWorks FTP server.</li> <li>Decide on a 2 or 3 letter lower case acronym for your company name which you will use as a prefix for your library names. e.g. Vencor Software uses the 2 letter acronym vs for prefixing library names. The company prefix az will be used in this quick start guide. You can substitute your own company 2 or 3 letter acronym whenever you see az in this quick start tutorial or use az for the tutorial. </li> <li>Decide on a short name for your application. The short app name Drivers will be used in this quick start guide. You can substitute your own short app name whenever you see Drivers in this quick start tutorial or use the app name Drivers.</li> <li>Rename the unzipped StartNewApp folder to Drivers. The Drivers folder is referred to as the APP folder. The entire application is enclosed inside the APP folder.</li> <li>Inside the Drivers folder, rename open_myApp to open_Drivers</li> <li>Inside the APP/libraries folder, rename myAppMain to azDriversMain</li> <li>Inside the APP/libraries/modules folder, rename myAppModule to azDrivers</li> <li>Inside the APP/libraries/modules folder, rename mySysAdmin to azSysAdmin</li> <li>Inside the APP/libraries/modules folder, delete all of the other libraries. They are just demo modules.</li> <li>Inside the APP/data folder, rename myAppData to DriversData</li> <li>We have renamed the files, but we also need to change the $defaultname property of each library before we open the Drivers application.</li> <li>Open your developer version of Omnis Studio.</li> <li>Under the File menu select Open Libraries... and navigate to the azDriversMain library but do not click the Open button. Select the file but don't open it up yet.</li> <li>Hold down the <kbd>Ctrl/Cmnd</kbd> key and then click the Open button. This opens the library without running the Startup_Task</li> <li>F2 Browser > select the myAppMain library > F6 Properties > Default tab. Set the $defaultname property to <kbd>azDriversMain</kbd> <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />With multiple library applications it is important that the library name remain consistent. If you don't set the $defaultname property, the library name will change if the user changes the file name. Not a good thing! </div></li> <li>F2 Browser > select the myAppMain library > click Close Library</li> <li>The Startup_Task in each module doesn't do anything so we can open those modules normally.</li> <li>Under the File menu select Open Libraries... and navigate to the azDrivers module and click the Open button.</li> <li>F2 Browser > select the myAppModule library > F6 Properties > Prefs tab. Set the $defaultname property to <kbd>azDrivers</kbd></li> <li>F2 Browser > select the myAppModule library > click Close Library</li> <li>Under the File menu select Open Libraries... and navigate to the azSysAdmin module and click the Open button.</li> <li>F2 Browser > select the mySysAdmin library > F6 Properties > Prefs tab. Set the $defaultname property to <kbd>azSysAdmin</kbd></li> <li>F2 Browser > select the mySysAdmin library > click Close Library</li> </ol>You are now ready to officially open the Drivers application. <a name="openingthedriversapp" /> <h3>Opening the Drivers App</h3> To help you get started with StudioWorks the starter app comes with a prepared Omnis data file which has some tables already created and records inserted. <ol> <li>Open the open_Driver library. This opens the azDriversMain library, which in turn opens all the libraries located in the APP/libraries/modules folder and the libraries at the first level in the APP/studioworks folder. The StudioWorks framework libraries are located inside the studioworks folder.</li> <li>All going well you will get to the Sign-In window. </li> <li>Enter user name: <kbd>SYS</kbd> and password: <kbd>pass</kbd>. Click the Sign-In button. </li> <li>All going well the My App main menu will be installed and the main window will be opened. Feel free to click on the various nodes in the main window treelist to view lists, edit records, insert new records, etc. </li> <li>My App menu > Programmer Menu > Programmer Workbench. This opens the StudioWorks Programmer Workbench window. The Programmer Workbench is command central for StudioWorks developers. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/tip.gif" alt="Tip" />Use the shortcut key combination <kbd>Shift+Ctrl/Cmnd+Z</kbd> to open the Programmer Workbench. </div></li> <li>Select the String Tables tab > String Tables _stb Schemas Editor tab</li> <li>Expand azDriversMain node if it isn't already expanded. </li> <li>Select the sMn_stb child node. (Click it twice of the list doesn't refresh)</li> <li>Change the description for the AppName column from My App to Drivers. StudioWorks will now translate AppName to Drivers where ever AppName is used as a string table ID.</li> <li>Tab out of the label field. The main menu title should change from My App to Drivers. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/tip.gif" alt="Tip" />If you wish to change an ID, click the yellow edit pencil in the ID column heading. This enables the ID fields in the grid. Click the pencil again to disable the ID column. </div></li> </ol> <a name="addingatable" /> <h3>Adding a Table</h3> The StudioWorks starter app comes with a set of tables and window classes which links contacts to towns/cities, and town/cities to states/provinces and countries. For our Drivers app we will add a table to store autos which are linked to auto types. We'll start with the parent table, Autotype. Create the schema class <ol> <li><nav>Programmer Workbench</nav> > SQL Meta-Data tab > right-click on the azDrivers node of the treelist > select New Schema...</li> <li>Enter the name of the new schema, <kbd>sAutotype</kbd>. StudioWorks creates the sAutotype schema for you.</li> <li>Select the sAutotype node in the treelist, and click the SQL Class Editor tab. StudioWorks created the new schema for you with various default values and colulmns which you can now modify. The Class Name, Description, and Server Table Name are properties of the sAutotype schema class. The rest of the fields in the window are meta-data. StudioWorks store the meta-data in the oModuleData object class of each library. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />The power of StudioWorks lies in the meta-data. The fields in the meta-data editor have tooltips which give more information about the field. If you are unsure about a certain meta-data field hover your mouse over the field and read the tooltip. </div></li> <li>Change the Label (Singular) from Autotype to <kbd>Auto Type</kbd>. Tab to the next field. Notice that they Label (Plural) automatically changed from Autotypes to Auto Types. StudioWorks tries to set the plural value for you automatically. The label singular is used for the window title when you are editing a record of that table. The label plural is used for the window title when you are looking at a list of records of that table.</li> <li>Click the Fetch All checkbox so that it is checked. This tells StudioWorks to fetch all of the active autotype records whenever you view them in a list window.</li> <li>Click the SQL Columns Editor tab.</li> <li>Right-click on the column names list and select New Column...</li> <li>Enter the column name <kbd>AutoTypeName</kbd>. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/warning.gif" alt="Warning" />You must be very careful to use the correct case for schema class and column names. Omnis Studio is case-sensitive with class names and column names. Naming the schema class sAutotype and then referring to it as sAutoType in another place will not work. Your code will fail if you name a schema column AutoTypeName, but then refer to it as AuotypeName in a calculation. </div></li> <li>Drag the AutoTypeName column to the 2nd row of the columns list if it isn't already the 2nd row.</li> <li>Set the character length field to 20 characters.</li> <li>Set the Label to <kbd>Auto Type Name</kbd>. Set the Abbreviation to <kbd>Auto Type</kbd>. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />StudioWorks will default to use the label value for the abbreviation. Abbreviations are used for headed list column headings, report column headings, and pushbuttons. </div></li> <li>Set the Unique Index checkbox to checked.</li> <li>Uncheck Null and Blank in the Values Allowed group box.</li> <li>Check Include in Lists, Prompts/Lookups, and Include in Search Columns in the Lists group box.</li> <li>Set the Sort Column checkbox to checked.</li> </ol><div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />Entry fields in the meta-data editor with a blue background are default values. If you edit a default value the background will change to white, indicating a non-default value. To revert to a default value, clear the entry field and tab out of the field. </div>Create the table in the database <ol> <li>Click the Database Admin tab in the Programmer Workbench. The Database Admin window is where you can sync your database tables to match your application's schemas. It also lets you view data, update primary keys, and a number of other database related functions.</li> <li>Click the Schemas and Tables tab.</li> <li>Select autotype in the Schema Table list. </li> <li>Click the Sync Database to Match Selected Schema button. This creates the new table in the database with the appropriate indexes. An information window will be opened that tells you the SQL script that was executed, actions taking, and if applicable and warnings or errors that were reported during the sync operation. Review the information and close the window.</li> </ol>You now have a table in the database ready to store records. <a name="addingawindow" /> <h3>Adding a Window</h3> Every window instance which you open in your StudioWorks application must first be declared. Each module declares its own window instances. Each window instance must have a unique wininstid. StudioWorks lets you set properties for each window instance. The Window Instance tab of the Programmer Workbench is where we can view and declare window instances. <ol> <li>Click the Window Instances tab in the Programmer Workbench.</li> <li>Expand the azDrivers node in the treelist.</li> <li>Note the AutotypeEdit and AutotypeList nodes in the treelist. StudioWorks automatically declares an edit and a list window instance for each schema class that you create.</li> <li>Click the AutotypeList node and look at the window instance properties. The fields in the upper portion of the window are display-only because this is a default window instance.</li> <li>Make sure the toolbarvisible and searchbarvisible checkboxes are checked for the AutotypeList window instance.</li> </ol> <a name="testingthewindow" /> <h3>Testing the Window</h3> We are now ready to test opening the AutotypesList window instance. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/tip.gif" alt="Tip" />Omnis Studio seems to cache the list of database tables when working with the Omnis data file. After you add some new tables you might need to Quit Omnis and reopen the application to force Omnis Studio to rebuild the database tables list. This only applies to the Omnis data file. If in the next few steps or later in the tutorial that you get some SQL errors after you've added a new table to the Omnis data file, try quitting Omnis and reopening the app. </div><ol> <li>With the AutotypeList node selected in the treelist, click the Open WinInst button at the bottom of the Programmer Workbench window.</li> <li>Click the New button in the toolbar. The AutotypeEdit autoconfig window instance should appear.</li> <li>Enter the Auto Type Name <kbd>Truck</kbd>. Click the Save and Close button or press the Return key.</li> <li>Click the New button in the toolbar.</li> <li>Enter the Auto Type Name <kbd>Car</kbd>. Click the Save and Close button.</li> <li>Click the New button in the toolbar.</li> <li>Enter the Auto Type Name <kbd>Bus</kbd>. Click the Save and Close button.</li> </ol>Congratulations you have created a table and inserted some records into the table! Easy, eh?! <a name="mappingicons" /> <h3>Mapping Icons</h3> In StudioWorks you can map an iconid to a wininstid or a basetable. Mapping an iconid to a basetable is more efficient because multiple window instances that use to the same basetable will immediately be mapped to the same iconid. For window instances that do not have a basetable (e.g. container windows), or window instances that you want to map to a different iconid, you can map an iconid to the wininstid. <ol> <li>Click the Icons List Editor tab in the Programmer Workbench.</li> <li>Click the Open Icons Browser button and take a look at the catalogue of StudioWorks icons available to you. The StudioWorks Icons Browser is a collection of icons in the swIcons4 library. Each iconid is mapped to an icon group and an icon name.</li> <li>Enter <kbd>car</kbd> in the search field and click the search button.</li> <li>Right-click on the PaperCar icon and select Copy Icon Full Name to Clipboard.</li> <li>Close the StudioWorks Icons Browser window.</li> <li>Select the azDrivers library in the Icons List Editor droplist.</li> <li>Right-click on the icons list and select New Icon... </li> <li>Enter <kbd>Autotype</kbd> in the following prompt for input window. Autotype will be added to the icons list.</li> <li>Set the schemacoldesc field to <kbd>vs.PaperCar</kbd> (You can paste this in from the clipboard). When you tab out of the field, the Autotype icon in the icons list should change to the PaperCar icon.</li> <li>Click the Window Instances tab in the Programmer Workbench. The AutotypeEdit and AutotypeList window instances should now be mapped to the $iconid of the vs.PaperCar icon name.</li> <li>Go back to the Icons List Editor and select the azDriversMain library in the droplist.</li> <li>Change the schemacoldesc to <kbd>vs.Truck</kbd> and tab out of the field.</li> <li>Close and reopen the Main Window. The root node of the navigation treelist should have changed from a cube icon to a truck icon.</li> </ol><div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />When you add an icon node to the Icons List Editor treelist, you are really adding a new row to the sIcons schema class of the parent node library. The Icons List Editor is just an interface for editing the sIcons schema classes. The advantage of using the Icons List Editor is that you immediately see a represention of the icon which you assigned, and the cached lists affected by your changes are immediately updated. (icons master list, windows master list, navigation menus list) </div> <a name="addingawindowtothenavigationlist" /> <h3>Adding a Window to the Navigation List</h3> The Navigation List Editor is used to add/remove window instances to/from the main window's navigation treelist. Let's add the AutotypesList window instance to the navigation treelist. <ol> <li>Click the Window Instances tab in the Programmer Workbench.</li> <li>Click the Navigation Menus List Editor tab.</li> <li>Expand the Drivers node in the treelist.</li> <li>Right-click the Drivers node and select Add WinInstID...</li> <li>Select the azDrivers > AutotypeList node in the prompt window and click the Continue button.</li> <li>All going well the AutotypeList window instance will be added as a child node to the Drivers root node.</li> <li>You can reorder the navigation list by dragging and dropping node(s) in the treelist.</li> <li>Open the main window (Ctrl/Cmnd+M). Expand the Drivers root node. All going well the Auto Types window instance will be appear as a child node.</li> <li>Click on the Auto Types node. The AutotypeList window instance will appear in a subwindow to the right of the navigation treelist.</li> </ol> <a name="addingachildtable" /> <h3>Adding a Child Table</h3> The steps for creating the Auto table are pretty much the same as the steps for creating the Autotype table. Create the schema class <ol> <li><nav>Programmer Workbench</nav> > SQL Meta-Data tab > azDrivers > right-click New Schema.... </li> <li>Name the new schema, <kbd>sAuto</kbd>.</li> <li>Select the SQL Class Editor tab.</li> <li>The Label (Singular) and the Label (Plural) values should already be set for you. If not, set them to <kbd>Auto</kbd> and <kbd>Autos</kbd>.</li> <li>Set the Fetchall checkbox to checked. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />If the Auto table was going to contain hundreds of records you would not check fetchall. </div></li> <li>SQL Columns Editor tab > right-click on the columns list > select New Column...</li> <li>Enter the name: <kbd>AutoName</kbd></li> <li>Set the character length to <kbd>50</kbd>.</li> <li>Drag the AutoName column to the 2nd row in the second row in the columns list.</li> <li>Set the Label to <kbd>Auto Name</kbd> if it isn't already set for you. Leave the abbreviation as is.</li> <li>Set the Unique Index checkbox to checked.</li> <li>Uncheck Null and Blank.</li> <li>Check Include in Lists, Prompts/Lookups, Include in Search Columns, and Sort Column.</li> <li>Add another column Autotype_fkey.</li> <li>Drag the Autotype_fkey column to the 3rd row in the columns list.</li> <li>Set the data type to <kbd>Integer</kbd>, and the subtype to <kbd>Long Int</kbd> This is the foreign key column which is used to link a child Auto record to its parent Autotype record.</li> <li>Set the Foreign Key checkbox to checked. Based on the column name StudioWorks will find the autotype table and set it as the referenced table, and then find the primary key column in the autotype table and set it to the referenced column name.</li> <li>Set the Cascade Delete checkbox to unchecked if it checked. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/warning.gif" alt="Warning" />If cascade delete is checked, child records are automatically deleted when the parent record is deleted. You want to be very careful with cascade deletes! </div></li> <li>Set the Null, Zero and Negative checkboxes to unchecked in the values allowed group. This enforces every child record to be linked to a parent record. Allowing null or zero values in the foreign key makes the child/parent link optional. </li> <li>Set the Hidden checkbox to checked if it is unchecked.</li> </ol> Create the table in the database <ol> <li>Programmer Workbench > Database Admin tab > Schemas and Tables tab.</li> <li>Select Auto in the Schema Table list. </li> <li>Click the Sync Database to Match Selected Schema button. This creates the new table in the database with the appropriate indexes.</li> </ol> <a name="creatingqueryclasses" /> <h3>Creating Query Classes</h3> We need to create query classes which joins the child Auto records to their parent Autotype records. Create the list view query class <ol> <li>Programmer Workbench > Query Builder tab.</li> <li>Expand the azDrivers node in the Queries treelist on the left side of the Query Builder window.</li> <li>Right-click on the azDrivers node and select New Query....</li> <li>Name the new query, <kbd>qAutoList</kbd></li> <li>Expand the azDriver node in the Schemas treelist on the right side of the Query Builder window.</li> <li>Select the sAuto schema class node.</li> <li>Drag the columns: auto_pkey and AutoName onto the qAutoList query class.</li> <li>Select the sAutotype schema class node.</li> <li>Drag the column: AutoTypeName onto the qAutoList query class. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />Based on the foreign keys meta-data the StudioWorks Query Builder will make its best guess at calculating the $extraquerytext to join the query class tables as you add or remove query class columns. If the $extraquerytext is not being calculated click the Rebuild Meta-Data button below the schemas treelist and then click the Extra Query Text button to recalculate the $extraquerytext. Always check, and if needed, correct the $extraquerytext when you have finished changing the columns. You are ultimately responsible for the final $extraquerytext. </div></li> <li>The Extra Query Text in Query Builder should read as follows: WHERE auto.autotype_fkey = autotype.autotype_pkey <div class="image_sideline"><img src="http://www.studiotips.net/css/images/tip.gif" alt="Tip" />The Omnis data file is picky about the order of the foreign key and primary key columns. To help you remember the order think about alphabetic order... fkey comes before pkey. </div></li> </ol> Create the edit view query class <ol> <li>Right-click on the azDrivers node in the Queries treelist on the left side and select New Query....</li> <li>Name the new query, <kbd>qAutoEdit</kbd></li> <li>Expand the azDriver node in the Schemas treelist on the right side of the Query Builder window.</li> <li>Drag and drop the sAuto schema class node on the Query Columns list. The column name value in the query columns list will be empty. By leaving the column name empty Omnis Studio will automatically include all of the columns from sAuto schema class in the query class.</li> <li>Select the sAutotype schema class node.</li> <li>Drag the column: AutoTypeName onto the qAutoList query class.</li> <li>Make sure the $extraquerytext reads as follows: WHERE auto.autotype_fkey = autotype.autotype_pkey </li> </ol> <a name="addingthechildwindow" /> <h3>Adding the Child Window</h3> Map an icon to the Auto table adding it to the icons list. <ol> <li>Click the Icons List Editor tab in the Programmer Workbench.</li> <li>Select the azDrivers library in the droplist. </li> <li>Right-click on the icons list and select New Icon... </li> <li>Enter <kbd>Auto</kbd> in the prompt window.</li> <li>Enter <kbd>vs.Car</kbd> in the schemacoldesc field. When you tab out of the field, the Auto icon should display a car.</li> </ol> Add the Autos window to the navigation list. <ol> <li>Programmer Workbench > Window Instances tab > Navigation Menus List Editor tab.</li> <li>Expand the Drivers node in the treelist.</li> <li>Right-click the Drivers node and select Add WinInstID...</li> <li>Select the azDrivers > AutoList node in the prompt window and click the Continue button.</li> <li>All going well the AutoList window instance will be added as a child node to the Drivers root node.</li> <li>You can drag the AutoList node to the position you want it to appear in the navigation list.</li> </ol> We are now ready to test opening the AutoList window instance. <ol> <li>Drivers > menu > select Main Window. Autos should now appear in the main window navigation treelist as a child of the Drivers node. </li> <li>Click the Autos node. The AutosList autoconfig window instance should appear in the main window navigation treelist. If the main window was open you will need to close and reopen it.</li> <li>Click the New button in the toolbar. The AutoEdit autoconfig window instance should appear.</li> <li>Enter the Auto Name <kbd>Ford F150</kbd>.</li> <li>Tab to the Auto Type Name field. The red border on the field indicates that it is a lookup type-ahead entry field.</li> <li>Type a <kbd>?</kbd> character in the field. StudioWorks displays a list of the possible auto types to select from.</li> <li>Hit the <kbd>down</kbd> and <kbd>up</kbd> arrow keys. StudioWorks scrolls the selected line in the droplist.</li> <li>Hit the <kbd>backspace</kbd> key and type the character <kbd>T.</kbd> StudioWorks displays a list of the auto types which begin with the letter T. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />The Omnis data file is case-sensitive, so you must type upper case T for this example. For other databases the lookups are case-insensitive. </div></li> <li>Click the droplist button to the right of the Auto Type Name field. StudioWorks displays a list of the possible auto types to select from.</li> <li>Click the <kbd>Truck</kbd> auto type in the droplist. StudioWorks closes the droplist and enters <kbd>Truck</kbd> in the entry field.</li> <li>Tab out of the field. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />On evAfter StudioWorks sets the Autotype_fkey column in the qAutoEdit list to the Autotype_pkey of the selected auto type record. </div></li> <li>Click the Save and Close button.</li> <li>Click the New button in the toolbar.</li> <li>Enter the Auto Name <kbd>Jaguar</kbd> and the Auto Type Name <kbd>Car</kbd>. </li> <li>Click the Save and Close button.</li> </ol>Congratulations you have created a child table and inserted some child records linked to parent records! <a name="linkingtoanotherparenttable" /> <h3>Linking to Another Parent Table</h3> Try the following assignment on your own. <ol> <li>Add a foreign key column to the sAuto schema to link it to the sContact schema. </li> <li>Set the meta-data. You will need to set the Null allowed and Zero allowed values to checked so that linking auto records to contacts records will be optional.</li> <li>Sync the sAuto table to the database. The contact_fkey column in the Auto table will be empty for the existing records in the Auto table. This will break the joins for those records. To fix this we will need to add a zero primary key record to the contact table and set the contact_fkey to zero for all the columns in the auto table as follows:</li><ol> <li>Programmer Workbench > Database Admin tab > Schemas and Tables tab > select contact</li> <li>Click the Insert Empty Records button. This checks for an empty record and if not found inserts an empty record with the primary key set to zero.</li> <li>Select the Interactive SQL tab and enter the following SQL statement: UPDATE auto SET contact_fkey = 0 WHERE contact_fkey IS NULL</li> <li>Click the Execute SQL button.</li> <li>Click the Data Viewer tab and select the auto table. Scroll across to the far right column to check the values in the contact_fkey column.</li> </ol> <li> Using Query Builder modify the qAutoList and qAutoEdit query classes to include the ContactSortName column from sContact. Be sure the $extraquerytext text joins the Auto table to the Contact table. <li> If you are using the Omnis data file you may need to quit Omnis and reopen your application before proceeding. <li> Select the Autos node in the main window navigation treelist. <li> Edit an existing auto record and link it to a contact. <li> Insert a new auto record linked to an autotype and a contact. </ol> <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />The Contact Sort Name labels can be changed to Driver Sort Name in the AutoList and AutoEdit window instances by changing the String Table name in the class meta-data of the qAutoList and qAutoEdit query classes. The quick start tutorial doesn't cover how to do this, but it is good know that you can create different labels for different query classes with the meta-data. </div> <a name="defaultreports" /> <h3>Default Reports</h3> The StudioWorks framework auto-creates a report when you click the Print button in the list view toolbar. The report includes all of the columns and records data displayed in the list. After you print a report you will find an X_ prefixed report class in the same library as the list query class. The report class name is based on the WinInstID of the list view window instance. If you remove the X_ prefix from the report class, the StudioWorks framework will continue to use the report class as the default report for that WinInstID. You can then open the default report class, reposition fields, and make as many modifications as you like. Your changes will be evident the next time you click the Print button in the list view toolbar. See the StudioTips > StudioWorks group > Reports tab for information on creating custom reports. <a name="exportingdata" /> <h3>Exporting Data</h3> If you click the Export button in a list view window the StudioWorks framework exports the columns and records data displayed in the list. The records are exported to a tab delimited text file. The column headings are included at the top of the file. <a name="addingmenus" /> <h3>Adding Menus</h3> You can add menus to any window instance. The menus appear in the toolbar. To add a Special menu to the AutoList window instance: <ol> <li>Programmer Workbench > Window Instances tab > Window Menus List Editor tab.</li> <li>Expand the azDrivers library node.</li> <li>Right-click on the AutoList node and select Add Special Menu...</li> <li>Enter <kbd>ExportAutoTables</kbd> as the menulineid in the prompt. All going well a Special menu child node will be added to the Autos node with the menu line, Export Auto Tables, added as a child node of the Special menu. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />When you add a menu line or change the menulineid, StudioWorks automatically adds the menulineid the sMn_stb schema class in that library and updates the string tables. You can further edit the string table text in the String Tables _stb Schemas Editor. StudioWorks adds a recipient method with the same name as the menulineid to the observer object class specified for the menu line. If the menuid is Reports, then a recipient method is also added to the oPrintReport object in the same library. You can click the edit pencil next to the menuclassname to go to the specified menu class. You can click the edit pencil next to the observer objectclassname to go to th observer object method that is called by this menu item. </div></li> <li>Click the Export Auto Tables node if it isn't already selected. The default values for the menu line are displayed in the fields to the right of the treelist. You can change the menu line's properties by editing these fields.</li> <li>Close and reopen the Main Window and select the Autos node.</li> <li>Click the Special menu in the far right side of the toolbar and select Export Autos Table. All going well you will end up at the breakpoint of the $ExportAutoTable method of the oSpecialMenuObserver object. You would write your code in this method to fetch all the records from the auto table and export them to a file.</li> </ol> To add a Reports menu to the AutoList window instance: <ol> <li>Programmer Workbench > Window Instances tab > Window Menus List Editor tab.</li> <li>Expand the azDrivers library node.</li> <li>Right-click on the AutoList node and select Add Reports Menu...</li> <li>Enter <kbd>AutosReportSortByType</kbd> as the menulineid in the prompt. All going well a Reports menu child node will be added to the Autos node, with the Autos Report Sort By Type menu line as a child node of the Reports menu. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />The StudioWorks framework will add the object classes oReportsMenuObserver and oPrintReport to a module if they don't exist when the first report menu item has been declared. The oReportsMenuObserver is classified as a visual object class. If you need to prompt the user to enter/select criteria before printing the report, do the prompts from this visual menu observer object. The oPrintReport object is classified as a non-visual object which means you should never prompt the user or open any error prompt windows in the oPrintReport object class methods. By splitting apart the visual code which prompts the user, from the non-visual print report code, you will be able to reuse the non-visual oPrintReport code when you add a web interface to your StudioWorks app. Trust me, it is worth doing. Clearly separating visual class code from non-visual make for cleaner reuseable code. </div></li> <li>Close and reopen the Main Window and select the Autos node.</li> <li>Click the Reports menu in the right side of the toolbar and select Autos Report Sort By Type. All going well you will end up at the breakpoint of the $AutosReportSortByType method of oReportsMenuObserver. You would write your code to prompt the user for the auto types they wish to include in the report and then pass this via parameters to the non-visual $AutosReportSortByType method of oPrintReport object. For prompting the user, use the oPromptModeless object which is instantiated by the task variable modelessprmpt. For more information see StudioTips > StudioWorks group > Prompts tab. For reports that do not require any user prompts you can remove the breakpoint and simply forward the message from the oReportsMenuObserver object to the oPrintReport object.</li> </ol><div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />You can associate an icon with any menu line by mapping an icon to the menulineid in the Icons List Editor. </div> <a name="customizingawindow" /> <h3>Customizing a Window</h3> The objective of the StudioWorks framework is to allow quickly move from database design to a basic application that allows you (and your client) to insert and link records, view lists and print simple reports. If you are converting an existing application you can import data from the old application and then play around with viewing and massaging the imported data in the new application. Once you get through the database design and generating the basic application you will be into the phase of creating custom windows with added bells and whistles to make data entry and modification easier for the users. To create a concrete window class from an autoconfig window class: <ol> <li>Programmer Workbench > Window Instances tab > Window Instances Editor tab</li> <li>Select the AutoEdit node.</li> <li>Click the Developerize button. The StudioWorks framework creates a wAutoEdit window class in the azDrivers module. In StudioWorks we call this a developerized window class. In object-oriented programming terms it is a concrete window class.</li> <li>Click the Modify button. This opens the wAutoEdit window class in the IDE.</li> <li>Rearrange the fields on the window and add a pushbutton object from the F3 Component Store.</li> <li>Close the wAutoEdit window class.</li> <li>Click the Open WinInstID button to open an instance of the wAutoEdit window class. Your changes to the wAutoEdit window class should be evident in the edit window instance.</li> </ol> Using normal Omnis Studio code you can customize your window class by adding field event methods, window objects, etc. to your concrete window class. The following sample code is from the $event method of the ContactFormalName entry field of the wContactEdit window class. On evBefore If len($cobj.$contents)=0    If iList.isHousehold       Calculate SortName as iList.ContactSortName       If pos(',',SortName)          Calculate FirstName as trim(mid(SortName,pos(',',SortName)+1))          Calculate LastName as trim(mid(SortName,1,pos(',',SortName)-1))          Calculate [$cobj.$dataname] as con(FirstName,' ',LastName)       Else          Calculate [$cobj.$dataname] as iList.ContactSortName       End If    Else       Calculate [$cobj.$dataname] as iList.ContactSortName    End If    Do $cobj.$redraw() End If Quit event handler (Pass to next handler) The code copies the ContactSortName to the ContactFormalName if the ContactFormalName is empty. For households the last name and first name are flipped from the ContactSortName to the ContactFormalName. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/tip.gif" alt="Tip" />It is important to end your $event method code with Quit event handler (Pass to next handler) so that the StudioWorks framework's field handler can properly decorate the field on evBefore and evAfter. </div> <a name="summary" /> <h3>Summary</h3> Hopefully this quick start tutorial has given you a sense of how the StudioWorks framework can assist you with rapid application development. We have really only scratched the surface in this tutorial. It is extremely difficult to write a tutorial that satisfies the wants and needs of all developers. Some developers like to have incredible detail, others get bored with too much detail. The real learning happens when you write your own application and have to deliver it to a client. Don't try to get too fancy too soon. Follow the pattern of the quick start tutorial by focusing on the database design, meta-data, and auto-generated window instances. Don't get side tracked into building custom window classes too early on. Get some real data into the database and generate some reports before tackling custom window classes. The farther you can get with using meta-data and auto-generated windows the better off you are. As you start adding custom features and enhancement to your StudioWorks app you will need to search the StudioWorks documentation, look at the methods and code inside the classes, and ask questions on the StudioWorks members list. The real learning is about to begin. Omnis Studio, StudioWorks, and SQL are a powerful combination - but you'll need to roll up your sleeves and be very persistent in order to learn how to harness the power. The StudioWorks members are a great community of developers, but they can't write your application for you (at least not for free). You can ask the questions, but you have to be persistent with the learning. There may be days you question your decision to invest in StudioWorks, but trust me, there are several man years of code included in the framework and many more years of experience that have been invested into learning Omnis Studio and object-oriented programming techniques. There are tools and features included in the StudioWorks framework which are the combined efforts of several StudioWorks devlopers. You would spend years writing (and debugging) these tools and features on your own. Working together we all win! Happy coding, Doug Kuyvenhoven <a href="http://www.vencor.ca">Vencor Software</a> <a name="whatnext" /> <h3>What Next?</h3> The following is a recommended list of things to do as you move forward with developing your new StudioWorks application. <ol> <li>If you haven't already done so, print the StudioTips and StudioWorks Naming Conventions. Read them. Keep them handy near your desk. Learning, understanding, and using the StudioWorks naming and coding conventions will make it much easier to follow the code in StudioWorks.</li> <li>If you are new to SQL or don't have formal database design training order a copy of Database Design for Mere Mortals by Micheal Hernandez from amazon.com. Read the book. I wish I read this book before writing my first app. Much of the thinking behind the SQL Meta-Data Editor came from reading this book.</li> <li>If you are new to SQL order a copy of Mastering SQL by Martin Gruber from amazon.com. I recommend this as a reference book for figuring out SQL scripts. You can do amazing things with SQL. With a little bit of SQL knowledge you can eliminate tons of list processing code in your application, and improve performance for compiling reports, etc. Spend time investing in learning advanced SQL, it is worth it.</li> <li>Learn to use Omnis Studio. To use StudioWorks you need to be familiar with Omnis Studio. If you aren't familiar with using Omnis Studio, you will be lost if when you try to write code in StudioWorks. Take the time to read the Omnis Studio PDFs and go through the tutorials and exercises they provide you with.</li> <li>Read through StudioTips to increase your knowledge of Omnis Studio.</li> <li>Do all of the StudioTips Tutorials. The tutorials help you understand StudioWorks.</li> <li>Learn Omnis Studio notation. Omnis Studio notation is powerful and StudioWorks uses Omnis Studio notation extensively. You can accomplish almost anything in Omnis Studio using notation. The notation becomes very logical once you begin to understand the syntax. There is no quick start tutorial to learning Omnis Studio notation. You can learn a lot by taking the time to study the comments and notation in the StudioWorks code.</li> <li>Learn to use the F4 Notation Inspector along with the F6 Property Manager to see the methods and properties. These two tools are the heart of where I figure out how to write Omnis Studio notation.</li> <li>Learn to use the Interface Manager. The Interface Manager shows the class methods you can call in an instance of class. Sending messages between instances of classes is a big part of Object-Oriented Programming. The Interface Manager reveals to you the messages you can send.</li> <li>Learn Object-Oriented Programming. Order a copy of Building Object Applications That Work by Scott Ambler from amazon.com, and read the book. Learning Object-Oriented Programming is a process that takes years. I'm still learning. The StudioWorks framework comes with loads of prewritten, well commented, reuseable, Object-Oriented Programming code. This gives you the advantage of live examples which you can learn from.</li> <li>Order a copy of Code Complete by Steve McConnell from amazon.com and read the book. This is one of the best books on writing good code. Loads of great advice. Much of the StudioWorks naming conventions are based on the recommendations in this book.</li> <li>Attend the StudioWorks training camps when they are held. There is nothing like in-class training. In a few days you will advance months in your application development.</li> <li>Attend Omnis conferences when they are held.</li> </ol> The above list might seem daunting. If it was easy, anybody could write custom software solutions. Once you gain the above knowledge and experience you can use Omnis Studio and StudioWorks to create powerful, flexible, and maintainable custom applications in an incredibly short period of time. The next tutorial, Customizing Your App, takes you through adding custom features and code to the meta-data based auto-generated Drivers app that you wrote in the Quick Start Tutorial. <a name="customizingyourapp" /> <h2>Customizing Your App</h2> This tutorial takes you through adding custom features and code to the meta-data based auto-generated Drivers app that you wrote in the Quick Start Tutorial. If you haven't completed the quick start tutorial, you will need to do that first. <a name="pingbuttons" /> <h3>Ping Buttons</h3> Under the Programmer Menu you will see the menu item Programmer $ping Pushbuttons. By selecting this menu item you toggle the menu checkmark. With this menu item checked a tiny pushbutton (White X in a blue circle) appears in the top left corner of each subwindow. If you click on the button a ping message tells you information about the subwindow. If you shift+click on the button you will end up at a breakpoint inside the subwindow. This feature is very helpful when you are debugging and customizing windows. I use the shift+click on the blue ping button technique for: <ol> <li>Looking at ivar values such as: iList, iSQLClassName, iWinInstID</li> <li>Adding a red breakpoint to the $doCmnd class methods so that I can step through the code when I click one of the toolbar buttons.</li> <li>Adding or modifying a window class method.</li> <li>Adding or modifying an $event method of an entry field.</li> </ol> <a name="debugokmessages" /> <h3>Debug OK Messages</h3> If a developer version of Omnis Studio is being used and an error is logged, the error handler opens a debug OK message. The OK message allows the user to break into the code at the error handler. From there, using the Stack toolbar menu you can go back up the method stack to investigate the method which logged the error, and any previous methods currently in the method stack. Being able to break into the method stack when an error is logged is extremely useful for solving bugs in your code. Click the Run Demo button in the StudioTips Browser window to try out the debug OK message. The debug OK message prompt is not opened for the following errors: check data, data, minor, and user errors. <a name="programmertestmethod" /> <h3>Programmer Test Method</h3> Each main library has its own mProgrammer menu class which is instantiated by the main menu as a cascading menu by the name Programmer Menu AppName. AppName is replaced with its string table translation. This method is helpful to you for experimenting and testing code which you write in StudioWorks. If I have a chunk of code that doesn't work and I want to experiment with variations of the code, I'll often go the the Programmer Test Method to try out different things. If I have a batch of records I need to fix in the database, I'll often use the Programmer Test Method to write and run the code. <ol> <li>Select the main menu > Programmer Menu AppName > Programmer Test Method</li> <li>This takes you to a Breakpoint command followed by a Quit method command.</li> <li>Below the Quit method you can write any code you like. The code in this method can access any of the task variable object methods so long as you are in the method stack. (i.e. You haven't cleared the method task after coming into the Programmer Test Method.)</li> <li>Enter the following code below the Quit method. Do stb.$getText('Mn','AppName',#S1) Return FlagOK</li> <li>Assuming you are still in the method stack, double-click on the line of code you just entered.</li> <li>Click the Step In IDE toolbar button. You should have stepped into the $getText method of the oStringTable object class.</li> <li>Click the Step Out button of the IDE toolbar. You should be back to the mProgrammer method.</li> <li>Hover over the #S1 variable in your line of code. The value should be the name of the current app.</li> </ol>The StudioWorks code only works from the main library task instance. You can't just open an object class from the IDE and double-click on a line of code in a method and hit the Go toolbar button. Wherever you run StudioWorks code you must be within the task instance of the main library's Startup_Task. If you don't understand the last few sentence don't worry about it for now. Just trust me, that if you want to test some code in StudioWorks you either catch it with a red breakpoint when the method is run, or you write it in the Progammer Test Method, select Programmer Menu > Programmer Test Method and then double-click below the Quit method and start stepping through your code. <a name="methodcallsormessages" /> <h3>Method Calls or Messages?</h3> One of the things that was confusing to me when I got into reading the object-oriented programming books was this thing about sending messages. In Omnis I was used to the the term method call. If I was explaining code to someone I would say that MethodA does a method call to MethodB even if MethodB was in another class. Instead of using the words making a method call to another class, the object-oriented programming world uses the word sending a message, which once you get your head adjusted to it, it really is a better word picture of what the code is doing. So, when we talk to each other about our code (or if we're talking to ourselves), let's talk about class instances sending messages to each other rather than using the term of making method calls. You can still use the term method call when MethodA and MethodB are in the same class. So how does this word picture help the developer? Let's use a the real world which all of use can easily relate to. <ul> <li>In this world there is a class called Human</li> <li>Doug is an instance of the class Human.</li> <li>Andy is another instance of the class Human.</li> <li>The instance Doug sends an $email message to the instance Andy. Doug is the sender. Andy is the target.</li> <li>In order for Andy to receive the $email message, Andy needs to have an $email recipient method.</li> <li>The $email message may contain parameters: pFrom, pTo, pReplyTo, bBody, which must map correctly to the $email recipient method's parameters.</li> </ul> Do you see how this relates to classes and public methods in Omnis Studio? Let's use a StudioWorks framework example to tell a similar story. <ul> <li>In StudioWorks there is a class called oStringTable</li> <li>The stb startup task variable is an instance of the class oStringTable.</li> <li>Programmer Menu is an instance of the class mProgrammer</li> <li>The instance Programmer Menu sends a $retText message to the instance stb and includes the parameters ('Mn','AppName') with the message.</li> <li>The stb instance receives the $retText message with the enclosed parameters, processes the message, and returns the value, Drivers, to the sender.</li> </ul> Once you get the picture of instances sending messages to each other, a lot of things gain clarity in Omnis Studio. When a user clicks on a line in a headed list: <ul> <li>Omnis Studio sends an $event message to the headed list object instance. In this special case of event handling instead sending parameters to the $event method, Omnis Studio sets the task scope variables pEventCode and pRow so that any instance within the task can access the event parameters.</li> <li>If the headed list object has an $event recipient method it can receive and act on the message.</li> <li>The $event method of the headed list object instance can then pass the message to the $control method of the window class.</li> <li>If the window class has a $control method it can receive the message and process it.</li> </ul> When you open a library, Omnis Studio looks for a task class named Startup_Task. If found Omnis Studio opens an instance of the Startup_Task class and names the instance the same name as the library name. Omnis Studio then sends the task instance a $construct message. If the $construct recipient method exists, the code in the method can open instances of menu classes, toolbar classes, and window classes. All of these instances that are opened are contained within the startup task instance. Hopefully the above note help you to see more clearly the picture of class instances sending messages to each other. The StudioWorks framework depends heavily on the concept of sending messages between source and target class instances, so it will be good if you think and talk in these terms. <a name="interfacemanager" /> <h3>Interface Manager</h3> One of the keys to using the StudioWorks framework (and Omnis Studio ) is learning to use the Interface Manager. I wrote code using Omnis Studio for about 2 years without using the Interface Manager. Today, I'd be lost without the Interface Manager. The Interface Manager shows you the public interface to a class, that is, all the class methods which begin with the $ character. Well built object-oriented programs have a good clean public interface. You write your code using the public interface. The Omnis Studio IDE works very well with the Interface Manager. If you aren't familar with the Interface Manager and how to use it to write code, let's go through some exercises. For these exercises you will be writing code in the Programmer Menu AppName > Programmer Test Method. The instructions below assume that you will write the code below the Quit method in the $event method of the Programmer Test Method menu line of the mProgrammer class method. Get and set the $:AppName property in the oConstants object class instance. <ol> <li>In the method, type the word <kbd>Do</kbd> and tab to the Calculation line.</li> <li>In the Variable pane, click the Task tab, and find the task variable cn.</li> <li>Right-click on cn > select <nav>Interface Manager</nav>.</li> <li>Scroll down the list and find the $:AppName method.</li> <li>Drag the $:AppName method from the <nav>Interface Manager</nav> into the Calculation field of your Do command.</li> <li>Press tab and enter #S1 in the return field. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/warning.gif" alt="Warning" />Do not use # hash variables for your real app code. </div></li> <li>Programmer Menu > Programmer Test Method > double-click your line of code and click the Step Over button in the IDE toolbar.</li> <li>Hover your mouse over the #S1 variable in your line of code. Is the value Drivers or whatever you named your app?</li> <li>Start a new <kbd>Do</kbd> command line.</li> <li>Drag the $:AppName.$assign method from the <nav>Interface Manager</nav> into the Calculation field. Omnis Studio very kindly includes the parameters in parenthesis for us when we drag in the method from the <nav>Interface Manager</nav>.</li> <li>Replace pAppName with <kbd>'Crazy Drivers'</kbd> including the single quotes.</li> <li>Double-click your line of code and click the Step Over button in the IDE toolbar.</li> <li>Now double-click the first Do command and Step Over that line of code. The value returned to #S1 should now be Crazy Drivers.</li> </ol> Your finished code should look like this: Do cn.$:AppName() Returns #S1 Do cn.$:AppName.$assign('Crazy Drivers') Now we'll use the <nav>Interface Manager</nav> to look at the table class methods. List and row variables do not know which table class they are supposed to point to until after you bind them to a table class. In StudioWorks you bind a list or row variable by sending a $retDefinedList to the lsts instance of the oSQLList object class. <ol> <li>Enter a <kbd>Do</kbd> command.</li> <li>Right-click the task variable lsts > select <nav>Interface Manager</nav>.</li> <li>Drag the $retDefinedList method into the Calculation field of your Do command.</li> <li>Replace the pSQLClassName parameter with <kbd>'sCountry'</kbd> including the single quotes.</li> <li>Remove the other parameters, they are optional.</li> <li>Enter <kbd>#L1</kbd> in the Returns field.</li> <li>Programmer Menu > Programmer Test Method. Double-click your line of code and click the Step Over button in the IDE toolbar.</li> <li>Right-click the #L1 variable > select Variable #L1... This opens the variable window which should display to you an empty list with the column names. Close the variable window.</li> <li>Enter another <kbd>Do</kbd> command in the next line.</li> <li>Right-click #L1 in your method code > select <nav>Interface Manager</nav>. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />The list or row variable <nav>Interface Manager</nav> is only available after the list or row has been bound to a table class while you are stepping through the code. If you were to clear the method stack and right-click on the list variable the <nav>Interface Manager</nav> menu line does not appear in the context menu. </div></li> <li>Drag the $:BaseTable method into the Calculation field of your new Do command.</li> <li>Enter <kbd>#S1</kbd> in the Returns field.</li> <li>Double-click your line of code and click the Step Over button in the IDE toolbar.</li> <li>Hover the mouse of the #S1 variable, that value should be Country.</li> <li>Enter another <kbd>Do</kbd> command in the next line.</li> <li>Right-click #L1 in your method code > select <nav>Interface Manager</nav>.</li> <li>Select the $getAllRecords method in the Interface Manager.</li> <li>Click the Description tab in the bottom part of the <nav>Interface Manager</nav>. Note the method description. If I've done my job, you should see a short description about what the method does and what it returns. Well written classes with good public methods should be like a black box. You should never need to look inside the box to see what the method does. The Interface Manager tells you the method name, the parameters, the method description, and the return value you can expect.</li> <li>Drag the $getAllRecords method into the Calculation field of your Do command.</li> <li>Enter #F in the Returns field. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/warning.gif" alt="Warning" />Do not use # hash variables for your real app code. </div></li> <li>Double-click your line of code and click the Step Over button in the IDE toolbar.</li> <li>Right-click #L1 in your Do command > select Variable #L1... All going well the variable window will show a list of country records that were fetched from the database.</li> </ol> Your finished code should look like this: Do lsts.$retDefinedList('sCountry') Returns #L1 Do #L1.$:BaseTable Returns #S1 Do #L1.$getAllRecords() Returns #F The <nav>Interface Manager</nav> is an important tool for you to use when writing code in Omnis Studio. Documenting all of the classes and methods in the StudioWorks framework would take longer than writing the code... and would end up being a repetition of the information you can find yourself by using the <nav>Interface Manager</nav>. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/tip.gif" alt="Tip" />From the method editor you can look at the Interface Manager of the class you are in using the View IDE toolbar button. From the F2 Browser you can look at the Interface Manager of any class by right-clicking on the class and selecting <nav>Interface Manager</nav>. </div>Take some time and study the public interface of the Startup_Task task variables. These are the key object classes of the StudioWorks framework. Before you spend time writing a custom method, look at the object classes in the StudioWorks core libraries. There are object classes for exporting and importing data, encrypting and decrypting files, opening the client's web browser to a specific URL, preparing an email in the client's email program, etc. If you are unsure, ask a question on the StudioWorks list. Other StudioWorks members might know where to look. One of the benefits of the StudioWorks community is that we can create reuseable object classes which we can share, because we are using a common framework. If you know the task variable name and have an idea of the public method name you don't have to use the <nav>Interface Manager</nav>. Try the following: <ol> <li>Set your Omnis > Preferences > General tab > $notationhelptimer to <kbd>50</kbd> milliseconds.</li> <li>In the method editor type Do</li> <li>Press the Tab key to go to the Calculation field.</li> <li>Type the characters <kbd>err</kbd>. The task variable errhndler should show up in the notation helper. </li> <li>Press the <kbd>Tab</kbd> key and type the characters <kbd>$pr</kbd>. The method $promptonceLastError should show up in the notation helper. </li> <li>Press the <kbd>Tab</kbd> key.</li> <li>Enter the opening and closing parenthesis <kbd>()</kbd> to finish the calculation.</li> </ol>I find the notation helper to be a huge help when writing code in Omnis Studio. It helps you enter method names, variable names, and even functions. You can play with the notation timer speed. I like it around 50 so that I don't have to pause and wait for the helper. You can use the <kbd>up</kbd> and <kbd>down</kbd> arrow keys or your mouse to select something in the notation helper list. If you don't select an item in the notation helper list the first matching item to what you have typed so far in the Calculation field will be used when you press the <kbd>Tab</kbd> key. <a name="addingatoolbarbutton" /> <h3>Adding a Toolbar Button</h3> To add a toolbar button to the contacts list window: <ol> <li>Main Window > Contacts > Shift+click the blue ping button.</li> <li>Find the $:ToolbarCmndsCSV method in the class methods.</li> <li>Right+click the method and select Override Method.</li> <li>Uncomment the method lines.</li> <li>Add <kbd>,HelloWorld</kbd> to the end of the toolbar buttons string being returned by the Quit method. Quit method 'Edit,New,NewCopy,Delete,SPACER,Find,Print,Export,HelloWorld'</li> <li>Right+Click the class methods > select Insert New Method.</li> <li>Name the new method <kbd>$HelloWorld</kbd> and put a breakpoint in the method.</li> <li>Close the IDE window.</li> <li>Close and reopen the main window and select the Contacts node.</li> </ol> The HelloWorld button should appear in the toolbar, but you will notice that the text is not translated, it is not enabled, and does not have an icon. To solve these problems: <ol> <li>Add <kbd>HelloWorld</kbd> to the sMn_stb schema class in the module. Enter <kbd>Hello World</kbd> in the description.</li> <li>Add <kbd>HelloWorld</kbd> to the sIcons schema class in the module. Enter <kbd>1653</kbd> in the description.</li> <li>Programmer Menu > Reload String Tables. (This also rebuilds the icons list)</li> <li>Main Window > Contacts > Shift+click the blue ping button.</li> <li>Find the $_retActiveCmndsList method in the class methods, override the method, and add the following code to the method: Do inherited Returns List Do List.$add('HelloWorld') Quit method List </li> <li>Close and reopen the main window and select the Contacts node. All going well the button will have the correct text, icon, and be enabled.</li> <li>Click the Hello World icon. All going well you will end up at the breakpoint in the $HelloWorld method.</li> </ol> <a name="removingatoolbarbutton" /> <h3>Removing a Toolbar Button</h3> There are two ways to remove a toolbar button. <ol> <li>Override the $:ToolbarCmndsCSV method and remove the button from the CSV string being returned by the method.</li> <li>Send a $removeCmnd message to the window instance.</li> </ol>A situation where you might use the $removeCmnd technique is where you are reusing an edit window inside a container window and you want to remove the Save and Close button from the edit subwindow. After constructing the edit subwindow, the container would send a $removeCmnd('SaveAndClose') message to the edit subwindow. The subwindow would remove the button from its toolbar. <a name="writingmethods" /> <h3>Writing Methods</h3> How you write your code is up to you. The following are a list of guidelines which I follow when writing code. These guidelines have evolved over the years. <ol> <li>Always return something. Either FlagOK (true or false) or a return value.</li> <li>Only exit at the end of the method. (This guideline was added in mid 2005. Code written by me prior to mid 2005 has lots of early exit points.)</li> <li>If a method is returning a value calculate the value to a local variable and return the variable. If an error occurs in the method, set the variable to #NULL. The sender can check the return value with the isnull() function.</li> <li>Preset the return local variable to the negative condition in the init value in the variables pane. FlagOK to kFalse. Return value to #NULL.</li> <li>Always test the return flag or value from a method before proceeding further in the method. Sample code as follows: ; Test FlagOK Do List.$getAllRecords() Returns FlagOK If FlagOK    ; Continue End If Quit method FlagOK ; Test return list. Lists and rows you can not test with isnull() Do lsts.$retDefinedList('sContact') Returns List If List.$colcount=0    Calculate FlagOK as kFalse Else    ; Continue End If Quit method FlagOK ; Test return string Do fn.$retCSVStringFromList(List) Returns String If isnull(String)    Calculate FlagOK as kFalse Else    ; Continue End If Quit method FlagOK </li> <li>The method where an error occurs must immediately log the error to the error handler. Always declare and set both error message variables, Mssg and Dtls, even if you set Dtls to empty.</li> <li>Only public methods of visual classes prompt the user with errors. (windows, toolbars, menus, menu obsever objects classes) Wait till the end of the method before prompting the user. ; Pretend this is a public method of a window class. Do lsts.$retDefinedList('sContact') Returns List If List.$colcount=0    Calculate FlagOK as kFalse Else    Do List.$getAllRecords() Returns FlagOK    If FlagOK       Do List.$smartlist.$assign(kTrue)       Do List.$sendall($ref.Active.$assign(kTrue))       Do List.$doworkBatch() Returns FlagOK    End If End If ; Wait till the end of the method. Test the flag. Prompt the last error if the flag is false. If not(FlagOK)    Do errhndlr.$promptonceLastError() End If You can avoid a lot of $promptonceLastError message calls by structuring your code so that the public methods of your visual classes call lots of private or protected methods which do the real work. The non-public methods only have to worry about returning the flag or value since the public visual class methods are responsible for taking care of the $promptonceLastError.</li> <li>Only public methods of visual classes issue redraws. Following this technique makes it easy for non-public methods and non-visual class methods... they never have to think about redrawing the window, that is the responsibility of the visual class public methods.</li> </ol><div class="image_sideline"><img src="http://www.studiotips.net/css/images/tip.gif" alt="Tip" />In your Omnis Studio Preferences > General tab set the $notationhelpertimer property to <kbd>50</kbd> milliseconds. The notation helper will come up a lot faster and save you loads of keystrokes and typing errors. </div> <a name="errorhandling" /> <h3>Error Handling</h3> If you want to write code that is easy to maintain you must be diligent about writing good error handling into your code. <ol> <li>Anticipate where errors might happen.</li> <li>Log every error to the error handler. </li> <li>Write clearly understandable error message text. (The Mssg and Dtls variables) <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />The error handler takes care of reporting the library/class/method which reported the error. You simply need to report additional helpful error message and details information. </div></li> <li>Check the return flag or value from every method which you call and bail out if the flag or value is communicating an error.</li> <li>End every visual class public methods with an if error test which sends a $promptonceLastError message to the error handler if an error was detected by the visual class public method code.</li> </ol> The StudioWorks error handler has specific log error methods which make it easier for you to log certain types of errors. Study the different $log...Error methods in the oErrorHandler object class to become familiar with them. By using the correct method you can save yourself some time, and your user will get an error message with with the appropriate icon and error message information. In some cases the error is not a program error. For example the user enters an incorrect password. A non-visual class method can send a $logMinorError message to the error handler and return false to the sender. The visual class method then sends a $promptonceLastError message to the error handler and the user is prompted with a non-threatening error message. Click the Run Demo button in the StudioTips Browser window to see a demonstration. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/warning.gif" alt="Warning" />Do not use OK message commands in your non-visual class methods. If you ever try to run your StudioWorks app as web server app the OK message commands will halt your application on the web server preventing it from responding to any further requests. Someone will have to go to the server and click the OK message to allow it to continue. Not a good thing. </div> <a name="overridingamethod" /> <h3>Overriding a Method</h3> When overriding a superclass method in StudioWorks, to avoid duplication, you should normally first Do inherited and then add your subclass specific method code. ; Run the superclass code Do inherited Returns FlagOK If FlagOK    ; Do the subclass additional code. End If Using the 4GL Do inherited command you can get away with not declaring the parameters in the subclass, but if you put a breakpoint on the Do inherited and step up into the superclass method the parameters in the superclass method will be empty. For the superclass code to work while stepping through a Do inherited, the correct parameters must also be declared in the subclass method. If you need any of the parameters in the subclass method, you will need to declare the parameters in the subclass. Sometimes is it easier to copy the entire superclass method, which also copies the parameters to the subclass, and then delete the code from the sublclass method and enter Do inherited at the top of the subclass method. See the steps below for the proper way to copy a superclass method to a subclass. Running the superclass method isn't always possible. In some cases you will have to copy the superclass method to the subclass and then modify the copied method in the subclass. Use the following steps to copy a superclass method to the subclass. <ol> <li>Select the superclass method from the subclass. The superclass method will be in blue text.</li> <li>Double-click anywhere on the superclass code. This takes you up to the superclass method.</li> <li>Right-click on the superclass method > select Copy. This copies the entire method to the clipboard.</li> <li>Close the superclass methods IDE window.</li> <li>Right-Click on the superclass method in the subclass > select Override Method.</li> <li>Right-Click on the overridden superclass method in the subclass > select Paste. This copies the entire method from the clipboard to the subclass.</li> </ol>If you only copy the method text from the superclass to the subclass you run the risk of having the superclass parameters being copied into the subclass method in the wrong order, which very quickly breaks your code and can lead to hours of debugging. I know this from first hand experience. <a name="callingasuperclassprivatemethod" /> <h3>Calling a Superclass Private Method</h3> You may run into a situation where there is a private in an StudioWorks superclass which you want to call from your subclass. Rather than copying the private method to your subclass you can add a protected method in the superclass which calls the private superclass method and then post a request to the StudioWorks list to add the protected method the superclass in the StudioWorks framework. This way you can immediately using the superclass private method and the next release will work without modification as long as the superclass method you requested is added to the framework. Here's an example. <ol> <li> You subclass oStartupTaskDefaultMethods to your main library. <li> You want to add to the setDefaultsAndPrefs method, but it is a private method called from the $constructMethod method. </ol> Here's what you can do. <ol> <li> Find all occurrences of Do method setDefaultsAndPrefs in oStartupTaskDefaultMethods and change them to Do $cinst.$_setDefaultsAndPrefs 2. Add a $_setDefaultsAndPrefs method to the superclass which has the following code: Do method setDefaultsAndPrefs Return FlagOK Quit Method FlagOK <li> Override the method in your subclass and enter the following code: Do inherited Return FlagOK If FlagOK ; Do the additional stuff you wanted to do End if Quit method FlagOK <li>Send a request to the StudioWorks members list to add $_setDefaultsAndPrefs to oStartTaskDefaultMethods for the next release. When the next release comes out you don't need to change any code. If I decide to rename or refactor the private method in the superclass your code won't get busted. If I add or fix code in the superclass private method, your subclass will use it. If I decide to move the private method code to the protected method and delete the private method nothing is broken. <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" />Background - Private methods give me much more flexibility because they are inside the box where I can still play with them. As soon as a method name has a $ character prefix, I can't mess with the name, the purpose, the parameters, etc. If you are coding from my end, you soon realize how restrictive that is... especially in the early stage of developing an object when you need to refactor the methods and code a few times as it progresses and gains clarity over the course of several releases. -- Doug K.</div> <a name="promptingtheuser" /> <h3>Prompting the User</h3> Only prompt the user from public visual class methods. In the context of the StudioWorks framework visual classes are: <ol> <li>Window classes</li> <li>Menu classes</li> <li>Toolbar classes</li> <li>Menu observer object classes (oReportsMenuObserver, oSpecialReportsMenuObserver)</li> <li>Startup_Task $construct and $destruct methods.</li> </ol> All other classes should be considered to be non-visual classes and therefore should never prompt the user. In the context of the StudioWorks framework public methods are: <ol> <li>Methods which begin with the $ character, excluding those which begin with $_ character.</li> </ol> You have several choices for prompting the user: <ol> <li>Omnis Studio 4GL commands: OK, Yes/No, No/Yes, Prompt for input These are modal prompts (they halt code execution), and they have a 255 character limit.</li> <li>StudioWorks oPrompts object methods which you access via the prmpts task variable. These are modal prompts which use one font size for the message text and a small font size for the additional details text. The StudioWorks prompts do not have a limit on the number of characters. The StudioWorks prompts do string table translations on any text strings that are in the format stbname.stbid.</li> <li>StudioWorks oModelessPrompts object methods which you access via the modelessprmpt task variable. These are modeless prompts which use one font size for the message text and a small font size for the additional details text. The StudioWorks prompts do not have a limit on the number of characters. The StudioWorks prompts do string table translations on any text strings that are in the format stbname.stbid. The StudioWorks modeless prompts let you build custom prompts or input prompts which can be a combination of radio buttons, checkboxes, etc. See StudioWorks > Prompts documentation for more information.</li> </ol>Click the Run Demo button in the StudioTips Browser window for a demo of the different prompts. <a name="databaseandsql" /> <h3>Database and SQL</h3> If flag trueThe StudioWorks framework uses the table class tBase for all selects, fetches, inserts, updates, and deletes with the database. The StudioWorks framework makes extensive use of the Omnis Studio $smartlist functions. When you set a list to be a smartlist, Omnis Studio makes a hidden history list. The history list keeps track of lines added, lines changed, and lines deleted from the original list at the time is was set to be a smartlist. The smartlist eliminates all the code you would have to write to keep track of which lines in a list need to be inserted into the database, which lines need to update records in the database, and which lines need to delete records in the database. You simply issue a $dowork and Omnis Studio does the database work for you. (StudioWorks uses a modified version of $dowork which it has named $doworkBatch) Without the StudioWorks framework you would need to write at least the following code to update a batch of contact records in the database. Calculate HostName as 'PathToTheOmnisDataFile' Calculate UserName as 'TheUserName' Calculate Password as 'ThePassword' Calculate SessionName as 'TheSessionName' Do SessionObj.$logon(HostName,UserName,Password,SessionName) Returns FlagOK If not(FlagOK)    ; Log the $logon error here. Else    Do List.$definefromsqlclass('myAppModule.sContacts')    Calculate List.$sessionobject as SessionObj    Do List.$select() Returns FlagOK    If not(FlagOK)       ; Log the SQL error here.    Else       Do List.$fetch(kFetchAll) Returns FetchStatus       If FetchStatus=kFetchError          ; Log the SQL error here.          Calculate FlagOK as kFalse       Else          Do List.$smartlist.$assign(kTrue)          For List.$line from 1 to List.$linecount step 1             Calculate List.ColName as 'SomeValue'             Calculate List.ModBy as UserName             Calculate List.ModDateTime as #D             Calculate List.EditNum as List.EditNum+1          End For          Do List.$dowork() Returns FlagOK       End If    End If End If Quit method FlagOK With the StudioWorks framework the following code accomplishes the same thing. ; Ask the oSQLLists object to return a defined list bound to the correct session object. ; If there is an error oSQLLists will log the error for you. Do lsts.$retDefinedList('sContact') Returns List If List.$colcount        ; Ask the tBase table class to select and get all the records.    ; If there is an error tBase will log the error for you.    Do List.$getAllRecords() Returns FlagOK    If FlagOK              Do List.$smartlist.$assign(kTrue)              For List.$line from 1 to List.$linecount step 1          Calculate List.ColName as 'SomeValue'          ; Setting the admin columns (EditNum, InsBy, InsDateTime, ModBy, ModDateTime) is handled by tBase.       End For              ; A custom dowork method in tBase, $doworkBatch, updates all the admin columns for you.       ; If there is an error tBase will log the error for you.       Do List.$doworkBatch() Returns FlagOK    End If End If Quit method FlagOK You can go a long ways with just the above snip of code. The code breaks down to 5 steps: <ol> <li>Define the SQL list variable. Always to this by sending a $retDefinedList message to the oSQLLists object. Do lsts.$retDefinedList('SchemaOrQueryClassName') Return List</li> <li>Fetch the record(s) you want update. Always use one of the $get... methods of the tBase table class. Do List.$getWhere(WhereRowOrWhereText) Return FlagOK</li> <li>Set the data list variable to be a smartlist. Do List.$smartlist.$assign(kTrue)</li> <li>Make your changes to the smarlist. </li><ol> <li>To add lines use Do List.$addNewLine()</li> <li>To update lines make sure the line you want to update is the current line, and use Calculate List.ColName as Value</li> <li>To delete lines use Do List.$remove(LineNum) or Do List.$remove(kListDeleteSelected) or Do List.$remove(kListKeepSelected)</li> </ol> <li> When you are ready to update the database issue a $doworkBatch Do List.$doworkBatch() Return FlagOK </ol> There is a lot more that the StudioWorks framework tBase table class can do for you. Study the public methods of tBase to see what is available to you. See StudioWorks > SQL documentation for more info. <a name="subwindows" /> <h3>SubWindows</h3> Every window and subwindow that you instantiate in StudioWorks must have a unique window instance ID. We refer to the unique window instance as the WinInstID. The WinInstID, CountryList, would be a headed list window used for displaying a list of Countries in the Country table. The WinInstID, CountryEdit would be a window with entry fields used for editing new or existing Country table records. Default WinInstIDs are automatically generated by StudioWorks for every server table based schema class in each module. The WinInstIDs use the naming convention TablenameList and TablenameEdit, where Tablename is the cap() value of the server table name in the database. You can declare your own custom WinInstIDs in the $addCustomWinInstIDs method oWindowList in each module. Information about each WinInstID is gathered from the oWindowsList object in each module. The information is stored in the oWindows object where it can be accessed through the task variable wn. To look at the WinInstID information you would issue: Do wn.$retWinListRow('CountryList') Return Row Virtually every WinInstID is instantiated as a subwindow inside of a parent shell window. The Main Window is a subclass of wShell with a navigation treelist subwindow added to it. The wShell window class is designed so that it can instantiate an infinite number of subwindows. The wShell window class keeps track of the subwindows it instantiates in its own subwindows list and subwindows stack. When you click a node in the navigation treelist a message is sent from the treelist subwindow to the main window shell asking it to prepare and open a specific WinInstID. The main window checks to see if the WinInstID has already been instantiated. If not, it adds a subwindow field, and based on the information in the windows list, it sets the $classname property of the new subwindow field. This immediately instantiates the window class inside the subwindow field. The subwindow is brought to the front by hiding the previous subwindow and making the new subwindow visible. Each subwindow in StudioWorks is designed to be self-contained. It can have its own title, toolbar, and pushbuttons. The subwindow has very little dependence on the shell window which instantiates it. For example, the CountryList subwindow constructs its own headed list, toolbar, and search bar. When a user presses New on the toolbar a $new message is sent to the subwindow. The subwindow finds out from the meta-data that the WinInstID, CountryEdit, is used for creating new records and it sends a message to its shell asking the shell to prepare a CountryEdit WinInstID. The shell prepares the WinInstID as a subwindow and returns a reference to the $new method which then sends a $newRecord message to CountryEdit. CountryList also attaches itself as an observer to CountryEdit asking to be notified if the database is changed. CountryEdit is self-contained, so it knows what to do. By making each subwindow as independent as possible, we can more easily use a window class in different situations. If you shift+click on a node in the navigation treelist the same subwindow will be instantiated in a separate shell; where you can click the New button and see the very same behavior. <a name="containerwindows" /> <h3>Container Windows</h3> The next level in using subwindows is to combine several subwindows inside a container window. Instead of instantiating just a ContactsList window, you might want to have the ContactList subwindow in the top half of the window and the ContactEdit subwindow in the bottom half of the window. Clicking on a contact in the list subwindow triggers displaying the contact details in the edit subwindow. A window which instantiates more than one subwindow is called a container window. The Town/City Lookups window is a container window. It has a tab pane interface with each tab being a separate WinInstID. The StudioWorks framework ships with a number of container window superclasses and templates which you can copy and play around with. These container windows have not been extensively developed or documented so you have to be prepared to do some investigative learning. The container window attempts to take typical window layouts and use generic code to reduce the amount of code you have to write in order to make them work. If you double-click on the subwindow field, you will find a $:InitialWinInstID property method. Enter the WinInstID you want that subwindow to intially be instantiated as. Good luck. Feel free to create you own custom container windows. The container windows gets into the realm of your domain because this is where things get very application and developer specific. From the object-oriented point of view, the shell window sends messages to the container window. The container window is fully responsible for its subwindows. A subwindow should not communicate directly to another subwindow, rather it should send the message to its cont