exploiting the gui - extending the browse widget

Exploiting the GUI –Extending the “Browse” Widget

Hansdip Singh Bindra

Phone: (973) 361-4224 Fax (973) 537-6946E-Mail: [email protected]: www.innov8cs.com

© 1999-2005. Innov8 Computer Solutions, LLC. – Transforming Business Processes into Software…™

Overview:

• Most important part of a "successful" business application? User Interface (UI)

• 4GL Flexibility + Effective Design Techniques = Successful and Effective UIs

• Expand 4GL widgets and constructs for “Rich" UI

• “Super-Widgets” like Browse-based Viewers

© 1999-2005. Innov8 Computer Solutions, LLC. www.innov8cs.com

Extending the “Browse”

“Super-Widgets”• Visual Basic and Delphi have “cool” and

“native” ActiveX controls• Controls can be used in Progress; but not with

the ease of 4GL, nor as “native” objects • “Super-Widgets” are totally built with the 4GL


“Super-Widgets” - Detail

• Browse-based Viewer

• Drop-Down Button-List (Browse)

• Updateable Browse Enhancements

• Extras…Tips & Tricks


Browse-based Viewer -Overview:

What is a Viewer?• Group of “display widgets” such as non-sensitive Fill-Ins stacked

below a main Browse

• Used in Inquiry or Information Retrieval applications

Why a Browse based Viewer?• Simple UI with uniform “Look and Feel”• Similar to ActiveX Grids with “Label” and “Value” cells• Takes up less area than stacked Fill-Ins• Customize Viewer colors/fonts at runtime


Browse-based Viewer - Comparison

Regular Viewer made up of Stacked Fill-Ins

Browse-based Viewer© 1999-2005. Innov8 Computer Solutions, LLC. www.innov8cs.com

** DEMO **

Browse-based Viewer -Components:

• Browse Widget• Temp-Table• Temp-Table Buffers• Free Form Query• 4 Internal Procedures


Browse-based Viewer -Browse Properties:

Property Value Enabled NO Multiple-Selection YES No-Labels YES Open the Query YES Scrollbar-Vertical NO Separators YES


Browse-based Viewer -Temp-Table and Associated Buffers:

• Temp-Table based

• Example: “Static” Temp-Table and Browse widget for simplicity

• Can construct with “dynamic” Temp-Table and Browse widget

• Number of Buffers = Number of Rows in Viewer

/** Define Temp-Table for Browse based Viewer **/DEFINE TEMP-TABLE TempBrowseViewer NO-UNDO

FIELD LineNo AS INTEGERFIELD Label01 AS CHARACTERFIELD Value01 AS CHARACTERFIELD Label02 AS CHARACTERFIELD Value02 AS CHARACTERINDEX LineNo IS PRIMARY UNIQUE LineNo ASC.

/** Define Buffers for each Row of the Viewer **/DEFINE BUFFER TempBrowseViewer-Line01 FOR TempBrowseViewer.DEFINE BUFFER TempBrowseViewer-Line02 FOR TempBrowseViewer.DEFINE BUFFER TempBrowseViewer-Line03 FOR TempBrowseViewer.DEFINE BUFFER TempBrowseViewer-Line04 FOR TempBrowseViewer.DEFINE BUFFER TempBrowseViewer-Line05 FOR TempBrowseViewer.


Browse-based Viewer -Free Form Query:

• Simple FOR EACH Query attaches Temp-Table to Viewer’s Browse• “Value” cells have default foreground/background colors• Easier readability than non-sensitive Fill-Ins with grayscale colors

TempBrowseViewer.Label01 FORMAT "X(15)":U COLUMN-BGCOLOR 8TempBrowseViewer.Value01 FORMAT "X(38)":U TempBrowseViewer.Label02 FORMAT "X(15)":U COLUMN-BGCOLOR 8TempBrowseViewer.Value02 FORMAT "X(38)":U.


Browse-based Viewer -4 Internal Procedures:

• TempViewerCreateProc

• TempViewerFillProc

• TempViewerQueryProc

• TempViewerRowDisplayProc


Browse-based Viewer -TempViewerCreateProc:

• Creates Temp-Table Rows• Executed before Window or Dialog-Box is realized• Assigns data to “Label” cells• Uses all Associated Buffers• Buffers are locked in default “Update” mode• Buffers are updated in other Internal Procedures without Re-Finds

CREATE TempBrowseViewer-Line01.

ASSIGN TempBrowseViewer-Line01.LineNo = 1 TempBrowseViewer-Line01.Label01 = "Address 1:"TempBrowseViewer-Line01.Label02 = "Sales Agent:".


Browse-based Viewer -TempViewerFillProc:

• Main Procedure for Viewer• Called from VALUE-CHANGED for main Browse, e.g. Customer List• Assigns data to “Value” cells

• One Input Parameter inType – Values “Assign/Initialize”

CASE inType:

WHEN "Assign":U THENASSIGN TempBrowseViewer-Line01.Value01 = Customer.Address

TempBrowseViewer-Line01.Value02 = Customer.Sales-Rep...

WHEN "Initialize":U THENASSIGN TempBrowseViewer-Line01.Value01 = ""

TempBrowseViewer-Line01.Value02 = ""...

END CASE.


Browse-based Viewer -TempViewerQueryProc:

• Re-opens Temp-Table Query associated with Viewer• Called from VALUE-CHANGED for main Browse• Executed after TempViewerFillProc• Contains simple FOR EACH on Temp-Table

/** If Customer is selected then Fill Browse based Viewer with Customerinformation, otherwise initialize the Viewer

**/

IF AVAILABLE Customer THENRUN TempBrowseViewerFillProc(INPUT "Assign":U).

ELSERUN TempBrowseViewerFillProc(INPUT "Initialize":U).

/** Refresh Browse based Viewer **/RUN TempBrowseViewerQueryProc.


Browse-based Viewer -TempViewerDisplayProc:

• Central location for customizing color/font for “Value” cells• Change properties for a single cell without changing entire Column

IF TempBrowseViewer.LineNo = 3 THENDO:

/* If Balance exceeds Credit Limit - Red otherwise Green */IF AVAILABLE Customer AND

Customer.Balance > Customer.Credit-Limit THENASSIGN TempBrowseViewer.Value02:BGCOLOR IN BROWSE browseViewer = 12.

ELSEASSIGN TempBrowseViewer.Value02:BGCOLOR IN BROWSE browseViewer = 10.

END....


Drop-Down Button-List (Browse) -Overview:

Why?• Similar to Drop-Down Grids in Visual Basic or Delphi• “Data Aware” Combo-Box• Standard “Look and Feel” – http://mspress.microsoft.com/prod/books/2466.htm

• “Black-Box” philosophy – Reusable• Replaces ActiveX Grids and SO Selection Browses

Advantages

• Performance – Reads data from data set as needed• Browse can be tied to Table, Temp-Table, FDO, and even SDO• User’s focus remains on main Window


http://mspress.microsoft.com/prod/books/2466.htm

Drop-Down Button-List (Browse) - Comparison

Traditional Selection Browse

** DEMO **

Drop-Down Button-List (Browse)


Drop-Down Button-List (Browse)Components:

• Visual – Fill-In and GUI Button widgets• Browse widget (with associated Query)• Frame widget (for Browse)• One External (or Super) Procedure (.p or .w)


Drop-Down Button-List (Browse)Visual Layout/Setup:

• Browse (associated Query) defined in External (Frame) Procedure• Linked to main Window through CHOOSE of Down Arrow Button• API Driven – “Customizable”• External Procedure outputs three Values

Widget Width Height Row ColumnFill-In <varies> 1.00 <varies> <varies>Button 4.20 1.14 Fill-In Row – 0.05 Fill-In Column +

Fill-In WidthBrowse <varies> Normally 6 Fill-In Row + 1 (for Drop

Down) or Fill-In Row –Browse Height (for Drop Up)

Normally Fill-InColumn (Left-Edge)

All values in Characters


Drop-Down Button-List (Browse)API and Result Value:

RUN DropDownCustomer.p (INPUT {&WINDOW-NAME}:HANDLE, /* Parent Handle */INPUT scrCustomerName:ROW + 1, /* Row */INPUT scrCustomerName:COLUMN, /* Column */INPUT 1, /* Number of Locked Cols */INPUT "Double-Click to select Customer",/* ToolTip */INPUT YES, /* Reposition */INPUT SELF:HANDLE, /* Initial Widget - Focus */INPUT scrCustomerName, /* Position to Row Value */OUTPUT localValidResult, /* YES/NO */OUTPUT localWidgetHndl, /* Final Widget - Focus */OUTPUT localRowid). /* Result – Value */

• Valid Result = YES (Double-Click on Row): Process Result Value• Simple data-type (i.e. CHARACTER): ASSIGN to Fill-In • ROWID or multiple Fields: FIND appropriate data, then ASSIGN• Valid Result = NO (Click outside Browse): Provide Focus (or Default

Action) to Output Widget Handle


Drop-Down Button-List (Browse)External Procedure – Overview:

• “Action” Object• Develop once, then Reuse• Save as .p, or .w (suppressed Window)

• Major Components– Fixed (Internal/Standard) Sections – Customizable Sections

• Fixed Sections: 4 Include Files (Require NO Modifications) • Customizable Sections: Modify for particular Application/Table(s)


Drop-Down Button-List (Browse)External Procedure – Fixed Sections:

4 Include Files• DropDown-InputParameters.i

– Define ALL (7) Fixed Input Parameters

• DropDown-OutputParameters.i– Define ALL (2) Fixed Output Parameters

• DropDown-MainBlock.i

• DropDown-Enable_UI.i



DropDown-MainBlock.i• LEAVE Browse Frame CLOSE Procedure HIDE Browse• Informs PARENT Window that CHILD Drop Down Browse is Open• Input Parameters ASSIGN Browse Properties

– PARENT Window or Frame– ROW and COLUMN– TOOLTIP and HELP– NUM-LOCKED-COLUMNS, etc.

/** Set Parent for Browse Frame **/IF inWindowHndl:TYPE = "WINDOW":U THEN

ASSIGN inWindowHndl:PRIVATE-DATA = "<DropDownFileOpen>":UFRAME frameDropDown:PARENT = inWindowHndl.

ELSEASSIGN FRAME frameDropDown:FRAME = inWindowHndl.



DropDown-Enable_UI.i• ENABLE Browse widget on Browse Frame• WAIT-FOR Event for Frame-based Procedure• Informs PARENT Window that CHILD Drop-Down Browse is Closed

– Handles “Multiple Persistent Window Architecture”– Cannot Close PARENT Window when Drop-Down is Open

/** Exit and Hide Frame **/WAIT-FOR CLOSE OF THIS-PROCEDURE FOCUS browseDropDown.

IF inWindowHndl:TYPE = "WINDOW":U THENASSIGN inWindowHndl:PRIVATE-DATA = "".


Drop-Down Button-List (Browse)External Procedure – Customizable Sections:Input Parameter(s)• REPOSITION to Value for QUERY• Additional Parameters for OPEN QUERY construction

Output Parameter(s)• Result Value (e.g. ROWID for Customer Table)• Additional Parameters if required by main Window

Query/Widget Definitions• FIELD-LISTS for performance• Example: “Static” Browse and Query for simplicity • Use “dynamic” Browse and Query Total “parameterization”


Drop-Down Button-List (Browse)External Procedure – Customizable Sections:DOUBLE-CLICK or DEFAULT-ACTION• SELECTED Row ASSIGN Result Value Valid Result = YES

• LEAVE Browse Frame CLOSE Procedure

/** Reposition will allow Scrolling Up and Down on Browse from Highlighted Row **/FIND FIRST Customer WHERE

Customer.Name >= inFillInValue NO-LOCK NO-ERROR.

ASSIGN localRowID = IF AVAILABLE Customer THENROWID(Customer)

ELSE?.

OPEN QUERY queryDropDown FOR EACH Customer NO-LOCK USE-INDEX Name INDEXED-REPOSITION.

IF localRowID <> ? THENREPOSITION queryDropDown TO ROWID localRowID.

OPEN and REPOSITION Query


Updateable Browse EnhancementsOverview:

Updateable Cell – Drop-Down Button-List (Browse)• “Data Aware” Drop-Down List• Select value(s) for Editable Cell (Row)

Conversion of Updateable to Non-Updateable Cell• Dynamic• Some Cells (Rows) in Column are editable• Does not convert entire COLUMN to Non-Updateable


Updateable Browse EnhancementsUpdateable Cell – Drop-Down Button-List (Browse):

** DEMO **

Focus in the Updateable Browse –Customer Name Cell

Drop-Down List (Browse) overlaying Updateable Browse



Components• Updateable Browse widget• Example: Free-Form Query• Drop-Down Button-List (Browse)

– Fill-In Widget Editable Cell• Down-Arrow Button

– Placement – Visibility



Down Arrow Button – Placement and Visibility• Uses X,Y, WIDGET-HANDLE of Editable Cell

• Localized in Internal Procedure– Example: ButtonCustomerNamePlacementProc

• Execute Internal Procedure from two Events – SCROLL-NOTIFY of Updateable Browse– ENTRY of Editable Cell

• FOCUS in Editable Cell Button HIDDEN = NO• FOCUS in any other Widget Button HIDDEN = YES



DO WITH FRAME {&FRAME-NAME}:/** Assign Widget Handle of the TempCustomerList.CustomerName Cell with Focus **/ASSIGN hndlCellCustomerName = TempCustomerList.CustomerName:HANDLE IN BROWSE

browseCustomerList.

/** If TempCustomerList.CustomerName Cell is horizontally not visible in the Browse Widget, then hide the Button, else set the Column position. **/

IF hndlCellCustomerName:X < 0 THEN ASSIGN buttonCustomerName:HIDDEN = YES.

ELSE ASSIGN buttonCustomerName:X = hndlCellCustomerName:X

+ browseCustomerList:X + hndlCellCustomerName:WIDTH-PIXELS- buttonCustomerName:WIDTH-PIXELS+ 3 /* Separator Pixels */.

/** If TempCustomerList.CustomerName Cell is vertically not visible in the Browse Widget, then hide the Button, else set the Row position. **/

IF hndlCellCustomerName:Y < 0 THEN ASSIGN buttonCustomerName:HIDDEN = YES.

ELSE ASSIGN buttonCustomerName:Y = hndlCellCustomerName:Y

+ browseCustomerList:Y.

/** If TempCustomerList.CustomerName Cell with Focus is visible in the Browse Widget then display and enable the Button. **/

IF AVAILABLE TempCustomerList THENDO:

IF hndlCellCustomerName:X >= 0 ANDhndlCellCustomerName:Y >= 0 THEN ASSIGN buttonCustomerName:HIDDEN = NO

buttonCustomerName:SENSITIVE = YES.END.

END.

ButtonCustomerNamePlacementProc


Updateable Browse EnhancementsDynamic Conversion of Updateable Cell to Non-Updateable Cell:

Functionality/Need• Entire editable Column, non-editable: READ-ONLY = YES

• Business Rules based• Examples:

– Price Items Matrix– User Security-based Field/Cell Level data entry

• Some cells (Rows) in Column are editable• Other cells in same Column are non-editable



• City Column• Ranks 1 – 5 are editable cells• Ranks 6 – 10 are non-editable cells• Editable cells: Blue/White• Non-Editable cells: Black/Light Grey

Example screen

** DEMO **



ROW-DISPLAY• Manage Color combination for Editable/Non-Editable cells• Consistent “Look and Feel”

– Non-editable Columns– Non-editable cells in editable Column

IF TempCustomerList.Rank > 5 THENASSIGN TempCustomerList.City:FGCOLOR IN BROWSE browseCustomerList = 0

TempCustomerList.City:BGCOLOR IN BROWSE browseCustomerList = 8.



VALUE-CHANGED• “Action” Event• Manage cell’s READ-ONLY (editable) attribute• Appropriate Updateable cell Non-Updateable • Does not convert entire COLUMN to Non-Updateable

IF TempCustomerList.Rank > 5 THENASSIGN TempCustomerList.City:READ-ONLY IN BROWSE browseCustomerList = YES.

ELSEASSIGN TempCustomerList.City:READ-ONLY IN BROWSE browseCustomerList = NO.


Extras…Tips & TricksOverview:

• Using Temp-Table Managers

• Working with Array Columns

• Positioning Multi-Select Browses


Extras…Tips & TricksDemo of Sales Analysis System:


** DEMO **

SORT COLUMNARRAY ELEMENTS

SELECTED COLUMN

Extras…Tips & TricksUsing Temp-Table Managers:

• Temp-Table to Manage Column Handles• Load Handles ONCE only!• Dynamic Access/Modify Cell (Column) Attributes:

LABEL, FGCOLOR, VISIBLE, etc.• Avoid Compiler Errors and Limitations – Arrays

DEFINE TEMP-TABLE tempBrowseColumns NO-UNDOFIELD BrowseName AS CHARACTER FIELD ColumnHandle AS WIDGET-HANDLE EXTENT 51 /* NUM-COLUMNS */INDEX BrowseName IS PRIMARY UNIQUE BrowseName ASC.

/* WRONG – WILL NOT COMPILE */ASSIGN CustomerSales.SalesMonth[i]:BGCOLOR IN BROWSE browseMain = 12.

/* CORRECT – WILL COMPILE *//* We have assigned the Handles of each Column to the Array Elements in

tempBrowseColumns.ColumnHandle Field */ ASSIGN tempBrowseColumns.ColumnHandle[i]:BGCOLOR = 12.


Extras…Tips & TricksWorking with Array Columns:

• CURRENT-COLUMN:NAME is always the “same”• How to differentiate which Array Element Column is

Selected?• CURRENT-COLUMN:TYPE is “FILL-IN” always!• Use CURRENT-COLUMN:INDEX (1…No. of Elements)• Now you can SORT or Manipulate Cells & Column

Headers for selected ColumnON START-SEARCH of browseMain DO ...

/* Validate Selected Column Handle, determine it is SalesMonth Array Field, and send Array Element Number to Sort Procedure */

IF VALID-HANDLE(browseMain:CURRENT-COLUMN) ANDbrowseMain:CURRENT-COLUMN:NAME = “SalesMonth” THEN

RUN SortColumnProc(INPUT browseMain:CURRENT-COLUMN:INDEX)...


Extras…Tips & TricksPositioning Multi-Select Browses:

• Multiple Selected Rows Multiple Bands of Blue• Position to a single Row One Blue Row. How?• Simple SET-REPOSITIONED-ROW will NOT work!

– Reposition OK– Will NOT Highlight One Blue Row (ONLY “- - -” Band)

/* Remove Bands of Blue from Multiple Selected Rows */IF browseMain:NUM-SELECTED-ROWS > 0 THEN

browseMain:DESELECT-ROWS().

/* Position Browser Query to desired Row */REPOSITION browseMain TO ROWID localRowid.

/* Visualize desired Row on Browse – put a “---” Band around the Row */browseMain:SET-REPOSITIONED-ROW(INTEGER(browseMain:HEIGHT-CHARS / 2),”CONDITIONAL”:U)

/* Highlight desired Row – One Blue Row */browseMain:SELECT-FOCUSED-ROW().


Questions?Additional Information and Downloads…

ProcessWare™ FrameworkStepUp Accounting™

“You do not have to Reinvent the Accounting Wheel”

“The ONLY Progress based G/L, A/R, A/P made just for ISV's and Consultants”

www.innov8cs.com


exploiting the gui - extending the browse widget

Documents