PLEASE NOTE: Our Web site uses cookies to help improve your browsing experience while here and to provide us with information on how you use our site. Click here to see the cookies we use. Click here to learn how to delete and block cookies (if you block cookies, parts of our Web site will not work). If you do not modify your cookie settings, then we take that to mean you are happy with the default and that you are explicitly consenting to our use of the cookies as described.

Check the box to close this pop-up.

 
Sybase Business Intelligence Solutions - Database Management, Data Warehousing Software, Mobile Enterprise Applications and Messaging
Sybase Brand Color Bar
delete

Search for    in all of Sybase.com
view all search results right arrow
  blank
 
 
 
 
 
Support > Technical Documents > Document Types > Technote > PFC Datawindow Filter Service

PFC Datawindow Filter Service

This document provides instructions for using the service in an application, and includes end-user usage information for each of the filter dialogs.
 
RSS Feed
 
 
 
PFC Datawindow Filter Service
 

The datawindow filter service allows the end user to specify filter criteria for datawindow data.
There are several different styles of filter dialogs available with the service.

This document provides instructions for using the service in an application, and includes end-user usage information for each of the filter dialogs.

Service Benefits

The benefits of using the PFC datawindow filter service include the following:

-- A choice of three different styles of filter dialogs.
The styles include the standard PowerBuilder filter dialog, and two PFC filter dialogs.

The two PFC filter dialogs provide additional functionality:
-- The ability to exclude columns from the filter dialogs, including specific column names
or all invisible columns
-- The ability to specify whether the list of columns should show the database column
names, datawindow column names, or column header names
-- The display of data values for the chosen column for the user to pick from

Using the Filter Service

Following are the steps, and sample code, to use the datawindow filter service in a PFC
application. The example code assumes a control named dw_1 which was inherited from u_dw.

1.) Enable the service for a specific datawindow control. For example:

/* Enable the filter service */
dw_1.of_SetFilter(TRUE)

2.) The service allows you to specify if the user should be presented with the standard
PowerBuilder filter dialog, the PFC simple dialog, or the PFC extended dialog.

The standard PowerBuilder filter dialog is used by default,. If you wish to use one of the
PFC filter dialogs, specify the desired filter dialog style. The following script indicates that
the PFC extended filter dialog should be used with the service.

/* Specify 1 for extended filter style */
dw_1.inv_filter.of_SetStyle(1)

or use the property
 dw_1.inv_filter.of_SetStyle(dw_1.inv_filter.EXTENDED)

Detailed information for each of the filter dialog styles is contained later in this document.

3.) The datawindow column names are used within the filter dialogs by default.
If you use one of the PFC filter dialogs (see step 2), you have the choice of using
database column names, or datawindow column header names instead.

For example:

/* Use dw column header names within the dialogs */
dw_1.inv_filter.of_SetColumnDisplayNameStyle(2)

or use the following property:

dw_1.inv_filter.of_SetColumnDisplayNameStyle(dw_1.inv_filter.HEADER)
 

Note: The of_SetColumnDisplayNameStyle function is defined on the base datawindow
service (n_cst_dwsrv) but may be referenced through the instance of the filter
service (inv_filter is a reference to n_cst_dwsrv_filter) since the filter service is a
descendant.

The of_SetColumnDisplayNameStyle method has no affect with the standard PB filter dialog.

4.) All columns are included in the filter dialogs by default.
If you use one of the PFC filter dialogs (see step 2), you have the choice of excluding some
columns from the dialog. For example:

/* Exclude all hidden columns from the dialog */
dw_1.inv_filter.of_SetVisibleOnly(TRUE)

/* The remaining script excludes one specific column
from the dialog */

/* declare a string array */
string ls_exclude[]

/* add desired column names to string array */
ls_exclude[1] = "last_name"

/* call function with populated string array */
dw_1.inv_filter.of_SetExclude(ls_exclude)

The of_SetExclude and of_SetVisibleOnly functions have no affect with the standard
PB filter dialog.

5.) There are several different ways to filter the data. The method you choose depends on
whether or not you want the filter dialog to display to the user, and if you want the
filter to be automatically applied after displaying the dialog.
More detail on each method follows.

a.) Use the PFC menu to display the filter dialog.

The PFC menu m_master includes a menu item to display the filter dialog.
If you inherit a menu from m_master, the user may choose Filter from the View
menu to trigger the pfc_FilterDlg event on the last datawindow control that had focus.

The pfc_FilterDlg event will trigger processing that causes the filter dialog to display,
and apply the filter criteria when the user clicks OK on the dialog.

If the user chooses the Filter menu item from a window that has not given
focus to a datawindow control since the window was opened, the menu
item will not cause the filter dialog to display. This is because the control's
pfc_filterdlg event will not be triggered by the PFC message router.

Refer to Chapter 1 of the PFC User Guide for more information on the message router.

b.) Programmatic display of the filter dialog, with automatic application of the filter

You may trigger the pfc_FilterDlg event on the datawindow control, to display
the filter dialog then automatically apply the filter when the user clicks OK on the
dialog. For example:

/* Cause the dialog to display and filter to be applied */
dw_1.EVENT pfc_FilterDlg()

c.) Programmatic display of the filter dialog, with programmatic application of the filter

Rather than triggering the event, you may call a set of functions to display the dialog
then apply the filter, as shown in the following sample script.

/* declare a string variable */
string ls_null

/* set the string to null */
SetNull(ls_null)

/* pass the null string to the of_SetFilter function, to cause
the filter dialog to display to the user */
dw_1.inv_filter.of_SetFilter(ls_null)

/* apply the filter */
dw_1.inv_filter.of_Filter()

The of_Filter function will apply the filter, then trigger the pfc_rowchanged event
on the datawindow control.

d.) Omit display of the dialog, and directly apply a filter instead.

The following script directly passes a filter string to the of_SetFilter function,
then calls the function to apply the filter.

/* set filter criteria directly */
dw_1.inv_filter.of_SetFilter("dept_id = 100")

/* apply the filter */
dw_1.inv_filter.of_Filter()

The of_Filter function will apply the filter, then trigger the pfc_rowchanged event
on the datawindow control.

Note: Always use the datawindow column names, even if you previously called
of_SetColumnDisplayNameStyle to indicate a different display choice for dialogs.

Filter Dialog Styles

There are three different styles of filter dialogs available with the service:

-- Standard (Default) PowerBuilder Filter Dialog
-- PFC Simple Filter Dialog
-- PFC Extended Filter Dialog

The following sections contain usage information for each of the dialog styles.

Standard PowerBuilder Filter Dialog

This is the standard filter dialog provided by PowerBuilder.
It includes a list of datawindow functions, and a list of all columns on the datawindow.
The dialog allows the user to paint a filter expression and validate it.

More information on the standard dialog is contained in the "Filtering Rows" section of the PowerBuilder User's Guide.

Filter Validation

For valid expressions, the following messagebox displays when the user clicks Verify.


 

For invalid expressions, the messagebox describes why the expression is not valid.
In the following example, an incorrect data type was specified for a column, i.e., a string value for an integer column.

The messagebox will appear if the user clicks Verify, or clicks OK to try to apply a filter that is not valid.

PFC Simple Filter Dialog

The w_filtersimple dialog presents dropdowns, allowing the user to choose columns, values, and associate multiple criteria associated with and/or conditions.

The dialog initially displays with four empty dropdowns.

Columns

The first dropdown presents a list of the datawindow columns to choose from.
The datawindow column names are used, unless otherwise specified with the of_SetColumnDisplayNameStyle function. If previous calls were made to of_SetVisibleOnly or of_SetExclude, the appropriate columns are omitted from the list.

Click on the desired column.
 

Equality Operators

The second dropdown presents the equality options.

Click the desired choice.

Data Values

The third dropdown lists the data values for the chosen column. The values that are listed depend on the column edit style.

If the column has an edit style of DropDownDataWindow, DropDownListBox, RadioButton, or Checkbox, the values listed are those available from the edit style.

Otherwise, a sorted list of the unique column values from the database is provided.

Note: The values dropdown is not populated if the datawindow presentation style is External.

Click on the desired value.

Criteria Relationships

The last dropdown allows for the concatenation of additional criteria using And or Or.
This allows you to specify how the criteria will be related to the next criteria.

If no additional criteria is required, do not select an item from the last dropdown, and choose OK.

To continue with additional criteria, choose And or Or from the last dropdown, to indicate how the criteria should be used.

When you choose a value in the last dropdown (And/Or), a new line is added automatically to continue with the next criteria.

Click OK to apply the filter, or Cancel to close the dialog without applying a filter.

Filter Validation

If the filter criteria is not valid, a messagebox displays.


 

Following is an example of invalid filter criteria, since two lines are used but their relationship is not specified with And or Or. This type of scenario would occur if the user did not choose a value in the last dropdown and clicked the Add button to specify additional criteria.


 

Previously Applied Criteria

Once a filter has been applied, it is shown in subsequent displays of the dialog, as shown in the Original Filter Criteria section of the following example.

Note that the criteria is shown using datawindow column names, even if another display choice was specified with of_SetColumnDisplayNameStyle.

 
 

With the PFC simple filter dialog, the user does not have the option to delete previous filter criteria.

To remove filter criteria that was previously applied, write script to set the filter to an empty string and re-apply the filter. For example:

/* set the filter to an empty string */
dw_1.inv_filter.of_SetFilter("")

/* apply the filter */
dw_1.inv_filter.of_Filter()

PFC Extended Filter Dialog

The w_filterextended dialog is the most flexible. It allows the user to choose from lists of datawindow functions, columns, operators, and column values to build a filter expression.

Functions

The Functions tabpage lists the datawindow functions grouped by category. Click a category (for example, Conversion) to list the associated datawindow functions.

Click on a function to show argument information and a description in the Syntax groupbox.
Double-click a function (for example, Asc) to paste it into the Filter expression.
The function is pasted in the current position, and includes placeholders for the function arguments.

Columns

The Columns tabpage presents a list of the datawindow columns.
If previous calls were made to of_SetVisibleOnly or of_SetExclude, the appropriate columns are omitted from the list.

The datawindow column names are used for the list, unless otherwise specified with the of_SetColumnDisplayNameStyle function. Note that the datawindow column names are pasted into the expression, even if the column header names or database names are used for display within the column list.

Double-click a column to paste it in the current position of the Filter expression.
 

Operators

The operators tabpage lists the equality operators for use in the expression.

Double-click an operator to paste it in the current position of the Filter expression.

Data Values

The third dropdown lists the data values for the chosen column. The values that are listed depend on the column edit style.

If the column has an edit style of DropDownDataWindow, DropDownListBox, RadioButton, or Checkbox, the values listed are those available from the edit style.

Otherwise, a sorted list of the unique column values from the database is provided.
Note: The values list is not populated if the datawindow presentation style is External.

Double-click a value to paste it in the current position of the Filter expression.

Filter Validation

When the user clicks OK from the filter dialog, a messagebox displays if the filter criteria is not valid.


 

If the user clicks Verify from the filter dialog, the following messagebox displays if the expression is not valid:

When the user clicks Verify, the following messagebox displays for valid expressions:


 

Previously Applied Criteria

Once a filter has been applied, it is shown in subsequent displays of the dialog, as shown in the following example.

Note that the criteria is shown using datawindow column names, even if another display choice was specified with of_SetColumnDisplayNameStyle.

To clear the filter criteria, the user may delete the filter expression and choose OK.

Filter criteria may also be cleared programmatically with script to set the filter to an empty string and re-apply the filter. For example:

/* set the filter to an empty string */
dw_1.inv_filter.of_SetFilter("")

/* apply the filter */
dw_1.inv_filter.of_Filter()

For more information on the datawindow filter service, refer to the PFC Object Reference.


 

DOCUMENT ATTRIBUTES
Last Revised: Jun 28, 2004
Product: PowerBuilder
Technical Topics: Application Development
  
Business or Technical: Technical
Content Id: 44546
Infotype: Technote
 
 
 

Home / Contact Us / Help / Jobs / Legal / Privacy / Code of Ethics
© Copyright 2014, Sybase Inc. - v 7.6
Sybase (UK) Limited, Sybase Court, Crown Lane, Maidenhead, Berkshire SL6 8QZ is a company incorporated in England & Wales under company registration number 2175260