Wylib DataBase Preview widget (DBP)


Table of Contents

Introduction
Loading the Records you Want
Selecting Records
Modifying the Column Sizes
Modifying the Column that Display
Sorting the Data
Standard Menu Functions
Context Menu Functions

Introduction

Typically, a database table might contain thousands or even millions of records. Often, the user may want a way to choose one particular record out of the table to view in detail or even to modify it. Also, the usere may want to view a group of records together in a comparative way. The preview widget is helpful for both of these purposes.

In the preview widget, multiple records are displayed in a list where each horizontal row in the list represents a single record. In each record are a number of individual data items, often called "fields." Each field is represented as a vertical column in the list.

One or more rows in the list can be selected (highlighted) using the mouse. And then the "Execute" function will cause some action to be taken on the selected rows. Typically these two steps (selecting and executing) are done on a single row by just Double-Clicking on the row.

Often a DBP widget will be used in conjunction with a DBE (record editing) widget. When this is the case, the execute function (Double-Click) will cause the selected record to be loaded into the DBE pane where it can be viewed in detail and possibly updated or deleted. In other applications, the execute function may do something else.

Loading the Records you Want

Some applications will be preconfigured to always load the data you need in the preview widget. More typically, the application will have a "Default" load and then will allow you to define your own criteria for which records you want to load from the database.

When requesting a customized set of records (like all contacts from a certain state), you need to use the DBS (DataBase Search) widget. This is typically invoked by a button titled "Srch" or a menu function called "Search For Records." After launching that widget, read the help document from its main menu for more information on how to use it.

Selecting Records

A single row can be selected simply by clicking on it. A single row can be selected and executed by Double-Clicking on it.

In some cases (depending on the application), multiple rows can be selected at once by dragging the cursor across the lines. Or, a Click on one line and a Shift-Click on another line will select both lines and all the lines between them. Control-Click on a line will add that line to the set of currently selected lines.

Once one or more lines have been selected, you can select the "Execute" function (from the Right-Click context menu) to perform the (pre-defined) action on the highlighted records. Or, more typically, you can just Double-Click on a single line to execute that record. As mentioned, the execute function is most commonly configured to load the selected record into an associated editing pane.

Modifying the Column Sizes

The DBP widget is built from multiple listboxes arranged side by side. Each listbox holds a column of similar data. There are small separator lines between each of the columns that can be used to drag the columns, making them wider or narrower.

The first time a DBP widget starts up on the screen, it will probably not be configured very well for reasonable column widths. One way to fix this is to simply drag the separator bars to size each of the columns to your liking. Another way is to first load the widget with some data (by using the Default load option, for example), and then press the small button in the lower right corner of the DBP (or execute the "Autosize All" function from the Right-Click context menu).

Once you have the columns sized the way you want, it is a good idea to close the toplevel window that contains the widget and then reopen it. From then on, the program should remember the way you have the columns sized.

Modifying the Column that Display

It is also possible from the Right-Click context menu to change what database columns to display in the widget. There is a menu option "Hide This Column" that will remove the column you clicked on from the display. There is a menu option "Show Column" that will allow you to select new columns that may not be presently showing.

When you add a new column, it will typically be added on the right side of the existing columns. You can re-arrange the columns by drag-and-drop. Grab the title of a first column with the cursor middle button and drag it on top of a second column to insert the first column just before the first one.

Note that when you add a new column, it may not be populated with any data. You may have to execute the Reload function to fetch the appropriate column data from the database.

Sorting the Data

Just to the right of each column title is a sort button and presidence indicator. The sort button is similar to those found in many programs--when you press it, the data will be sorted according to that column. Press it again, and the data will be sorted in reverse order according to that column. A small arrow will appear on the button to show if the sort is normal or reversed.

In addition to this normal sort behavior, the DBP can sort on multiple columns. After sorting on one column, now press the sort button for a second column. The data will now be sorted primarily according to the second column. But any time, the contents of that column are the same for two or more records, those records will be sorted secondarily on the basis of the first column.

When sorting on multiple columns, you can tell the precidence of each column by a number which will appear next to the sort button. The number "1" indicates that this is the primary sort column. The number "2" indicates the secondary sort column and so on. You can remove a column from the sort order by Right-Clicking on the sort button.

When this widget is associated with a database table, the sort buttons will cause the data to be reloaded from the database each time you press a sort button. For large sets of data, this can be slow sometimes. When the widget is not associated with a database table (it just contains data local to the application), the widget itself does the sorting according to a separate algorithm.

Standard Menu Functions

Like many other widgets, DBP has a menu near the upper left corner of the widget where you can find the available functions for the widget. The title on this menu is typically something like "Table Preview:" where "Table" is the name of the database table the widget draws its data from. This menu contains standard functions mostly for selecting and executing records in the preview.

Depending on the application, the menu may contain some or all of these functions. Also, the application may contain shortcut buttons for some or all of these functions. The shortcut buttons can be found somewhere in the menu bar (typically just to the right of the widget menu). They may have slightly different (typically shorter) titles, but the help popups will be identical to those for the functions in the menu which they represent.

Clear

This will empty the preview so it does not contain any records.

Default Load

This will invoke the menu function "Search For Records" but will execute a saved query that is predefined by the program. For example, in the employee contact information manager, it will load all "current" employees. In the payroll module, it might load all checks needing to be paid.

It is possible to create a saved query (with the name "default") that will become the new default query. See the DBS help document for more information on this.

Reload

This will request data from the database according to the same critiera as the last time the preview was loaded. Sometimes, data can change in the database (like when someone else updates a record) without you knowing about it. When you press Reload, you will get the latest data again fresh from the database.

Load All

This will query the database, asking for all records the preview is capable of loading. Beware, on large databases, this may take a long time. In most cases, it is probably better to use the "Search For Records" (Srch) function.

Previous Record

If a record is currently selected in the preview, this function will change the selection to the record just above it and then will execute that record. Executing a row usually (but not always) causes the record to be loaded into an associated DBE widget. This button is helpful for browsing through multiple records in reverse order. If you press and hold the button, it will repeat.

Current Record

If a record is currently selected in the preview, this function will cause it to be executed again. This is very similar to the Execute function in the context menu.

Next Record

If a record is currently selected in the preview, this function will change the selection to the record just below it and then will execute that record. Executing a row usually (but not always) causes the record to be loaded into an associated DBE widget. This button is helpful for browsing through multiple records in forward order. If you press and hold the button, it will repeat.

Search For Records (Srch)

This will launch a DBS (DataBase Search) widget which will allow you to select certain records from the database according to search criteria you define. This is often referred to as a "query" of the database. Once you have defined a set of query criteria, you can then save your query with a name, so you can use it again later.

Open the DBS widget and then access the help page from its main menu to learn more about how to use it.

Auto Execute

This menu function is a checkbox which can be enabled or disabled. Sometimes, there will also be a clone copy of this checkbox visible toward the right side of the widget menu bar.

When enabled, this will cause the Execute function to be triggered each time the preview is loaded from the database. This can be handy when you want to update a bunch of records.

For example, you can configure a Query to load the preview with all records with a certain value (which you want to change). The only records then showing are the ones you want to modify. Execute the first record in the preview to load it into the associated DBE (editing) widget. Modify the data and press the update button.

When the record is modified, the preview will be reloaded according to the previous search criteria. Because you changed the data, the modified record should no longer show up in the preview list. Now there should be one less record in the list (see the record count in the upper right corner). Additionally, because the Auto Execute function was checked, the next record in the preview will now be highlighted, and that record will have automatically been loaded into the DBE widget, ready for you to make your changes to it as well.

Each time you update a record, it will fall out of the list and the next record will be loaded for you. When there are no more records in the preview, your work is done.

Context Menu Functions

In addition to the main widget menu, there is also a context menu that can be invoked by Right-Clicking anywhere inside the preview box. The first few functions pertain to a single column, so make sure you click on the column you want to modify if you are using one of those functions. The rest of the functions operate on the preview as a whole, so it doesn't matter where you click for them.

The functions in the context menu don't have anything to do with database access. Rather, they pertain more to the display and control of data once it is loaded into the preview.

The available functions are as follows:

Find in This Column

This will invoke a search function on the column you clicked on. There is no way currently to search for a value across all the columns so you need to know which column you would expect the data to appear in. The search function is similar to what you would find in a text editing widget.

Hide This Column

This will cause the selected column to be removed from the display. If the column is part of the primary key for the table, the column will still fetch data from the database on loads--it will just not be displayed. (See the section on how data is stored in the Standard Features manual for more on primary keys.) Otherwise, the column will not fetch data. So if it is added again later, it may contain obsolete data or no data at all.

As a precaution, you should generally do a Reload any time you add a new column to the display.

Autosize This Column

Typically the display width of each column is arbitrary (just set to some meaningless default). After fetching data from the database, you may see that the column is not wide enough and you will have to use the small scroll bar to see all the data. This function will make the column wide enough to show all its present data.

Show Column

This will allow you to add more columns to the display. Each database table (or view) has a fixed number of columns available to view. Typically, not all of them will be a part of the display when you start the application. This allows you to customize the display to your liking.

Note that when a new column is added, the display may not contain any data. You must press the Reload button to populate it with data.

This is done for the sake of efficiency. Some columns are slower to compute in the database. By asking for only the columns that are part of the display, the program can run faster.

Execute

This will cause the predefined action to be performed on the selected record(s). Most commonly, this means that the highlighted line will be loaded into the associated DBE editing pane. In some cases, the DBP may configured to perform some other action on execute.

Print

This will render the contents of the preview window as a text file and then allow you to send it to a printer. The widths of each column will be approximated to be similar to what is shown on the screen. So if you have not sized all the columns wide enough, it is possible to have missing text on the printout. Exporting the data to a spreadsheet (see below) is an alternate method for printing the preview contents.

Export to File

This will allow you to write the contents of the preview out to a CSV (Comma Separated Values) file. This is a common format for the interchange of columnar data. All the data will be exported without regard to the way it displays on the screen (column widths).

Export to Spreadsheet

This function exports to a CSV file, but then it also launches the Open Office spreadsheet program on the file automatically.