fgl_zoom is a Genero library you can use to code all your zoom windows. What is a zoom window, alternative names include lookup window, query window, pick list. It is a window that appears when you click on a BUTTONEDIT button that allows you to select a value that will then be entered into the BUTTONEDIT field.
We typically see this pattern when entering what is a foreign key to another table. The BUTTONEDIT requires entry of the key field and the zoom window allows you to list the key and data fields of the referenced table and to select a value. To narrow the list, a QBE option may also be available.
These screenshot illustrates a typical usage,
A BUTTONEDIT is used for the State code ...
User clicks on the BUTTONEDIT button, a window appears with a list of values
The user selects a state that is in turn passed back to the BUTTONEDIT field
Sometimes you may even display a description as well
If the list of values is long, before you display the list, you may enter some QBE Criteria to reduce the number of values displayed in the list
For the pattern decribed previously, for each these zoom windows, we would typically see a FUNCTION with a FOREACH to read the database, a DISPLAY ARRAY to list values, and an OPEN WINDOW, and .per for the UI. We would see one of these for EACH zoom window and this code will typically be repetitive/duplicated making maintenance expensive.
So say you had 100 zoom windows, instead of 100 functions, 100 forms, 100 database cursors, 100 display arrays, with fgl_zoom there is a single library with one lot of database code, one lot of UI code etc. This ensures a consistent user interface and makes code maintenance a lot cheaper.
The fgl_zoom_test program consists of a form of three tabs
Illustrates potential uses. Click on the BUTTONEDIT button and note the window that appears. To view the 4gl source the junior developer would require, click on the View Source button. In most cases, it is less than a screenful of 4gl source. In the following screenshots, the list on the left is coded by the code you see on the right.
fgl_zoom has a number of configuration parameters. The functional test tab is used to test each of these parameters in isolation. You can also look at the source to see the function name and expected parameters.
The custom tab allows you to experiment and create some fgl_zoom code.
Enter the appropriate parameter
Click Execute to run the resultant zoom window(s)
View Source to see the 4gl source required in your program.
For these refer to the Configuration Tab, or the Functional Test Tab to observe the difference in behaviour.
The SQL to be used to access the database. There are two placeholders. Enter %1 to indicate where the where clause generated by the QBE Window is to be inserted into the SQL. Use %2 to generate the column list from the column definitions below. A typical value maybe something like SELECT %2 FROM tablename WHERE %1 ORDER BY id
Check to derive the column data from the SQL parameter
Title to appear in the QBE and List Window
If the user selects cancel, what is the value returned. Typically populated with FGL_DIALOG_GETBUFFER() so as not to remvoe the existing value.
Set to TRUE to disable the QBE Window. This means that all the values that match the entered SQL will appear in the List Window.
Set to TRUE to disable the List Window. This means that the where clause generated by the QBE is the value returned.
Determine if the QBE or List Window is the first window shown. Default is QBE Window.
If only one row is returned by the display, do not display the List Window and return immediately with that one value.
Set to TRUE if you want to allow the user to select multiple rows.
Put a restriction on maximum number of rows returned.
Allow a certian number of columns to be frozen so that they are always in view and not scrolled out
Set to TRUE if you want to force the user to enter at least one value in a QBE field
The remainging properties are duplicated for each column. To quickly define column information, there are two functions which may help.
If you call fgl_zoom.column_auto_set(), it will derive all the column data from the columns you enter in the sql_set() function. In this instance, title is replaced by the column name with _ turned to spaces and the first letter of each word capitalised.
The other function which can aid developer productivity is the column_quick_set() function. Called once for each column, it takes 5 parameters... an index integer column name a one character code c,d,f,i for the database type, char, date, float, integer respectively a width a title ... and saves typing each of these functions.
Name of the database column as used in SQL statement.
Title of the column, appears as the column header.
The initial display width to be used for the column
For numeric and date data, the format to be used.
The datatype of the column. We don't need exact datatype but need to differentitate Character, Date, Integer, Numeric for sorting and display purposes.
The justification left, right, center used for the column.
Set to TRUE if you do not want to see the column appear in the QBE Window.
Set to TRUE if you do not want to the see the column in the list of results.
Set to TRUE to include the value in the result set. Typically you would ensure that one column has this set to TRUE although you can set it in multiple columns for composite keys, or if you want to return code and matching description values.
Initial value to be used in the QBE field.
Require the user to enter a value in the QBE for that column.
The use of Dynamic Dialogs will make it difficult to port this code to Genero versions prior to 3.00. The module was originally written using Genero 2.30 so if you use GitHub to retrieve old versions of the code, you can probably put something together but I would suggest you upgrade to at least 3.00.
To incorporate fgl_zoom into your own application.
Compile and llace fgl_zoom.42m, fgl_zoom.42s where they will be found by FGLLDPATH, FGLRESOURCEPATH, DBPATH etc. as used by your application.
Merge the contents of fgl_zoom_test.4st into your applications own style file. You may wish to amend the styles used in fgl_zoom_test.4st so that it matches your own applications look and feel.
Merge the contents of fgl_zoom.str into your own string localization mechanism. You could do as the test program does and simple add fgl_zoom.42s to the list of specified files by the fglrun.localization.file settings in FGLPROFILE.
It is intended that you would create some wrapper routines that wrap around a series of fgl_zoom calls e.g.
IMPORT FGL fgl_zoom
FUNCTION zoom_tabid()
DEFINE z fgl_zoom.zoomType
DEFINE tabid INTEGER
CALL z.init()
LET z.sql = "SELECT tabid, tabname FROM systables WHERE %1"
CALL z.column[1].quick_set("tabid",true,"i",4,"ID")
CALL z.column[2].quick_set("tabname",false,"c",20,"Name")
CALL z.call() RETURNING tabid
RETURN tabid
END FUNCTION
and you would call your wrapper routine from your DIALOG statements e.g.
ON ACTION zoom INFIELD tabid
LET tabid = zoom_tabid()
Intended usage would follow this broad pattern.
Define a variable for the zoom window
DEFINE z fgl_zoom.zoomType
To clear the fgl_zoom settings, use the following call
CALL z.init()
To configure, you can use one or more of the following functions
LET z.sql =sql - define the SQL used in the zoom. This SQL should have %1 where the where clause will be substituted with the result of the QBE. Optionally you can also include a %2 in place of the columns e.g. SELECT %2, and the columns will be populated from the additional column definition functions.
LET z.title = STRING - set the title of the zoom window
LET z.cancelvalue = STRING - the value to return if user cancels
LET z.noqbe = BOOLEAN - set to true if you dont want the QBE window to appear
LET z.nolist = BOOLEAN - set to true if you dont want the List of results to appear
LET z.gotolist = BOOLEAN - set to true to dislay the results first without initially doing a QBE
LET z.autoselect = BOOLEAN - set to true if you want the window to return immediately if only row is found
LET z.multiplerow = BOOLEAN - set to true to allow the user to select multiple row
For each column specified in the call to fgl_zoom.sql_set() you would specify one or more of the following functions
LET z.column[COLUMN].column = STRING - The SQL column name
LET z.column[COLUMN].title = STRING - The title of the column
LET z.column[COLUMN].format = STRING - The format to display the column
LET z.column[COLUMN].datatypec = ["c"|"d"|"f"|"i"] - Set the datatype of the column, (c)har, (d)ate, (f)loat, (i)nteger
LET z.column[COLUMN].width = INTEGER - The width of the column
LET z.column[COLUMN].justify = ["left"|"right"|"center"] - Set the justification of the column
LET z.column[COLUMN].excludeqbe = BOOLEAN - Set to true to exclude column from QBE
LET z.column[COLUMN].excludelist = BOOLEAN - Set to true to exclude column from result list)
LET z.column[COLUMN].includeinresult = BOOLEAN - Set to true to include column in return values
LET z.column[COLUMN].qbedefault =STRING) - Default expression to set in QBE field
To ease programming an ease of access function is provided to set a column quickly in one line
CALL z.column[COLUMN].quick_set(column_name, includeinresult, datatypec, width, title)
This sets the column_name, include in result flag, datatype indicator, width of column, and the title of a column. THis is considered minimm required to be set. It will also set jusitfy=right for a numeric column. Typically you would set includeinresult flag to true for the first column, false otherwise
To execute the zoom window, there is a choice of 2 methods
CALL z.call() RETURNING STRING - Execute the zoom window and return the value in the first column of the first row selected
OR
CALL z.execute() - Execute the zoom window
You then refer to one of the following variables to get the selected info
z.result[ROW,COLUMN] - Return the value in the specified ROW,COLUMN of the selected rows
z.result.getLengt() - Return the number of rows selected
z.where - Return the QBE clause generated in the QBE screen
z.qbe - Return the selected values pipe delimited suitable for inclusion in a CONSTRUCT field
z.result[1].getLength() - Return the number of columns in the result selected
The following is an examle of a simple zoom window call
CALL z.init()
LET z.sql = "SELECT tabid, tabname FROM systables WHERE %1"
CALL z.column[1].quick("tabid",true,"i",4,"ID")
CALL z.column[2].quick("tabname",false,"c",20,"Name")
CALL z.call() RETURNING tabid
The routines here are based on Quanta's query_win(). This can be found in the IIUG repository (https://sourceforge.net/projects/iiug-software-repository/files/Informix4GL-Tools/query_win/)
Century also had a similar routine that ran off database entries. It would be possible to implement these routines to run off some database or XML configuration so that changes didn't require compilation.