PowerBuilder Foundation Class

Library Object Reference

Volume 1

PowerBuilder
8
DOCUMENT ID: 37785-01-0800-01

LAST REVISED: June 2001

Copyright © 1989-2001 by Sybase, Inc. All rights reserved.

This publication pertains to Sybase database management software and to any subsequent release until otherwise indicated in new
editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished
under a license agreement, and it may be used or copied only in accordance with the terms of that agreement.

To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 229-9845.

Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other
international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled
software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic,
mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc.

Sybase, the Sybase logo, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server,
Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replication,
Adaptive Server Everywhere, Adaptive Server IQ, Adaptive Warehouse, AnswerBase, Anywhere Studio, Application Manager,
AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-FORMS, APT-Translator, APT-Library, Backup Server,
ClearConnect, Client-Library, Client Services, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress,
DataServer, DataWindow, DB-Library, dbQueue, Developers Workbench, Direct Connect Anywhere, DirectConnect, Distribution
Director, E-Anywhere, E-Whatever, Embedded SQL, EMS, Enterprise Application Studio, Enterprise Client/Server, Enterprise Connect,
Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work Designer,
Enterprise Work Modeler, EWA, Financial Fusion, Financial Fusion Server, Gateway Manager, ImpactNow, InfoMaker, Information
Anywhere, Information Everywhere, InformationConnect, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBase,
MainframeConnect, Maintenance Express, MAP, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, MySupport,
Net-Gateway, Net-Library, ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Client,
Open ClientConnect, Open Client/Server, Open Client/Server Interfaces, Open Gateway, Open Server, Open ServerConnect, Open
Solutions, Optima++, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library, Power++, power.stop, PowerAMC, PowerBuilder,
PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerJ, PowerScript, PowerSite,
PowerSocket, Powersoft, PowerStage, PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowerWare Desktop,
PowerWare Enterprise, ProcessAnalyst, Report Workbench, Report-Execute, Replication Agent, Replication Driver, Replication Server,
Replication Server Manager, Replication Toolkit, Resource Manager, RW-DisplayLib, RW-Library, S-Designor, SDF, Secure SQL
Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script, SQL Advantage, SQL Anywhere, SQL
Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere, SQL Modeler, SQL Remote, SQL
Server, SQL Server Manager, SQL SMART, SQL Toolset, SQL Server/CFT, SQL Server/DBM, SQL Server SNMP SubAgent, SQL
Station, SQLJ, STEP, SupportNow, Sybase Central, Sybase Client/Server Interfaces, Sybase Financial Server, Sybase Gateways, Sybase
MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User Workbench, SybaseWare, Syber Financial,
SyberAssist, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, Transact-SQL, Translation Toolkit,
UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viewer, Visual Components, VisualSpeller, VisualWriter,
VQL, WarehouseArchitect, Warehouse Control Center, Warehouse Studio, Warehouse WORKS, Watcom, Watcom SQL, Watcom SQL
Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server and XP
Server are trademarks of Sybase, Inc. 3/01

Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.

All other company and product names used herein may be trademarks or registered trademarks of their respective companies.

Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-
7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.

Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608.

Contents

About This Book ........................................................................................................................... ix

VOLUME 1

C H APTE R 1 Object Reference Conventions...................................................... 1

Naming conventions......................................................................... 2
Online Help ...................................................................................... 7
Sample application and code examples........................................... 8

C H APTE R 2 Window Objects .............................................................................. 9

w_child ........................................................................................... 10
w_frame ......................................................................................... 11
w_main ........................................................................................... 17
w_master........................................................................................ 18
w_popup......................................................................................... 52
w_response .................................................................................... 53
w_sheet .......................................................................................... 56

C H APTE R 3 Menus............................................................................................. 59
m_dw.............................................................................................. 60
m_edit ............................................................................................ 62
m_frame ......................................................................................... 64
m_lvs .............................................................................................. 65
m_master ....................................................................................... 68
m_oc .............................................................................................. 73
m_tvs.............................................................................................. 75

C H APTE R 4 Global Functions........................................................................... 77

f_SetFilesrv .................................................................................... 78
f_SetPlatform ................................................................................. 79

iii
Contents

CH APT ER 5 Global Structures and Structure Objects .................................... 81

n_cst_aboutattrib............................................................................ 82
n_cst_baseattrib ............................................................................. 83
n_cst_calculatorattrib ..................................................................... 84
n_cst_calendarattrib ....................................................................... 85
n_cst_columnattrib ......................................................................... 86
n_cst_dberrorattrib ......................................................................... 87
n_cst_dirattrib................................................................................. 88
n_cst_dssrv_multitableattrib........................................................... 89
n_cst_dwcacheattrib ...................................................................... 90
n_cst_dwobjectattrib ...................................................................... 91
n_cst_dwpropertyattrib ................................................................... 92
n_cst_dwsrv_dropdownsearchattrib............................................... 93
n_cst_dwsrv_multitableattrib .......................................................... 94
n_cst_dwsrv_querymodeattrib ....................................................... 95
n_cst_dwsrv_resizeattrib................................................................ 96
n_cst_errorattrib ............................................................................. 97
n_cst_filterattrib .............................................................................. 98
n_cst_findattrib............................................................................... 99
n_cst_infoattrib............................................................................. 100
n_cst_itemattrib ............................................................................ 101
n_cst_linkageattrib ....................................................................... 102
n_cst_logonattrib .......................................................................... 103
n_cst_lvsrvattrib ........................................................................... 104
n_cst_mruattrib ............................................................................ 105
n_cst_propertyattrib ..................................................................... 106
n_cst_resizeattrib ......................................................................... 107
n_cst_restorerowattrib.................................................................. 108
n_cst_returnattrib ......................................................................... 109
n_cst_selectionattrib .................................................................... 110
n_cst_sortattrib............................................................................. 111
n_cst_splashattrib ........................................................................ 112
n_cst_sqlattrib .............................................................................. 113
n_cst_textstyleattrib ..................................................................... 114
n_cst_tmgregisterattrib................................................................. 115
n_cst_toolbarattrib........................................................................ 116
n_cst_trregistration....................................................................... 117
n_cst_tvattrib................................................................................ 118
n_cst_tvsrvattrib ........................................................................... 119
n_cst_winsrv_sheetmanagerattrib ............................................... 120
n_cst_winsrv_statusbarattrib........................................................ 121
n_cst_zoomattrib .......................................................................... 122
s_pagesetupattrib......................................................................... 123
s_paperattrib ................................................................................ 124

iv
 Contents

s_printdlgattrib.............................................................................. 125
s_svalue ....................................................................................... 126

C HA PTER 6 Standard Visual User Objects.................................................... 127

u_cb ............................................................................................. 128
u_cbx............................................................................................ 131
u_ddlb .......................................................................................... 134
u_ddplb ........................................................................................ 141
u_dw............................................................................................. 148
u_em ............................................................................................ 195
u_gb ............................................................................................. 203
u_gr .............................................................................................. 204
u_hpb ........................................................................................... 207
u_hsb ........................................................................................... 210
u_htb ............................................................................................ 213
u_lb .............................................................................................. 216
u_lvs............................................................................................. 220
u_mle ........................................................................................... 253
u_oc ............................................................................................. 259
u_p ............................................................................................... 267
u_pb ............................................................................................. 270
u_phl ............................................................................................ 273
u_plb ............................................................................................ 276
u_rb .............................................................................................. 280
u_rte ............................................................................................. 283
u_sle............................................................................................. 307
u_st .............................................................................................. 313
u_sth ............................................................................................ 316
u_tab ............................................................................................ 319
u_tvs............................................................................................. 334
u_vpb ........................................................................................... 369
u_vsb............................................................................................ 372
u_vtb ............................................................................................ 375

C HA PTER 7 Custom Visual User Objects...................................................... 379

u_base ......................................................................................... 380
u_calculator.................................................................................. 396
u_calendar ................................................................................... 419
u_progressbar .............................................................................. 457
u_st_splitbar................................................................................. 483
u_tabpg ........................................................................................ 497

v
Contents

CH APT ER 8 Standard Class User Objects ..................................................... 499

n_cn ............................................................................................. 500
n_cxinfo........................................................................................ 504
n_cxk............................................................................................ 505
n_dda ........................................................................................... 506
n_ds ............................................................................................. 507
n_dsa ........................................................................................... 529
n_err............................................................................................. 530
n_inet ........................................................................................... 532
n_ir ............................................................................................... 533
n_ms ............................................................................................ 534
n_msg .......................................................................................... 536
n_oo ............................................................................................. 542
n_ostg .......................................................................................... 543
n_ostm ......................................................................................... 544
n_pl .............................................................................................. 545
n_srv ............................................................................................ 547
n_tmg ........................................................................................... 548
n_tr ............................................................................................... 550
n_trp ............................................................................................. 566

VOLUME 2

CH APT ER 9 Custom Class User Objects........................................................ 569

n_base ......................................................................................... 570
n_cst_appmanager ...................................................................... 572
n_cst_apppreference ................................................................... 601
n_cst_color................................................................................... 619
n_cst_conversion ......................................................................... 621
n_cst_datetime............................................................................. 633
n_cst_debug................................................................................. 651
n_cst_dropdown ........................................................................... 658
n_cst_dssrv .................................................................................. 664
n_cst_dssrv_multitable................................................................. 665
n_cst_dssrv_printpreview............................................................. 666
n_cst_dssrv_report....................................................................... 667
n_cst_dwcache ............................................................................ 668
n_cst_dwsrv ................................................................................. 682
n_cst_dwsrv_dropdownsearch..................................................... 706
n_cst_dwsrv_filter ........................................................................ 717
n_cst_dwsrv_find ......................................................................... 728
n_cst_dwsrv_linkage .................................................................... 744
n_cst_dwsrv_multitable ................................................................ 806

vi
 Contents

n_cst_dwsrv_printpreview ............................................................ 817

n_cst_dwsrv_property .................................................................. 826
n_cst_dwsrv_querymode ............................................................. 830
n_cst_dwsrv_report ...................................................................... 841
n_cst_dwsrv_reqcolumn .............................................................. 884
n_cst_dwsrv_resize...................................................................... 891
n_cst_dwsrv_rowmanager ........................................................... 908
n_cst_dwsrv_rowselection ........................................................... 918
n_cst_dwsrv_sort ......................................................................... 934
n_cst_error ................................................................................... 950
n_cst_filesrv ................................................................................. 978
n_cst_filesrvwin32...................................................................... 1004
n_cst_inifile ................................................................................ 1025
n_cst_linkedlistbase ................................................................... 1030
n_cst_linkedlistnode................................................................... 1038
n_cst_linkedlistnodecompare ..................................................... 1039
n_cst_list .................................................................................... 1042
n_cst_luw ................................................................................... 1051
n_cst_lvsrv ................................................................................. 1067
n_cst_lvsrv_datasource ............................................................. 1073
n_cst_lvsrv_sort ......................................................................... 1114
n_cst_menu................................................................................ 1120
n_cst_metaclass ........................................................................ 1126
n_cst_mru .................................................................................. 1133
n_cst_nodebase......................................................................... 1155
n_cst_nodecomparebase ........................................................... 1161
n_cst_numerical ......................................................................... 1164
n_cst_platform............................................................................ 1170
n_cst_platformwin32 .................................................................. 1178
n_cst_queue............................................................................... 1187
n_cst_resize ............................................................................... 1190
n_cst_rtefind............................................................................... 1200
n_cst_security ............................................................................ 1206
n_cst_selection .......................................................................... 1210
n_cst_sql .................................................................................... 1215
n_cst_sqlspy .............................................................................. 1218
n_cst_stack ................................................................................ 1224
n_cst_string................................................................................ 1227
n_cst_tmgmultiple ...................................................................... 1247
n_cst_tmgsingle ......................................................................... 1257
n_cst_tree .................................................................................. 1266
n_cst_treenode .......................................................................... 1279
n_cst_treenodecompare ............................................................ 1283
n_cst_trregistration..................................................................... 1285

vii
Contents

n_cst_tvsrv ................................................................................. 1294

n_cst_tvsrv_levelsource ............................................................. 1303
n_cst_tvsrv_print ........................................................................ 1358
n_cst_winsrv .............................................................................. 1362
n_cst_winsrv_preference ........................................................... 1365
n_cst_winsrv_sheetmanager ..................................................... 1382
n_cst_winsrv_statusbar.............................................................. 1389

viii
About This Book

Subject This book describes the objects in the PowerBuilder Foundation Class
Library (PFC). Each object’s discussion includes:
• A diagram providing a quick overview of the object’s capabilities
• Instance variables
• Events and user events
• Object functions

Online Help
The PFC online Help (pbpfc80.hlp) contains all the objects, events, and
functions explained in this book. This Help file includes customized
buttons and links to help you navigate through inheritance hierarchies and
related objects.

For PFC usage information, see the PowerBuilder Foundation Class

Library User’s Guide.
Audience This book is for experienced PowerBuilder developers. It assumes that:
• You are currently developing applications using PowerBuilder and
understand the concepts and techniques described in the
PowerBuilder Application Techniques book
• You understand SQL and how to use your site-specific DBMS
Two volumes The printed version of this book is divided into two volumes:
Volume 1 includes Chapters 1-8.
Volume 2 includes Chapter 9.

ix
About This Book

x
CH A PTE R 1 Object Reference Conventions

About this chapter This chapter describes the conventions used in this book and the PFC
online Help file.
Contents
Topic Page
Naming conventions 2
Online Help 7
Sample application and code examples 8

1
Naming conventions

Naming conventions
Object naming PFC uses the following prefix standard for object names:
conventions
pfcobject_type_objectname
where:
• pfcobject indicates whether the object is part of the PFC level or the
extension level. Objects that are part of the PFC level have the prefix PFC_
• type indicates the object type
This table describes the object types.
Prefix Description
m_ Menu
n_ Standard class user object
n_cst Custom class user object
s_ Global structure
u_ Visual user object
w_ Window

For example:
• Pfc_w_master is the master window and is in the PFC level
• Pfc_u_tvs is the TreeView visual user object and is in the PFC level
• U_dw is the DataWindow visual user object and is in the extension level
• N_cst_dwsrv is the custom class user object for DataWindow services and
is in the extension level
• N_tr is the transaction standard class user object and is in the extension
level
Variable naming PFC uses the following standard for variable names:
conventions
<scope><datatype>_variablename
Scope is one of the following:
Prefix Description
a Argument to an event or function
g Global variable
i Instance variable
l Local variable

2
 Chapter 1 Object Reference Conventions

Prefix Description
s Shared variable

For standard data types, datatype is one of the following:

Prefix Description
a Any
blb Blob
b Boolean
ch Character
d Date
dtm DateTime
dc Decimal
dbl Double
e Enumerated
i Integer
l Long
r Real
s String
tm Time
ui UnsignedInteger
ul UnsignedLong

For reference variables, datatype is one of the following:

Prefix Description
app Application
ab ArrayBounds
cbx CheckBox
cb CommandButton
cd ClassDefinition
cdo ClassDefinitionObject
cn Connection
cninfo ConnectionInfo
cno ConnectObject
cxk ContextKeyword
cxinfo ContextInformation
cpp cplusplus
ds DataStore

3
Naming conventions

Prefix Description
dw DataWindow
dwc DataWindowChild
drg DragObject
drw DrawObject
ddplb DropDownPictureListBox
ddlb DropDownListBox
dwo DWobject
dda DynamicDescriptionArea
dsa DynamicStagingArea
ed EnumerationDefinition
eid EnumerationItemDefinition
em EditMask
env Environment
err Error
ext ExtObject
gr Graph
go GraphicObject
grax GrAxis
grda GrDispAttr
gb GroupBox
hsb HorizontalScrollBar
inet Inet
ir InternetResult
ln Line
lb ListBox
lv ListView
lvi ListViewItem
mfd MailFileDescription
mm MailMessage
mr MailRecipient
ms MailSession
mdi MDIClient
m Menu
mc MenuCascade
msg Message
mle MultiLineEdit
nv NonVisualObject

4
 Chapter 1 Object Reference Conventions

Prefix Description
oc OleControl
oo OleObject
ostg OleStorage
omc OmControl
omcc OmCustomControl
omec OmEmbeddedControl
omo OmObject
omstm OmStream
omstg OmStorage
oval Oval
p Picture
pb PictureButton
pbcpp PBToCPPObject
plb PictureListBox
pl Pipeline
po PowerObject
procall ProfileCall
proclass ProfileClass
proln ProfileLine
prort ProfileRoutine
pro Profiling
rb RadioButton
rec Rectangle
rem RemoteObject
rte RichTextEdit
rrec RoundRectangle
rteo RteObject
scrd ScriptDefinition
sle SingleLineEdit
srv Service
st StaticText
std SimpleTypeDefinition
str Structure
tab Tab
tabpg TabPage
tcan TraceActivityNode
tcbe TraceBeginEnd

5
Naming conventions

Prefix Description
tcerr TraceError
tcf TraceFile
tcln TraceLine
tcgc TraceGarbageCollect
tco TraceObject
tcrt TraceRoutine
tcsql TraceSQL
tct TraceTree
tctn TraceTreeNode
tcterr TraceTreeError
tctsql TraceTreeSQL
tctgc TraceTreeGarbageCollect
tctln TraceTreeLine
tcto TraceTreeObject
tctrt TraceTreeRoutine
tctu TraceTreeUser
tcu TraceUser
td TypeDefinition
tr Transaction
trp Transport
tv TreeView
tvi TreeViewItem
uo UserObject
vrcd VariableCardinalityDefinition
vrd VariableDefinition
vsb VerticalScrollBar
wo WindowObject
w Window

Function naming Global functions use the f_ prefix and object functions use the of_ prefix.
conventions

6
 Chapter 1 Object Reference Conventions

Online Help
Accessing Help The PFC online Help file contains all information found in this manual, as well
as hypertext links among related topics. There are many ways to access this
file:
• From the PowerBuilder Help Contents tab The PowerBuilder Help
screen includes a jump to PFC Help.
• Double-click the filename (pbpfc80.hlp) from the Explorer or File
Manager This displays the Contents tab, which you can use to view lists
of objects.
• Using SHIFT+F1 from the Script view This displays Help for the
selected object function or event.
Navigating through The PFC Help file provides many helpful links among objects, functions, and
the Help file events:
• From an object You can display a dialog box with jumps to instance
variables, events, and functions. You can also:
• Click the See Also button to jump to related objects
• Click the Descendants button to display a list of descendants, if any
• Click the Ancestor button to jump to the ancestor object
• From an event or function You can display a code example, if
appropriate, for the event or function. You can also:
• Click the See Also button to jump to related objects
• Click the Object button to jump to the parent object

7
Sample application and code examples

Sample application and code examples

Sample application The PEAT sample application shows you how to use PFC for a simple project
estimation and tracking system. It includes examples of windows,
DataWindows, tabs, TreeViews, ListViews, and custom class user objects.
By default, the PEAT application is installed in the PFC\DemoApp directory.
Code examples The APPEXAMP code examples application shows you how to use selected
PFC objects and services. Its includes examples of application services,
windows, window services, DataWindows, DataWindow services, tabs,
TreeViews, ListViews, and custom class user objects.
By default, the code examples are installed in the PFC\Examples directory.

8
CH A PTE R 2 Window Objects

About this chapter This chapter describes the base-class windows in the PowerBuilder
Foundation Class Library (PFC). Each discussion includes information on
usage, instance variables, events, and functions.
Contents The windows are listed in alphabetical order. The information for each
window includes an alphabetical listing of instance variables, events, and
object functions.

9
w_child

w_child
Description Ancestor for all PFC child windows.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this window as the ancestor for all of your application’s child windows.
See also w_master

10
 Chapter 2 Window Objects

w_frame
Description Ancestor frame window for all MDI applications.
It includes MicroHelp automatically. To create a frame window without
MicroHelp, either modify or rename your application’s frame window.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships m_frame
n_cst_toolbarattrib
w_statusbar
w_toolbars
Usage Use this window or a descendant as the frame window for all MDI applications
that use PFC.
See also m_frame
w_master
w_statusbar
w_toolbars

11
w_frame

Instance variables
W_frame includes instance variables:
Instance
variable Description Data type Access Usage
inv_sheetmanager Reference variable for n_cst_winsrv_sheetmanager Public Set with
sheet management of_SetSheetManager
service
inv_statusbar Reference variable for n_cst_winsrv_statusbar Public Set with
status bar service of_SetStatusBar

Events
W_frame includes precoded events:
Activate pfc_PostOpen
Close pfc_PreToolbar
Hide pfc_TileHorizontal
Move pfc_TileVertical
pfc_Cascade pfc_Toolbars
pfc_Layer pfc_UndoArrange
pfc_MicroHelp Resize
pfc_MinimizeAll Show

Activate
Description Calls the n_cst_appmanager of_SetFrame function to establish this window as
the active frame.
This event extends the ancestor Activate event.
Usage This event executes when the window becomes active.

Close
Description Destroys any instantiated services.
Usage This event executes when the window closes.

12
 Chapter 2 Window Objects

Hide
Description Calls the n_cst_winsrv_statusbar pfc_Hide event.
Usage This event executes when the window is hidden.

Move
Description Positions the status bar when the user moves the window.
This event extends the ancestor Move event.
Usage This event executes when the user moves the frame window.

pfc_Cascade
Description Calls the n_cst_winsrv_sheetmanager pfc_Cascade event.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event executes when the user selects Window>Cascade from the menu bar
of a menu descended from the PFC m_master menu.

pfc_Layer
Description Calls the n_cst_winsrv_sheetmanager pfc_Layer event.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event executes when the user selects Window>Layer from the menu bar
of a menu descended from the PFC m_master menu.

pfc_MicroHelp
Description Displays the passed string in the status bar.
This event extends the w_master pfc_MicroHelp event.
Syntax instancename.EVENT pfc_MicroHelp ( microhelp )
Argument Description
instancename Instance name of w_frame
microhelp String to be displayed in the status bar

Return value None

Usage This event is called by u_dw ItemFocusChanged event. It is also extended in
w_sheet.

13
w_frame

pfc_MinimizeAll
Description Minimizes all open sheets.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event executes when the user selects Window>Minimize All from the
menu bar of a menu descended from the PFC m_master menu.

pfc_PostOpen
Description Opens the w_statusbar window if this capability has been requested through
the of_SetStatusBar function.
This event extends the w_master pfc_PostOpen event.
Usage This event executes after the window opens.

pfc_PreToolbar
Description Populates toolbar attributes.
Syntax instancename.EVENT pfc_PreToolbar ( attributes )
Argument Description
instancename Instance name of w_frame
attributes N_cst_toolbarattrib variable into which the event places toolbar
attributes (passed by reference)

Usage The pfc_Toolbars event calls this event before displaying the w_toolbars
dialog box.

pfc_TileHorizontal
Description Tiles sheets horizontally.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event executes when the user selects Window >Tile Horizontal from the
menu bar of a menu descended from the PFC m_master menu.

pfc_TileVertical
Description Tiles open sheets vertically.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.

14
 Chapter 2 Window Objects

Usage This event executes when the user selects Window>Tile Vertical from the
menu bar of a menu descended from the PFC m_master menu.

pfc_Toolbars
Description Displays the w_toolbars dialog box.
Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the
w_toolbars dialog box, and -1 if an error occurs.
Usage This event executes when the user selects View>Toolbars from the menu bar
of a menu that descends from the PFC m_master menu.

pfc_UndoArrange
Description Calls the n_cst_winsrv_sheetmanager pfc_UndoArrange event.
Return value Integer. Returns the number of sheets undone if the event succeeds and -1 if an
error occurs.
Usage This event executes when the user selects Window>Undo Arrange from the
menu bar of a menu descended from the PFC m_master menu.

Resize
Description Positions the status bar when the user resizes the window.
Usage This event executes when the user resizes the frame window.

Show
Description Calls the n_cst_winsrv_statusbar pfc_Show event.
Usage This event executes when the window displays after being hidden.

Functions
W_frame includes precoded object functions:
of_SetSheetManager
of_SetStatusBar

15
w_frame

of_SetSheetManager
Description Creates or destroys an instance of n_cst_winsrv_sheetmanager, which provides
sheet management services.
Access Public
Syntax windowname.of_SetSheetManager ( boolean )
Argument Description
windowname Instance name of w_frame
boolean Boolean specifying whether to create (TRUE) or destroy (FALSE)
an instance of the n_cst_winsrv_sheetmanager object

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetSheetManager function:
of_SetSheetManager(TRUE)
of_SetStatusBar(TRUE)

of_SetStatusBar
Description Creates or destroys an instance of n_cst_winsrv_statusbar, which provides
status bar services and opens the w_statusbar at the bottom of the frame.
Access Public
Syntax windowname.of_SetStatusBar ( boolean )
Argument Description
windowname Instance name of w_frame
boolean Boolean specifying whether to create (TRUE) or destroy (FALSE)
an instance of the n_cst_winsrv_statusbar object

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetStatusBar function:
of_SetStatusBar (TRUE)

16
 Chapter 2 Window Objects

w_main
Description Ancestor main window for all SDI applications.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use w_main as the ancestor window for all single document interface (SDI)
applications.
See also w_master

17
w_master

w_master
Description W_master is the ancestor for all PFC windows. It includes instance variables,
events, and functions that are accessed by many PFC objects.
W_master is a self-updating object.
Ancestry

Library PFCWNSRV.PBL
PFEWNSRV.PBL
Object relationships n_cst_appmanager
n_cst_dberrorattrib
n_cst_dwsrv_linkage
n_cst_luw
n_cst_winsrv
n_cst_winsrv_preference
n_cst_resize
u_dw
Usage When writing a PFC-based application, all windows must descend from
w_master.
W_master is the ancestor of all PFC windows. When you add instance
variables, events, and functions to w_master, they are immediately available in
all PFC windows.
Descendants w_child
w_frame
w_main
w_popup

18
 Chapter 2 Window Objects

w_response
w_sheet
See also n_cst_appmanager
n_cst_winsrv
n_cst_winsrv_preference
n_cst_resize

Instance variables
W_master includes instance variables:
Instance variable Description Data type Access Usage
CONTINUE_ACTION Constant set to 1 Integer Public Internal
FAILURE Constant set to -1 Integer Public Internal
ia_helptypeid Controls whether PFC calls Any Protected Set programmatically
the ShowHelp function by
topic, keyword, or index
ib_alwaysvalidate Controls whether the save Boolean Protected Set with
process includes all objects of_SetAlwaysValidate
in the validation process (default is FALSE)
ib_closestatus Indicates whether the Boolean Protected Internal
window is closing
ib_disableclosequery Indicates whether Boolean Protected Internal
CloseQuery processing is
enabled
ib_isupdateable Indicates whether the Boolean Protected Set with
window can be updated of_SetUpdateable
(default is TRUE)
ib_savestatus Controls whether message Boolean Protected Internal
display during the save
process
idw_active Current DataWindow U_dw Protected Internal
inv_base Reference variable for basic n_cst_winsrv Public Set with of_SetBase
window services
inv_dberrorattrib Contains database error n_cst_ Protected Set with
information dberrorattrib of_SetDBErrorMsg
inv_luw Reference variable for n_cst_luw Protected Set with of_
logical unit of work service SetLogicalUnitOfWork
inv_preference Reference variable for n_cst_winsrv_ Public Set with
window preference service preference of_SetPreference

19
w_master

Instance variable Description Data type Access Usage

inv_resize Reference variable for resize n_cst_resize Public Set with of_SetResize
service
ipo_pendingupdates[ ] Default list of objects to be PowerObject Protected Internal
updated
ipo_updateobjects[ ] Customized list of objects to PowerObject Protected Internal
be updated
ipo_ One-time list of objects to be PowerObject Protected Internal
tempupdateobjects[ ] updated
ipo_updaterequestor Owner of the save process PowerObject Protected Internal
NO_ACTION Constant set to 0 Integer Public Internal
PREVENT_ACTION Constant set to 0 Integer Public Internal
SUCCESS Constant set to 1 Integer Public Internal

Events
W_master includes precoded events:
Activate pfc_Open
Close pfc_PageSetup
CloseQuery pfc_PostOpen
Move pfc_PostUpdate
Open pfc_PreClose
pfc_AcceptText pfc_PreMRUSave
pfc_BeginTran pfc_PreOpen
pfc_Close pfc_PreUpdate
pfc_ControlGotFocus pfc_Print
pfc_DBError pfc_PrintImmediate
pfc_Descendant pfc_Save
pfc_EndTran pfc_SaveAs
pfc_Help pfc_SaveObjects
pfc_MessageRouter pfc_Update
pfc_MicroHelp pfc_UpdateObjects
pfc_MRUClicked pfc_UpdatePrep
pfc_MRUProcess pfc_UpdatesPending
pfc_MRURestore pfc_UpdatesPendingRef
pfc_MRUSave pfc_Validation
pfc_New Resize

20
 Chapter 2 Window Objects

Activate
Description Calls the n_cst_mru pfc_MRURestore event to restore changed menu items as
needed.
Usage This event executes when the window becomes active.

Close
Description Stores preference information and destroys any existing window service
objects.
Usage This event executes when a window closes.

CloseQuery
Description Accesses all DataWindows, checks for validation errors and, if changes are
pending, prompts the user to save the changes.
Usage This event executes when a window closes, just before the Close event. It calls
one or more of the following:
• Pfc_PreClose
• Of_UpdateChecks
• Pfc_Save

Move
Description Stores the window position and size.
Usage This event executes when the user moves a window.

Open
Description Triggers the pfc_PreOpen event and posts the pfc_PostOpen event. If the
preference and MRU services are enabled, this event also restores window
settings and MRU information.
Usage This event executes when the window opens. It's best to add application-
specific code to either the pfc_PreOpen or pfc_PostOpen events.

21
w_master

pfc_AcceptText
Description Calls the n_cst_luw of_AcceptText function, which in turn calls the
of_AcceptText function for all controls that implement it.
Syntax instancename.EVENT pfc_AcceptText ( controlarray, focusonerror )
Argument Description
instancename Instance name of the w_master-based descendant
controlarray PowerObject array containing the controls for which to accept text.
From within the pfc_AcceptText event, access this value through
the apo_control argument
focusonerror Boolean specifying whether to set focus on a DataWindow column
with errors. From within the pfc_AcceptText event, access this
value through the ab_focusonerror argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the of_UpdateChecks function.

pfc_BeginTran
Description Empty user event that you extend to perform start-of-transaction processing.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the pfc_Save event.

pfc_Close
Description Closes the window.
Usage Call this event to close a window.

pfc_ControlGotFocus
Description Triggered when a PFC visual control gets focus. This event keeps track of the
current control.
Syntax instancename.EVENT pfc_ControlGotFocus ( control )
Argument Description
instancename Instance name of the w_master-based descendant
control DragObject variable containing the control that just received focus

Usage This event is called by PFC visual controls when they get focus.

22
 Chapter 2 Window Objects

Use this event to add application-specific functionality to be performed when

a visual control gets focus.
If the control getting focus is a DataWindow inherited from u_dw, this event
sets the idw_active instance variable.

pfc_DBError
Description Displays a database error encountered during the pfc_Save process.
Usage This event is called by pfc_Save if an update error occurs.

pfc_Descendant
Description PFC events and functions call this event to determine if the window is inherited
from w_master.
Return value Boolean. Always returns TRUE.
Usage Internal.

pfc_EndTran
Description Empty user event that you extend to initiate end-of-transaction processing,
such as COMMIT or ROLLBACK.
Syntax instancename.EVENT pfc_EndTran ( savecode )
Argument Description
instancename Instance name of the w_master-based descendant
savecode Integer specifying the return code from the pfc_Update function.
From within the pfc_EndTran event, access this value through the
ai_update_results argument

Return value Integer. Return 1 if the end transaction process succeeds and other application-
specific values as appropriate.
Usage This event is called by pfc_Save. The value passed in savecode indicates
whether previous updates succeeded or failed. Based on savecode, you extend
this event to add COMMIT, ROLLBACK, or other end-of-transaction
processing.
Examples This example extends the pfc_EndTran event to COMMIT all open
transactions. This example returns 0 if it succeeds and -1 if a COMMIT fails:
n_tr ltr_trans[ ]
Integer li_trans, li_count

23
w_master

Long ll_return

li_trans = &
gnv_app.inv_trregistration.of_GetRegistered &
(ltr_trans)
IF li_trans = 0 THEN Return 0
For li_count = 1 to li_trans
ll_return = ltr_trans[li_count].of_Commit()
IF ll_return < 0 THEN Return -1
Next
Return 0

pfc_Help
Description Calls the ShowHelp function by index, topic or keyword, based on the
ia_helptypeid instance variable.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is triggered when the window has focus and the user selects
Help>Help Topics from the menu bar of a menu that descends from the PFC
m_master menu. You can also trigger it directly (from a Help
CommandButton, for example).
If the Help type ID is not specified, this event opens the top-level Help contents
topic. Call the n_cst_appmanager of_SetHelpfile function to specify the
application’s Help filename.

pfc_MessageRouter
Description Triggers the passed user event. This event first attempts to trigger the passed
user event on the window, then the current control. If the user event is not
found, it then attempts to trigger the passed user event on the last active
DataWindow control.
Syntax instancename.EVENT pfc_MessageRouter ( userevent )
Argument Description
instancename Instance name of the w_master-based descendant
userevent String specifying the event to trigger. From within the
pfc_MessageRouter event, access this value through the
as_message argument

Return value Integer. Returns 1 if the event succeeds, 0 if no objects contain the user event,
and -1 if an error occurs.

24
 Chapter 2 Window Objects

Usage This event is triggered when the user selects a menu choice that calls the
of_SendMessage menu function.
All PFC visual controls, including u_dw, include events that work with the
message router.

pfc_MicroHelp
Description Ancestor event to which descendants add code that displays MicroHelp.
Syntax instancename.EVENT pfc_MicroHelp ( microhelp )
Argument Description
instancename Instance name of the w_master-based descendant
microhelp String to be displayed in the status bar

Usage This event is called by u_dw ItemFocusChanged event. It is extended in

w_frame and w_sheet.

pfc_MRUClicked
Description Checks for the existence of the specified menu item in the MRU DataStore and
calls the pfc_MRUProcess event if the menu item is found.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Internal.

pfc_MRUProcess
Description Empty user event that you extend to open the appropriate window based on the
clicked MRU menu item.
Syntax instancename.EVENT pfc_MRUProcess ( row )
Argument Description
instancename Instance name of the w_master-based descendant
row Integer specifying the MRU DataStore row that corresponds to the
clicked MRU menu item. From within the pfc_MRUProcess event,
access this value through the ai_row argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage You extend this event to open windows (SDI) or sheets (MDI) with or without
passing parameters.
The pfc_w_master ancestor contains sample code for this event.

25
w_master

Examples This example shows code you might add to the pfc_MRUProcess event:
window lw_frame, lw_window
n_cst_menu lnv_menu
n_cst_mruattrib lnv_mruattrib

// check parameters
if isnull(ai_row) or (ai_row < 1) then
return -1
end if
if not isvalid(gnv_app.inv_mru) then
return -1
end if
// retrieve row from datastore and do work with it
gnv_app.inv_mru.of_getitem(ai_row, lnv_mruattrib)
// get the mdi frame if necessary
lnv_menu.of_getmdiframe(this.menuid, lw_frame)
//example opens
// SDI Process
//open(lw_window, lnv_mruattrib.is_classname)
//openwithparm(lw_window, &
// lnv_mruattrib.is_menuitemkey, &
// lnv_mruattrib.is_classname)
// MDI Process
//opensheet(lw_window, lnv_mruattrib.is_classname, &
// lw_frame)
//opensheet(lw_window, lnv_mruattrib.is_classname, &
// lw_frame, 0, original!)
Return opensheetwithparm(lw_window, &
lnv_mruattrib.is_menuitemkey, &
lnv_mruattrib.is_classname, lw_frame, 0, &
original! )

pfc_MRURestore
Description Empty user event that you extend to restore MRU settings.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Add code to this event that calls the n_cst_mru of_Restore function.
The pfc_w_master ancestor contains sample code for this event.
Examples This example shows the code you add to the pfc_MRURestore event:
If IsValid(gnv_app.inv_mru) Then
Return gnv_app.inv_mru.of_Restore(ls_id, This)
End If

26
 Chapter 2 Window Objects

pfc_MRUSave
Description Saves MRU information for the current window.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Call this event when the window opens (typically in the pfc_PreOpen event).
This event calls the pfc_PreMRUSave event. You must add code to
pfc_PreMRUSave that populates the n_cst_mruattrib object with the ID,
classname, key, menu item text, and menu item help to be saved.

pfc_New
Description Empty user event into which you place code that performs processing to add a
new entity to the current window, window control, or DataWindow.
Usage Use this event for application- and window-specific new entity processing.
This event is triggered when the user selects File>New from the menu bar of a
menu that descends from the PFC m_master menu.
Examples This example, which might be found in a descendent sheet or main window,
inserts a new row into the active DataWindow when the user selects File>New
from the menu bar:
idw_active.InsertRow(0)

pfc_Open
Description Empty user event into which you place code that performs processing to open
a new entity (typically a file) in the current window, window control, or
DataWindow.
Usage Use this event for application- and window-specific open processing.
This event is triggered when the user selects File>Open from the menu bar of
a menu that descends from the PFC m_master menu.
Examples This example, which might be found in a descendent sheet or main window,
displays the Open dialog box when the user selects File>Open from the menu
bar. Is_fullname and is_filename are instance variables:
Integer li_fileid

SetPointer (HourGlass!)
IF GetFileOpenName &
("Open", is_fullname, is_filename &
"txt", "Text Files (*.txt),*.txt) < 1 THEN

27
w_master

Return
END IF

// Open the new file and put results into the MLE.
li_fileid = FileOpen(is_fullname, StreamMode!)
FileRead (li_fileid, mle_notepad.text)
FileClose (li_fileid)
...

pfc_PageSetup
Description Empty user allowing you to add code to display a Page Setup dialog box and
print multiple DataWindows.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Call this event to synch page setup properties among multiple DataWindows.
Examples This example synchs the paper source for three DataWindows:
Integer li_rc
s_pagesetupattrib lstr_pagesetup

li_rc = dw_1.event pfc_PageSetupDlg(lstr_pagesetup)

IF li_rc = 1 THEN
dw_2.object.datawindow.print.paper.source = &
lstr_pagesetup.i_papersource
dw_3.object.datawindow.print.paper.source = &
lstr_pagesetup.i_papersource
END IF
...

pfc_PostOpen
Description Empty user event into which you place code that performs processing just after
a window opens.
Usage Use this event for application- and window-specific post-open processing. This
event executes just after a window opens.
Examples This example calls the Retrieve function in a window’s pfc_PostOpen event:
Long ll_return

ll_return = dw_employee.EVENT pfc_Retrieve()

IF ll_return = -1 THEN
MessageBox("Retrieve", "Retrieval error")
ELSE

28
 Chapter 2 Window Objects

gnv_app.of_getframe().SetMicroHelp &
(String(ll_return) + " rows retrieved")
END IF

pfc_PostUpdate
Description Calls the n_cst_luw of_PostUpdate function, which in turn calls the
of_PostUpdate function for all controls that implement it.
Syntax instancename.EVENT pfc_PostUpdate ( controlarray )
Argument Description
instancename Instance name of the w_master-based descendant
controlarray PowerObject array containing the controls for which to perform
post update processing. From within the pfc_AcceptText event,
access this value through the apo_control argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The pfc_Save user event calls this event after calling the pfc_DBError user
event.
You can extend this event to perform additional post-update processing.

pfc_PreClose
Description Empty user event that you extend to perform processing just before a window
closes.
Return value Integer. Return 1 if the pre-close process succeeds and -1 to prevent the
window from closing.
Usage Use this event for application- and window-specific pre-close processing.
This event executes just before CloseQuery processing.
Examples This example uses the pfc_PreClose function to write to a log file:
IF inv_filesrv.of_FileWrite &
(is_logfile, "Window: " + this.title &
+ " closing at " + String(Today()) &
+ String(Now()),TRUE) = 1 THEN
Return 1
ELSE
Return -1
END IF

29
w_master

pfc_PreMRUSave
Description Empty user event that you extend to create MRU information that you can later
access when opening windows.
Syntax instancename.EVENT pfc_PreMRUSave ( mruattrib )

Argument Description
instancename Instance name of the w_master-based descendant
mruattrib N_cst_mruattrib into which the event places window
information

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The pfc_MRUSave event calls this event.
The pfc_w_master ancestor contains sample code for this event.
Examples This example shows code you might add to the pfc_PreMRUSave event:
anv_mruattrib.is_id = "empinfo"
anv_mruattrib.is_classname = this.classname()
anv_mruattrib.is_menuitemname = this.title
anv_mruattrib.is_menuitemkey = this.classname()
anv_mruattrib.is_menuitemmhelp = &
"Opens " + this.classname()

pfc_PreOpen
Description Empty user event into which you place code that performs processing just
before a window opens.
Usage Use this event for application- and window-specific pre-open processing.
If you are using n_cst_mru to track most recently used windows, you typically
call the pfc_MRUSave event from this event.
This event executes just before a window opens.
Examples This example connects to the database in the frame window’s pfc_PreOpen
event:
String ls_file, ls_section
Long ll_return

ls_file = "c:\pbapp\pbapp.ini"
ls_section = "PBAppDB"

itr_pbapp.of_Init(ls_file, ls_section)
ll_return = itr_pbapp.of_Connect()

30
 Chapter 2 Window Objects

IF ll_return <> 0 THEN

itr_pbapp.of_Rollback()
MessageBox("PBApp", "Connect error")
END IF

pfc_PreUpdate
Description Empty user event into which you place pre-save processing.
Return value Integer. Return 1 if the pre-save processing succeeds and -1 if it does not.
Usage Extend this event to perform application-specific pre-save processing.
The pfc_Save user event calls this event before performing any save
processing. If you return -1, save processing terminates.
Examples This example adds code to the pfc_PreUpdate event to check for user ID:
String ls_user

ls_user = gnv_app.of_GetUserID()
IF ls_user = "RNielsen" THEN
Return -1
ELSE
Return 1
END IF

pfc_Print
Description Empty user event into which you place code that prints windows or
DataWindows, first displaying the Print dialog box.
Usage Extend this event to print application- and window-specific information. For
example, you might print a single DataWindow. Alternatively, you might call
the DataWindow report service’s of_CreateComposite function to create a
composite report of all the window’s DataWindows.
This event is triggered when the user selects File>Print from the menu bar of a
menu that descends from the PFC m_master menu.
Examples This example synchs the copies property of all DataWindows on the window:
Integer li_rc
s_printdlgattrib lstr_printdlg

li_rc = dw_1.Event pfc_PrintDlg(lstr_printdlg)

IF li_rc = 1 THEN
dw_2.object.datawindow.print.copies = &

31
w_master

lstr_printdlg.l_copies
dw_3.object.datawindow.print.copies = &
lstr_printdlg.l_copies
END IF

pfc_PrintImmediate
Description Empty user event into which you place code that prints windows or
DataWindows without displaying the Print dialog box.
Usage Extend this event to print application- and window-specific information.
This event is triggered when the user selects File>Print Immediate from the
menu bar of a menu that descends from the PFC m_master menu.
Examples This example prints the dw_employee DataWindow:
IF dw_employee.Event pfc_PrintImmediate( ) <> 1 THEN
Return -1
END IF

pfc_Save
Description Calls w_master user events and functions to save changes for all self-updating
objects in the window.
Return value Integer. Returns values as follows:
• 1 All save processes succeeded
• 0 No pending updates
• -1 Accept text error
• -2 Updates pending error
• -3 Validation error
• -4 Pre-update process failed
• -5 Pfc_BeginTran failed
• -6 Pfc_Update failed
• -7 Pfc_EndTran failed
• -8 Post-update process failed
• -9 Update prep process failed

32
 Chapter 2 Window Objects

Usage The CloseQuery event calls this user event automatically to check for pending
updates and initiate the save process. You can call it from your application to
save changes, as needed.
For more on the save process, see n_cst_luw on page 1051.

pfc_SaveAs
Description Empty user event allowing you to save all or part of a window.
Usage This event is triggered when the user selects File>Save As from the menu bar
of a menu that descends from the PFC m_master menu.
Examples This example displays the Save As dialog box:
String is_docname, is_named
Integer li_value

li_value = GetFileSaveName("Save As", &

is_docname, is_named, "TXT", &
"Text Files (*.TXT),*.TXT," + &
" Doc Files (*.DOC), *.DOC")
...

pfc_SaveObjects
Description Performs a save on the specified controls.
Syntax instancename.EVENT pfc_SaveObjects ( controlarray )
Argument Description
instancename Instance name of the w_master-based descendant
controlarray PowerObject array containing the controls for which to perform
save processing. From within the pfc_SaveObjects event, access
this value through the apo_control argument

Return value Integer. Returns values as follows:

• 1 All save processes succeeded
• 0 No pending updates
• -1 Accept text error
• -2 Updates pending error
• -3 Validation error
• -4 Pre-update process failed

33
w_master

• -5 Pfc_BeginTran failed
• -6 Pfc_Update failed
• -7 Pfc_EndTran failed
• -8 Post-update process failed
• -9 Update prep process failed
Usage Call the of_SetUpdateObjects function to establish the array of controls to be
updated.
Examples This example calls the pfc_SaveObjects event:
PowerObject lpo_save[ ]
Integer li_return

lpo_save[1] = dw_1
this.of_SetUpdateObjects(lpo_save)
li_return = this.EVENT pfc_SaveObjects(lpo_save)
...

pfc_Update
Description Calls the pfc_UpdateObjects event.
Syntax instancename.EVENT pfc_Update ( controlarray )
Argument Description
instancename Instance name of the w_master-based descendant
controlarray PowerObject array containing the controls to be updated. From
within the pfc_Update event, access this value through the
apo_control argument

Return value Integer. Returns 1 if the event succeeds and -1 if one or more DataWindow
update errors occur.
Usage The pfc_Save event calls this event.

pfc_UpdateObjects
Description Calls the n_cst_luw of_Update function, which in turn calls the of_Update
function for all controls that implement it.
Syntax instancename.EVENT pfc_UpdateObjects ( controls, accepttext, resetflags )
Argument Description
instancename Instance name of the w_master-based descendant

34
 Chapter 2 Window Objects

Argument Description
controls PowerObject array containing the objects to update. This argument
is accessed through the apo_control argument
accepttext Boolean specifying whether n_cst_luw should automatically
perform an AcceptText before performing the Update (TRUE) or
not (FALSE)
resetflags Boolean specifying whether n_cst_luw should automatically reset
DataWindow update flags (TRUE) or not (FALSE)

Return value Integer. Returns 1 if the event succeeds, 0 if no action was taken, and -1 if one
or more update errors occur.
Usage The of_Update function and the pfc_Update event call this event.

pfc_UpdatePrep
Description Empty user event to which you can add code that prepares for update.
Syntax instancename.EVENT pfc_UpdatePrep ( controls )
Argument Description
instancename Instance name of the w_master-based descendant
controls PowerObject array containing the objects to update. This argument
is accessed through the apo_control argument

Return value Long. Return 1 if the update preparation succeeds and -1 to halt the update
process.
Usage The of_UpdatePrep function calls this event.

pfc_UpdatesPending
Description Calls the pfc_UpdatesPendingRef event.
When CloseQuery calls this user event, validation messages are suppressed.
Syntax instancename.EVENT pfc_UpdatesPending ( controlarray )
Argument Description
instancename Instance name of the w_master-based descendant
controlarray PowerObject array containing controls to be tested for pending
updates

Return value Integer. Returns values as follows:

• 1 Pending updates were found

35
w_master

• 0 No pending updates
• -1 AcceptText failed
Usage The CloseQuery event calls this event to determine if there are pending
updates.

pfc_UpdatesPendingRef
Description Calls the n_cst_luw of_UpdatesPending function, which in turn calls the
of_UpdatesPending function for all controls that implement it.
Syntax instancename.Eventpfc_UpdatesPendingRef ( controls, pending )
Argument Description
instancename Instance name of the w_master-based descendant
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument
pending PowerObject array to contain objects with pending updates. This
argument is accessed through the apo_pending argument
(passed by reference)

Return value Integer. Returns values, as follows:

• 1 Pending updates were found
• 0 No pending updates
• -1 AcceptText failed
Usage The pfc_UpdatesPending event calls this event to determine if there are
pending updates.

pfc_Validation
Description Calls the n_cst_luw of_Validation function, which in turn calls the
of_Validation function for all controls that implement it.
Syntax instancename.EVENT pfc_Validation ( controlarray )
Argument Description
instancename Instance name of the w_master-based descendant
controlarray PowerObject control array containing controls to be validate

Return value Integer. Returns 1 if there are no validation errors and -1 if a validation error
occurs.

36
 Chapter 2 Window Objects

Usage The of_Validation and of_UpdateChecks functions call this event to determine
if there are validation errors.

Resize
Description Triggers automatic resize processing, if enabled in n_cst_resize.
Usage This event executes when the user resizes the window.

Functions
W_master includes precoded object functions:
of_AcceptText of_SetDBErrorMsg
of_GetCloseStatus of_SetLogicalUnitOfWork
of_GetDWType of_SetPreference
of_GetInfo of_SetResize
of_GetSaveStatus of_SetUpdateable
of_GetUpdateObjects of_SetUpdateObjects
of_IsAlwaysValidate of_SetUpdateRequestor
of_IsUpdateable of_Update
of_MessageBox of_UpdateChecks
of_PostUpdate of_UpdatePrep
of_SetAlwaysValidate of_UpdatesPending
of_SetBase of_Validation

of_AcceptText
Description Calls the pfc_AcceptText event.
Access Public
Syntax instancename.of_AcceptText ( focusonerror )
Argument Description
instancename Instance name of w_master
focusonerror Boolean indicating whether PFC sets focus to the first item in error
when an error occurs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.

37
w_master

Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize accept text processing,
extend the pfc_AcceptText event.
Examples This example is from the n_cst_luw of_AcceptText function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_AcceptText &
(ab_focusonerror)
If li_rc < 0 Then Return -1

...

of_GetCloseStatus
Description Reports the window’s close status (whether the window is closing.)
Access Public
Syntax windowname.of_GetCloseStatus ( )
Argument Description
windowname Instance name of w_master

Return value Boolean. Returns TRUE if the window is closing and FALSE if it is not.
Usage PFC does not report validation errors if the window is closing.
Examples This example calls the of_GetCloseStatus function:
IF al_row <> 0 AND &
(Not lw_parent. of_GetCloseStatus ( )) THEN
IF IsValid(gnv_app) THEN
MessageBox(gnv_app.iapp_object.Appname, &
"Required Value Missing for " &
+ as_colname + " on row " + &
String(al_row) + &
’. Please enter a value.’, StopSign!)
ELSE
...

of_GetDWType
Description Indicates whether a DataWindow is a descendant of u_dw and whether it uses
the linkage service.
Access Protected

38
 Chapter 2 Window Objects

Syntax instancename.of_GetDWType ( datawindow )

Argument Description
instancename Instance name of w_master
datawindow DataWindow variable containing the DataWindow to be tested

Return value Integer. Returns values as follows:

• 0 Datawindow is not a descendant of u_dw
• 1 Datawindow is a descendant of u_dw
• 2 Datawindow is a descendant of u_dw and it is linked
• -1 An error occurred
Usage Internal.
Examples This example calls the of_GetDWType function:
...
li_dwtype = of_GetDWType (ldw_dw)
If li_dwtype < 0 Then Return -1
...

of_GetInfo
Description Retrieves object information.
Access Public
Syntax instancename.of_GetInfo ( infoobject )
Argument Description
instancename Instance name of w_master
infoobject N_cst_infoattrib instance into which the function places
information (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_GetInfo function:
n_cst_infoattrib lnv_info

w_emplist.of_GetInfo(lnv_info)
MessageBox("Info", &
"Description: " + lnv_info.is_description &
+ ". Name: " + lnv_info.is_name)

39
w_master

of_GetSaveStatus
Description Reports the window’s save status (whether the window is in the process of
updating its DataWindows).
Access Public
Syntax windowname.of_GetSaveStatus ( )
Argument Description
windowname Instance name of w_master

Return value Boolean. Returns TRUE if the window is updating and FALSE if it is not.
Usage Call this function to determine whether a window is updating its
DataWindows.
Examples This example calls the of_GetSaveStatus function:
...
IF lw_parent.TriggerEvent &
("pfc_Descendant") = 1 THEN
lb_pfcsaveprocess = &
lw_parent.of_GetSaveStatus()
END IF
...

of_GetUpdateObjects
Description Retrieves the current default array of objects affected by the update process.
Access Protected
Syntax instancename.of_GetUpdateObjects ( objects )
Argument Description
instancename Instance name of w_master
objects PowerObject array into which the function places objects to be
updated (passed by reference)

Return value Integer. Returns the number of elements in the objects array if the function
succeeds and -1 if an error occurs.
Examples This example calls the of_GetUpdateObjects function:
PowerObject lpo_objs[ ]
Integer li_return, li_count

li_return = this.of_GetUpdateObjects(lpo_objs)
FOR li_count = 1 to li_return

40
 Chapter 2 Window Objects

IF lpo_objs[li_count] = ids_data THEN

Return 1
END IF
NEXT
li_return++
lpo_objs[li_return] = ids_data
Return this.of_SetUpdateObjects(lpo_objs)

of_IsAlwaysValidate
Description Reports whether the default save process always performs validation.
Access Protected
Syntax instancename.of_IsAlwaysValidate ( )
Argument Description
instancename Instance name of w_master

Return value Boolean. Returns TRUE if the default save process always performs validation
and FALSE if it does not.
Examples This example calls the of_IsAlwaysValidate function:
IF this.of_IsAlwaysValidate() = TRUE THEN
MessageBox("Window", "Always validate")
ELSE
MessageBox("Window", "Sometimes validate")
END IF

of_IsUpdateable
Description Reports whether the window is updatable and should be included in save
processing.
Access Protected
Syntax instancename.of_IsUpdateable ( )
Argument Description
instancename Instance name of w_master

Return value Boolean. Returns TRUE if the window is updatable and FALSE if it is not.
Usage Internal.

41
w_master

Examples This example is from the pfc_UpdatesPendingRef event:

...
If Not of_IsUpdateable() Then Return NO_UPDATESPENDING
...

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of w_master
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in windows.
The id argument is not used in the default implementation.

42
 Chapter 2 Window Objects

Examples This example calls the of_MessageBox function:

of_Messagebox(’win_error’,’Save’, &
as_error, StopSign!, Ok!, 1)

of_PostUpdate
Description Calls the pfc_PostUpdate event.
Access Public
Syntax instancename.of_PostUpdate ( )
Argument Description
instancename Instance name of w_master

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize post-update processing,
extend the pfc_PostUpdate event.
Examples This example is from the n_cst_luw of_PostUpdate function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_PostUpdate()
...

of_SetAlwaysValidate
Description Specifies whether the default save process always performs validation.
Access Protected
Syntax instancename.of_SetAlwaysValidate ( boolean )
Argument Description
instancename Instance name of w_master
boolean Boolean specifying whether the default save process always
perform validation (TRUE) or only performs validation if a
control has pending updates (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetAlwaysValidate function:
this.of_SetAlwaysValidate(TRUE)

43
w_master

of_SetBase
Description Enables or disables n_cst_winsrv, which provides basic window services.
Access Public
Syntax instancename.of_SetBase ( boolean )
Argument Description
instancename Instance name of w_master
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
an instance of the n_cst_winsrv object

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_winsrv. This instance
is named inv_base.
Because all window services are descendants of n_cst_winsrv (and have
n_cst_winsrv functions available to them), use this object when you require
basic window services only.
Examples This example calls the of_SetBase function in a window Open event to enable
basic window services:
this.of_SetBase (TRUE)

of_SetDBErrorMsg
Description Saves a database update error message for display after save processing
completes.
Access Public
Syntax windowname.of_SetDBErrorMsg ( message )
Argument Description
windowname Instance name of w_master
message String or n_cst_dberrorattrib containing the error message

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to save a database error message for display after
ROLLBACK processing completes.

44
 Chapter 2 Window Objects

The u_dw DBError event populates this instance variable, suppressing the
display of a message dialog box. This allows you to roll back changes in the
pfc_EndTran event. After calling pfc_EndTran, the pfc_Save process displays
this message.
Examples This example is from the u_dw DBError event:
...
If IsValid(lpo_updaterequestor) Then
lpo_updaterequestor.Dynamic Function &
of_SetDBErrorMsg(lnv_dberrorattrib)
Else
...

of_SetLogicalUnitOfWork
Description Enables or disables n_cst_luw, which provides the logical unit of work service.
Access Public
Syntax instancename.of_SetLogicalUnitOfWork ( boolean )
Argument Description
instancename Instance name of w_master
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) n_cst_luw

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_luw. This instance is
named inv_luw. If you do not enable n_cst_luw, w_master enables it
automatically.
Examples This example calls the of_SetLogicalUnitOfWork function:
this.of_SetLogicalUnitOfWork(TRUE)

of_SetPreference
Description Enables or disables n_cst_winsrv_preference, the window preference service.
Access Public
Syntax instancename.of_SetPreference ( boolean )
Argument Description
instancename Instance name of w_master

45
w_master

Argument Description
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
an instance of the n_cst_winsrv_preference object

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_winsrv_preference.
This instance is named inv_preference.
Examples This example calls the of_SetPreference function:
this.of_SetPreference(TRUE)

of_SetResize
Description Enables or disables n_cst_resize, the resize service.
Access Public
Syntax instancename.of_SetResize ( boolean )
Argument Description
instancename Instance name of w_master
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
an instance of the n_cst_resize object

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_resize. This instance
is named inv_resize.
Examples This example calls the of_SetResize function:
this.of_SetResize(TRUE)

of_SetUpdateable
Description Specifies whether the window is updatable and should be included in a default
save process.
Access Protected
Syntax instancename.of_SetUpdateable ( boolean )
Argument Description
instancename Instance name of w_master

46
 Chapter 2 Window Objects

Argument Description
boolean Boolean indicating whether the window is updatable

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to disable default save processing for windows that are not
updatable.
Examples This example calls the of_SetUpdateable function:
this.of_SetUpdateable(FALSE)

of_SetUpdateObjects
Description Sets a new default array containing objects for which updates are attempted.
Access Protected
Syntax instancename.of_SetUpdateObjects ( requestor )
Argument Description
instancename Instance name of u_dw
requestor PowerObject array containing the object to be updated

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to customize the objects updated by the save process. You
can even add other windows to the save process.
Examples This example calls the of_SetUpdateObjects function:
PowerObject lpo_objs[ ]
Integer li_count

lpo_objs = this.control
li_count = UpperBound(lpo_objs)
li_count++
// Update w_other as well as this window
lpo_objs[li_count] = w_other
Return this.of_SetUpdateObjects(lpo_objs)

of_SetUpdateRequestor
Description Creates a reference to the object requesting an update within a logical unit of
work.
Access Protected
Syntax instancename.of_SetUpdateRequestor ( requestor )

47
w_master

Argument Description
instancename Instance name of w_master
requestor PowerObject containing the object requesting the update

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_SetLogicalUnitOfWork function:
...
inv_luw = create n_cst_luw
inv_luw.of_SetRequestor (this)
inv_luw.of_SetUpdateRequestor (this)
...

of_Update
Description Calls the pfc_UpdateObjects event.
Access Public
Syntax instancename.of_Update ( accept, resetflag {, requestor } )
Argument Description
instancename Instance name of w_master
accept Boolean indicating whether the Update function performs an
AcceptText before saving rows to the database
resetflag Boolean indicating whether the Update function resets the update
flags
requestor PowerObject containing the requestor object
(optional)

Return value Integer. Returns 1 if the update succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update processing, extend
the pfc_Update event.
You typically call the pfc_Save event instead of this function.
Examples This example is from the n_cst_luw of_Update function:
...
If lb_defined Then
li_rc = lpo_tocheck.Function Dynamic of_Update &
(ab_accepttext, ab_resetflag, &
lpo_updaterequestor)

48
 Chapter 2 Window Objects

If li_rc < 0 Then Return -1

Continue
End If
...

of_UpdateChecks
Description Determines whether edits are pending and whether there are any validation
errors.
Access Protected
Syntax instancename.of_UpdateChecks ( { controls } )
Argument Description
instancename Instance name of w_master
controls PowerObject array containing the objects to be checked
(optional)

Return value Integer. Returns values as follows:

• 1 Updates are pending and there are no validation errors
• 0 No updates pending
• -1 AcceptText error
• -2 UpdatesPending error
• -3 Validation error
Usage Internal.
Examples This example is from the pfc_Save event:
...
li_rc = of_UpdateChecks(lpo_updatearray)
If li_rc <= 0 Then
...

of_UpdatePrep
Description Calls the pfc_UpdatePrep event, which allows you to code additional update
preparation logic.
Access Public
Syntax instancename.of_UpdatePrep ( )

49
w_master

Argument Description
instancename Instance name of w_master

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update preparation
processing, extend the pfc_UpdatePrep event.
Examples This example is from the n_cst_luw of_UpdatePrep function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_UpdatePrep()
If li_rc < 0 Then Return -1
Continue
End If
...

of_UpdatesPending
Description Calls the pfc_UpdatesPendingRef event.
Access Public
Syntax instancename.of_UpdatesPending ( )
Argument Description
instancename Instance name of w_master

Return value Integer. Returns values as follows:

• 1 Updates are pending
• 0 No updates pending
• -1 An error occurred
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize pending updates
processing, extend the pfc_UpdatesPending event.
Examples This example calls the of_UpdatesPending function:
...
If lb_defined Then
la_rc = lpo_tocheck.Dynamic of_UpdatesPending()
...

50
 Chapter 2 Window Objects

of_Validation
Description Calls the pfc_Validation event.
Access Public
Syntax instancename.of_Validation ( )
Argument Description
instancename Instance name of w_master

Return value Integer. Returns 1 if the function succeeds and -1 if a validation error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize validation processing,
extend the pfc_Validation event.
Examples This example calls the of_Validation function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_Validation()
...

51
w_popup

w_popup
Description Ancestor for all PowerBuilder Foundation Class Library popup windows.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use w_popup as the ancestor window for all popup windows.
See also w_master

52
 Chapter 2 Window Objects

w_response
Description Ancestor for all PFC response windows.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use w_response as the ancestor window for all response windows.
Add OK, Cancel, and window-specific CommandButtons to your w_response
descendant. Then add code to the CommandButtons’ Clicked events to trigger
the appropriate w_response user event. Typically, Cancel triggers pfc_Cancel,
Apply triggers pfc_Apply, and OK triggers pfc_Default.
See also w_master

Events
W_response includes predefined events:
pfc_Apply pfc_Default
pfc_Cancel

53
w_response

pfc_Apply
Description Empty user event to which you add code that applies dialog box specifications
to the associated sheet or window.
Usage Add code to this event to apply specifications to the associated sheet or
window. Trigger this user event from a cb_apply.Clicked event script.
Examples This example shows code you might add to pfc_Apply:
Integer li_cnt, li_arraysize, li_rc
Boolean lb
ToolbarAlignment lt
String ls

// Set toolbar settings

li_arraysize = UpperBound(istr_toolbar[])
FOR li_cnt = 1 to li_arraysize
istr_toolbar[li_cnt].w_owner.SetToolbar &
(istr_toolbar[li_cnt].i_barindex, &
istr_toolbar[li_cnt].b_visible, &
istr_toolbar[li_cnt].e_alignment, &
istr_toolbar[li_cnt].s_title)
istr_toolbar[li_cnt].w_owner.GetToolbar &
(istr_toolbar[li_cnt].i_barindex, lb, lt, ls)
NEXT
// Set application toolbar settings
iapp_object.ToolbarText = cbx_text.checked
iapp_object.ToolbarTips = cbx_tips.checked
// Disable Apply button. Make OK the default
cb_apply.Enabled = False
cb_apply.Default = False
cb_cancel.Default = False
cb_ok.Default = True

pfc_Cancel
Description Empty user event to which you add code that closes the window without
accepting changes.
Usage Add code to this user event to close the window without accepting changes.
Trigger this user event from the cb_cancel.Clicked event script.
Examples This example closes the window and passes a return value of 0:
CloseWithReturn(This, 0)

54
 Chapter 2 Window Objects

pfc_Default
Description Event to apply changes and close a response window.
Usage Add code to this event to apply changes and close a response window. It is
meant to be triggered by the default CommandButton (typically cb_ok), but it
could be triggered by Cancel, Close, or some other CommandButton.
Examples This example shows code you might add to the pfc_Default:
SetPointer(HourGlass!)

SQLCA.dbms = "ODBC"
SQLCA.database = "expense"
SQLCA.logid = sle_userid.text
SQLCA.logpass = sle_password.text
SQLCA.dbparm = "Connectstring=’DSN=" + &
SQLCA.database + ";UID=" + &
SQLCA.logid + ";PWD=" + SQLCA.logpass + "’"
IF SQLCA.of_Connect() <> 0 THEN
MessageBox("Login Error", SQLCA.SQLErrText)
CloseWithReturn(This, 0)
ELSE
CloseWithReturn(This, 1)
END IF

55
w_sheet

w_sheet
Description Ancestor for all PowerBuilder Foundation Class Library sheet windows.
This window contains automatic MicroHelp display capability.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships n_cst_string
Usage Use this window as the ancestor for all of your application’s sheet windows.
If you want to display MicroHelp for controls within a sheet, associate the
MicroHelp text with each control’s tag value. The control’s tag value must
specify MICROHELP=microhelptext. When the control gets focus, the
pfc_ControlGotFocus event displays the tag text in the status bar.
See also w_frame
w_master

Events
W_sheet includes predefined events:
Activate

56
 Chapter 2 Window Objects

pfc_MicroHelp
pfc_ControlGotFocus

Activate
Description Sets MicroHelp to the control with focus.
Usage This event executes whenever the window receives focus.

pfc_ControlGotFocus
Description Displays the MicroHelp stored in the control’s tag value.
This event extends the ancestor pfc_ControlGotFocus event.
Syntax instancename.EVENT pfc_ControlGotFocus ( control )
Argument Description
instancename Instance name of w_sheet-based descendant
control DragObject variable containing the control that just got focus

Usage This event is called by PFC visual controls when they get focus.
The control’s tag value must specify MICROHELP=microhelptext.

pfc_MicroHelp
Description Updates MicroHelp by calling the frame’s pfc_MicroHelp event.
This event extends the ancestor pfc_MicroHelp event.
Syntax instancename.EVENT pfc_MicroHelp ( microhelp )
Argument Description
instancename Instance name of w_sheet-based descendant
microhelp String to be displayed in the status bar

Usage This event executes whenever the sheet or a control on the sheet receives focus.

57
w_sheet

58
CH A PTE R 3 Menus

About this chapter This chapter describes the menus in the PowerBuilder Foundation Class
Library (PFC).
Contents The menus are listed in alphabetical order. The information for each menu
includes an alphabetical listing of instance variables, events, and menu
functions.

59
m_dw

m_dw
Description Popup menu displayed when the user releases the right mouse button over a
u_dw based DataWindow control.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL

Menu bar items

M_dw is a popup menu and has a single menu bar item:
Table

Table menu
Menu items
Menu item Description
Cut Calls the pfc_Cut event
Copy Calls the pfc_Copy
Paste Calls the pfc_Paste event
Select All Calls the pfc_SelectAll event
Insert Calls the pfc_InsertRow event
Add Calls the pfc_AddRow event
Delete Calls the pfc_DeleteRow event
Restore Calls the pfc_RestoreRow event
Columns Calls the pfc_Columns event
Functions Calls the pfc_Functions event
Operators Calls the pfc_Operators event
Values Calls the pfc_Values event
DataWindow Calls the pfc_Debug event
Properties
Properties Empty menu item. Add calls to functions or events that
display properties for a DataWindow column

60
 Chapter 3 Menus

See also u_dw

Instance variables
M_dw includes one instance variable:
Instance variable Description Data type Access Usage
idw_parent Owning DataWindow DataWindow Protected Used to access the current
control. DataWindow control

Functions
M_dw includes one precoded object function:
of_SetParent

of_SetParent
Description Establishes the current DataWindow control.
Access Public
Syntax instancename.of_SetParent ( currentdw )
Argument Description
instancename Instance name of m_dw
currentdw DataWindow variable identifying the DataWindow that opened
this instance of m_dw

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage U_dw calls this function to establish a relationship with m_dw.
Examples This example is from the u_dw RButtonUp event:
...
lm_dw = create m_dw
lm_dw.of_SetParent(this)
...

61
m_edit

m_edit
Description Popup menu displayed when the user releases the right mouse button over
certain PFC visual controls.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL

Menu bar items

M_edit is a popup menu and has a single menu bar item:
Edit

Edit menu
Menu items
Menu
item Description
Cut Calls the pfc_Cut event for the current window or window control
Copy Calls the pfc_Copy event for the current window or window control
Paste Calls the pfc_Paste event for the current window or window control
Select All Calls the pfc_SelectAll event for the current window or window
control

See also u_mle

u_rte
u_sle

62
 Chapter 3 Menus

Instance variables
M_edit includes one instance variable:
Instance variable Description Data type Access Usage
idrg_current Current window or window DragObject Protected Used to access the current
control control

Functions
M_edit includes one precoded object function:
of_SetParent

of_SetParent
Description Establishes the current control.
Access Public
Syntax instancename.of_SetParent ( currentcontrol )
Argument Description
instancename Instance name of m_edit
currentcontrol DragObject containing the control that opened this instance of
m_edit

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage PFC visual objects call this function to establish a relationship with m_edit.
Examples This example is from the u_rte RButtonUp event:
Integer li_rc
m_edit lm_edit
Window lw_parent
String ls_selectedtext
...
lm_edit = create m_edit
lm_edit.of_SetParent(this)
...

63
m_frame

m_frame
Description The m_frame menu is a descendant of m_master with most items disabled and
hidden. Use this menu as the frame menu for your application, modifying and
adding menu items as necessary.
Ancestry

Library PFEWNSRV.PBL

Menu bar items

The m_frame menu has the following visible menu bar items:
File
Help

File menu
Menu items
Menu
item Description
New Calls the pfc_New event for the frame window
Open Calls the pfc_Open event for the frame window
Exit Calls the pfc_Exit event for the frame window

Help menu
Menu items
Menu item Description
Help Topics Calls the pfc_Help event for the frame window
About Calls the n_cst_appmanager of_About function

See also m_master

w_frame

64
 Chapter 3 Menus

m_lvs
Description Popup menu displayed when the user releases the right mouse button over a
ListView based on u_lvs.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL

Menu bar items

M_lvs is a popup menu and has a single menu bar item:
View

View menu
Menu items
Menu item Description
View Changes the ListView display style. Options are:
• Large icon
• Small icon
• List
• Report
Arrange Icons Sorts the display by the specified column
Select All Calls the pfc_SelectAll event
Invert Selection Calls the pfc_InvertSelection event
Cut Calls the pfc_Cut event
Copy Calls the pfc_Copy event
Paste Calls the pfc_Paste event
Clear Calls the pfc_Clear event
New Calls the pfc_New event
Delete Calls the pfc_Delete event
Rename Calls the pfc_Rename event

65
m_lvs

Menu item Description

Properties Calls the pfc_Properties event

See also u_lvs

Instance variables
M_lvs includes one instance variable:
Instance variable Description Data type Access Usage
ilv_parent ListView control displaying ListView Protected Used to access the associated
the popup menu. ListView control

Functions
M_lvs includes one precoded object function:
of_SetParent

of_SetParent
Description Establishes the ListView control associated with an instance of the m_lvs
popup menu.
Access Public
Syntax instancename.of_SetParent ( listview )
Argument Description
instancename Instance name of m_lvs
listview ListView variable containing the ListView that opened this
instance of m_lvs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage U_lvs calls this function to establish a relationship with m_lvs.

66
 Chapter 3 Menus

Examples This example calls the of_SetParent function:

...
if IsNull(lm_view) Or not IsValid(lm_view) then
lm_view = create m_lvs
lm_view.of_SetParent(this)
end if
...

67
m_master

m_master
Description Master menu for all PFC applications. Use this menu as the ancestor for your
application’s menus.
Ancestry

Library PFCWNSRV.PBL
PFEWNSRV.PBL

Menu bar items

The m_master menu has the following menu bar items:
File
Edit
View
Insert
Tools
Window
Help

File menu
Menu items
Menu item Description
New Calls the pfc_New event for the current window or window control
Open Calls the pfc_Open event for the current window or window control
Close Calls the pfc_Close event for the current window or window control
Save Calls the pfc_Save event for the current window or window control
Save As Calls the pfc_SaveAs event for the current window or window
control
Print Calls the pfc_Print event for the current window or window control
Print Preview Calls the pfc_PrintPreview event for the current window or window
control
Page Setup Calls the pfc_PageSetup event for the current window or window
control

68
 Chapter 3 Menus

Menu item Description

Print Calls the pfc_PrintImmediate event for the current window or
Immediate window control
Delete Empty menu item. Add calls to function or events that perform
deletion
Properties Empty menu item. Add calls to function or events that display
properties
Exit Calls the pfc_Exit event for the current window or window control
PFCMRU1 Calls the pfc_MRUClicked event for the current window or window
through control
PFCMRU5

Edit menu
Menu items
Menu item Description
Undo Calls the pfc_Undo event for the current window or window control
Cut Calls the pfc_Cut event for the current window or window control
Copy Calls the pfc_Copy event for the current window or window control
Paste Calls the pfc_Paste event for the current window or window control
Paste Special Calls the pfc_PasteSpecial event for the current window or window
control
Clear Calls the pfc_Clear event for the current window or window control
Select All Calls the pfc_SelectAll event for the current window or window
control
Find Calls the pfc_FindDlg event for the current window or window
control
Replace Calls the pfc_ReplaceDlg event for the current window or window
control
Update Links Calls the pfc_UpdateLinks event for the current window or window
control
Object>Edit Calls the pfc_EditObject event for the current window or window
control
Object>Open Calls the pfc_OpenObject event for the current window or window
control

View menu
Menu items
Menu item Description
Ruler Calls the pfc_Ruler event for the current window or window control

69
m_master

Menu item Description

Large Icon Empty menu item. Add calls to function or events that change
ListView display
Small Icon Empty menu item. Add calls to function or events that change
ListView display
List Empty menu item. Add calls to function or events that change
ListView display
Details Empty menu item. Add calls to function or events that change
ListView display
Arrange Empty menu item. Add calls to function or events that arrange icons
Icons>By
Arrange Empty menu item. Add calls to function or events that arrange icons
Icons>Auto
Arrange
First Calls the pfc_FirstPage event for the current window or window
control
Next Calls the pfc_NextPage event for the current window or window
control
Prior Calls the pfc_PreviousPage event for the current window or window
control
Last Calls the pfc_LastPage event for the current window or window
control
Sort Calls the pfc_SortDlg event for the current window or window control
Filter Calls the pfc_FilterDlg event for the current window or window
control
Zoom Calls the pfc_Zoom event for the current window or window control

Insert menu
Menu items
Menu
item Description
File Calls the pfc_InsertFile event for the current window or window
control
Picture Calls the pfc_InsertPicture event for the current window or window
control
Object Calls the pfc_InsertObject event for the current window or window
control

70
 Chapter 3 Menus

Tools menu
Menu items
Menu item Description
Customize Calls the pfc_Toolbars event for the current window or window
Toolbars control

Window menu
Menu items
Menu item Description
Cascade Calls the pfc_Cascade event for the frame window
Tile Horizontal Calls the pfc_TileHorizontal event for the frame window
Tile Vertical Calls the pfc_TileVertical event for the frame window
Layer Calls the pfc_Layer event for the frame window
Minimize All Calls the pfc_MinimizeAll event for the frame window
Undo Arrange Calls the pfc_UndoArrange event for the frame window

Help menu
Menu items
Menu item Description
Help Topics Calls the pfc_Help event for the current window or window
control
About Calls the n_cst_appmanager of_About function

See also m_frame

w_frame
w_master

Functions
The m_master menu includes one precoded object function:
of_SendMessage

of_SendMessage
Description Calls the n_cst_menu of_SendMessage function, which sends the passed
message to the current window through the pfc_MessageRouter event.

71
m_master

Access Public
Syntax instancename.of_SendMessage ( message )
Argument Description
instancename Instance name of m_master
message String specifying the user event to be triggered by the
pfc_MessageRouter event

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage PFC menu items call this function to trigger events on the associated window
and window controls.
Examples This example is from the m_master File>Open menu item’s Clicked event.
SetPointer (hourglass!)
of_SendMessage("pfc_open")

72
 Chapter 3 Menus

m_oc
Description Popup menu displayed when the user releases the right mouse button over an
OLE control based on u_oc.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL

Menu bar items

M_oc is a popup menu and has a single menu bar item:
Object

Object menu
Menu items
Menu item Description
Edit Calls the pfc_EditObject event for the OLE control
Open Calls the pfc_OpenObject event for the OLE control
Cut Calls the pfc_Cut event for the OLE control
Copy Calls the pfc_Copy event for the OLE control
Paste Calls the pfc_Paste event for the OLE control

See also u_oc

Instance variables
M_oc includes one instance variable:
Instance
variable Description Data type Access Usage
ioc_parent OLE control displaying the OLEControl Protected Used to access the associated
popup menu. OLE control.

73
m_oc

Functions
M_oc includes one precoded object function:
of_SetParent

of_SetParent
Description Establishes the OLE control associated with an instance of the m_oc popup
menu.
Access Public
Syntax instancename.of_SetParent ( olecontrol )
Argument Description
instancename Instance name of m_oc
olecontrol OLEControl variable containing the OLE control that opened this
instance of m_oc

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage U_oc calls this function to establish a relationship with m_oc.
Examples This example calls the of_SetParent function:
m_oc lm_oc
String ls_selectedtext
...
lm_view = create m_oc
lm_view.of_SetParent(this)
...

74
 Chapter 3 Menus

m_tvs
Description Popup menu displayed when the user releases the right mouse button over a
TreeView based on u_tvs.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL

Menu bar items

M_tvs is a popup menu and has a single menu bar item:
View

View menu
Menu items
Menu item Description
Open Calls the pfc_Open event
Find Calls the pfc_FindDlg event
Cut Calls the pfc_Cut event
Copy Calls the pfc_Copy event
Paste Calls the pfc_Paste event
Clear Calls the pfc_Clear event
New Calls the pfc_New event
Delete Calls the pfc_Delete event
Rename Calls the pfc_Rename event
Properties Calls the pfc_Properties event

See also u_tvs

Instance variables
M_tvs includes one instance variable:

75
m_tvs

Instance variable Description Data type Access Usage

itv_parent TreeView control displaying TreeView Protected Used to access the
the popup menu. associated TreeView
control

Functions
M_tvs includes one precoded object function:
of_SetParent

of_SetParent
Description Establishes the TreeView control associated with an instance of the m_tvs
popup menu.
Access Public
Syntax instancename.of_SetParent ( listview )
Argument Description
instancename Instance name of m_tvs
listview TreeView variable containing the TreeView that opened this
instance of m_tvs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage U_tvs calls this function to establish a relationship with m_tvs.
Examples This example calls the of_SetParent function:
...
im_view = CREATE m_tvs
im_view.of_SetParent(this)
...

76
CH A PTE R 4 Global Functions

About this chapter This chapter describes the global functions in the PowerBuilder
Foundation Class Library (PFC).

77
f_SetFilesrv

f_SetFilesrv
Description Enables or disables the platform-specific file-handling service. The file service
is implemented through the n_cst_filesrv user object and its descendants.
This function creates a descendant of n_cst_filesrv:
• n_cst_filesrvwin32
Access Public
Syntax f_SetFilesrv ( fileservice, boolean )
Argument Description
fileservice N_cst_filesrv variable into which the function creates the
platform-specific n_cst_filesrv descendant
boolean Boolean specifying whether to create an instance of
n_cst_filesrv (TRUE) or destroy an instance of n_cst_filesrv
(FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to enable and disable the file service.
These objects contain functions that make external function calls to perform
operating system-specific file processing.
Examples This example enables the file service. It assumes an inv_filesrv instance
variable:
f_SetFileSrv(inv_filesrv, TRUE)
See also f_SetPlatform
n_cst_filesrv
n_cst_platform

78
 Chapter 4 Global Functions

f_SetPlatform
Description Enables or disables platform-specific services. The platform service is
implemented through the n_cst_platform user object and its descendants.
This function creates a descendant of n_cst_platform:
• n_cst_platformwin32
Access Public
Syntax f_SetPlatform ( platformservice, boolean )
Argument Description
platformservice N_cst_platform variable into which the function creates the
platform-specific n_cst_platform descendant
boolean Boolean specifying whether to create an instance of
n_cst_platform (TRUE) or destroy an instance of n_cst_platform
(FALSE).

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to enable and disable the platform service.
These objects contain functions that make external function calls to return
operating system-specific information and play sounds.
Examples This example enables the platform service. It assumes an inv_platform instance
variable:
f_SetPlatform(inv_platform, TRUE)
See also f_SetFilesrv
n_cst_filesrv
n_cst_platform

79
f_SetPlatform

80
CH A PTE R 5 Global Structures and Structure
Objects

About this chapter This chapter describes the global structures and structure objects in the
PowerBuilder Foundation Class Library (PFC).
Structure objects are autoinstantiated custom class user objects that
consist solely of instance variables. These objects provide all the
functionality of global structures and they also allow you to extend them
by adding instance variables, events, and object functions.
Contents The global structures and structure objects are listed alphabetically.

81
n_cst_aboutattrib

n_cst_aboutattrib
Description Structure object containing information displayed in w_about.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
is_application String
is_copyright String
is_logo String
is_version String

See also n_cst_appmanager

82
 Chapter 5 Global Structures and Structure Objects

n_cst_baseattrib
Description Ancestor of all structure objects. This object contains no properties. To define
a global property or function for structure objects, define it in this object.
Library PFCMAIN.PBL
PFEMAIN.PBL
Properties No properties
See also All other structure objects

83
n_cst_calculatorattrib

n_cst_calculatorattrib
Description Structure object containing information used by u_calculator.
Library PFCMAIN.PBL
PFEMAIN.PBL
Properties
Field Data type
ib_dropdown Boolean

See also u_calculator

84
 Chapter 5 Global Structures and Structure Objects

n_cst_calendarattrib
Description Structure object containing information used by u_calendar.
Library PFCMAIN.PBL
PFEMAIN.PBL
Properties
Field Data type
ib_dropdown Boolean

See also u_calendar

85
n_cst_columnattrib

n_cst_columnattrib
Description Structure object containing column information.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
is_colformat String
is_coltype String
is_columns String

See also n_cst_lvsrv_datasource

n_cst_lvsrv_sort

86
 Chapter 5 Global Structures and Structure Objects

n_cst_dberrorattrib
Description Structure object containing database error information.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
idwb_buffer DWBuffer
il_row Long
il_sqldbcode Long
ipo_inerror PowerObject
is_errormsg String
is_sqlerrtext String
is_sqlsyntax String

See also n_cst_luw

w_master

87
n_cst_dirattrib

n_cst_dirattrib
Description Structure object containing information used in n_cst_filesrv and its
descendants.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ib_archive Boolean
ib_drive Boolean
ib_hidden Boolean
ib_readonly Boolean
ib_subdirectory Boolean
ib_system Boolean
id_creationdate Date
id_lastaccessdate Date
id_lastwritedate Date
idb_filesize Date
is_altfilename String
is_filename String
it_creationtime Time
it_lastwritetime Time

See also n_cst_filesrv

n_cst_filesrvwin32

88
 Chapter 5 Global Structures and Structure Objects

n_cst_dssrv_multitableattrib
Description Structure object containing information used to control multitable updates.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
b_keyupdateinplace Boolean
i_whereoption Integer
s_keycolumns[ ] String
s_updatecolumns[ ] String
s_updatetable String

See also n_cst_dssrv_multitable

n_cst_dwsrv_multitable

89
n_cst_dwcacheattrib

n_cst_dwcacheattrib
Description Structure object containing information about cached data.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
a_args[] Any
ds_originalcontrol DataStore
dw_originalcontrol DataWindow
ds_obj N_ds
tr_obj N_tr
po_originaldata[] PowerObject
s_id String
s_filename String
s_method String
s_originaldataobject String

See also n_cst_dwcache

90
 Chapter 5 Global Structures and Structure Objects

n_cst_dwobjectattrib
Description Structure object containing information used in n_cst_dwcache, n_cst_dssrv,
n_cst_dwsrv, and its descendants.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
is_column String
is_datatype String
is_value String

See also n_cst_dwcache

n_cst_dssrv
n_cst_dwsrv

91
n_cst_dwpropertyattrib

n_cst_dwpropertyattrib
Description Structure object containing DataWindow property information.
Library PFCUTIL.PBL
PFEUTIL.PBL
Properties
Field Data type
idw_requestor DataWindow
is_dataobjectbuffer String
is_dataobjectstatus String
is_objectname String
is_tabpages String
iw_mail Window

See also w_dwproperty

92
 Chapter 5 Global Structures and Structure Objects

n_cst_dwsrv_dropdownsearchattrib
Description Structure object containing column and text information for dropdown
DataWindows.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
dwc_object DataWindowChild
s_columnname String
s_editstyle String

See also n_cst_dwsrv_dropdownsearch

93
n_cst_dwsrv_multitableattrib

n_cst_dwsrv_multitableattrib
Description Structure object containing information used to control multitable updates.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
b_keyupdateinplace Boolean
i_whereoption Integer
s_keycolumns[ ] String
s_updatecolumns[ ] String
s_updatetable String

See also n_cst_dwsrv_multitable

94
 Chapter 5 Global Structures and Structure Objects

n_cst_dwsrv_querymodeattrib
Description Structure object storing querymode information for DataWindow columns.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
b_state Boolean
s_col String
s_protect String

See also n_cst_dwsrv_querymode

95
n_cst_dwsrv_resizeattrib

n_cst_dwsrv_resizeattrib
Description Structure object containing information about registered columns and text
objects.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
b_scale Boolean
b_movex Boolean
b_movey Boolean
b_scalewidth Boolean
b_scaleheight Boolean
i_movex Integer
i_movex Integer
i_scalewidth Integer
i_scaleheight Integer
r_x Real
r_y Real
r_width Real
r_height Real
s_control String
s_typeof String

See also n_cst_dwsrv_resize

96
 Chapter 5 Global Structures and Structure Objects

n_cst_errorattrib
Description Structure object containing information used in n_cst_error and w_message.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ib_print Boolean
ib_userinput Boolean
idt_date Datetime
ie_buttonstyle Button
ie_icon Icon
ii_buttonclicked Integer
ii_default Integer
ii_rc Integer
ii_severity Integer
ii_timeout Integer
is_text String
is_title String
is_user String
is_usertext String

See also n_cst_error

97
n_cst_filterattrib

n_cst_filterattrib
Description Structure object containing information used in n_cst_dwsrv_filter and Filter
dialog boxes.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
idw_dw u_dw
is_colnamedisplay[ ] String
is_columns[ ] String
is_dbnames[ ] String
is_filter String

See also n_cst_dwsrv_filter

98
 Chapter 5 Global Structures and Structure Objects

n_cst_findattrib
Description Structure object containing information used in n_cst_dwsrv_find, u_rte,
w_find, and w_replace.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ib_directionenabled Boolean
ib_directionvisible Boolean
ib_lookenabled Boolean
ib_lookvisible Boolean
ib_matchcase Boolean
ib_matchcaseenabled Boolean
ib_matchcasevisible Boolean
ib_wholeword Boolean
ib_wholewordenabled Boolean
ib_wholewordvisible Boolean
ii_lookindex Integer
ipo_requestor PowerObject
is_direction String
is_find String
is_lookdata[] String
is_lookdisplay[] String
is_replacewith String

See also n_cst_dwsrv_find

u_rte

99
n_cst_infoattrib

n_cst_infoattrib
Description Structure object containing information displayed by the DataWindow
Properties dialog box.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
is_description String
is_name String

See also All objects that contain an of_GetInfo function.

100
 Chapter 5 Global Structures and Structure Objects

n_cst_itemattrib
Description Structure object containing information used in u_lb, u_plb, and u_tv.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ii_index Integer
is_itemtext String

See also u_lb

u_plb
u_tvs

101
n_cst_linkageattrib

n_cst_linkageattrib
Description Structure object containing information used in n_cst_dwsrv_linkage.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
is_detailcolarg[ ] String
is_mastercolarg[ ] String

See also n_cst_dwsrv_linkage

102
 Chapter 5 Global Structures and Structure Objects

n_cst_logonattrib
Description Structure object containing information used in n_cst_appmanager.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ii_rc Integer
ipo_source PowerObject
is_appname String
is_logo String
is_password String
is_userid String

See also n_cst_appmanager

103
n_cst_lvsrvattrib

n_cst_lvsrvattrib
Description Structure object containing information used by ListView services.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ids_source n_ds
itr_obj n_tr
is_dataobject String
is_keycolumns[ ] String
is_labelcolumn String
is_method String
is_overlaycolumn String
is_picturecolumn String
is_statecolumn String
is_xposcolumn String
is_yposcolumn String

See also n_cst_lvsrv_datasource

104
 Chapter 5 Global Structures and Structure Objects

n_cst_mruattrib
Description Structure object containing information used by n_cst_mru.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ii_itemcount Integer
is_classname String
is_id String
is_menuitemkey String
is_menuitemmhelp String
is_menuitemname String

See also n_cst_mru

105
n_cst_propertyattrib

n_cst_propertyattrib
Description Structure object containing information used by the DataWindow Properties
dialog box.
Library PFCUTIL.PBL
PFEUTIL.PBL
Properties
Field Data type
ib_switchbuttons Boolean
is_description String
is_name String
is_propertypage[ ] String
is_propertytabtext String

See also All objects that contain an of_GetPropertyInfo function.

106
 Chapter 5 Global Structures and Structure Objects

n_cst_resizeattrib
Description Structure object containing information for tracking objects eligible for
resizing.
Library PFCWNSRV.PBL
PFEWNSRV.PBL
Properties
Field Data type
b_scale Boolean
b_movex Boolean
b_movey Boolean
b_scalewidth Boolean
b_scaleheight Boolean
wo_control GraphicObject
i_movex Integer
i_movex Integer
i_scalewidth Integer
i_scaleheight Integer
i_widthmin Integer
i_heightmin Integer
r_x Real
r_y Real
r_width Real
r_height Real
s_classname String
s_typeof String

See also n_cst_resize

107
n_cst_restorerowattrib

n_cst_restorerowattrib
Description Structure object containing information used by n_cst_dwsrv_rowmanager
when restoring deleted rows.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
idw_active DataWindow
is_filter String
is_sort String

See also n_cst_dwsrv_rowmanager

108
 Chapter 5 Global Structures and Structure Objects

n_cst_returnattrib
Description Structure object containing return code and associated text.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ii_rc Integer
is_rs String

See also n_cst_dwsrv_sort

109
n_cst_selectionattrib

n_cst_selectionattrib
Description Structure object containing information used in n_cst_selection and
w_selection.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ia_argument[20] Any
ia_returnval[ ] Any
ipo_data[ ] PowerObject
is_columnreturn[ ] String
is_dataobject String
is_title String
itr_object n_tr

See also n_cst_selection

110
 Chapter 5 Global Structures and Structure Objects

n_cst_sortattrib
Description Structure object containing information used in n_cst_dwsrv_sort and the Sort
dialog boxes.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
ib_usedisplay[ ] Boolean
is_colnamedisplay[ ] String
is_origcolumns[ ] String
is_origorder[ ] String
is_sort String
is_sortcolumns[ ] String

See also n_cst_dwsrv_sort

111
n_cst_splashattrib

n_cst_splashattrib
Description Structure object containing information used in n_cst_appmanager and
w_splash.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ii_secondsvisible Integer
is_application String
is_copyright String
is_logo String
is_version String

See also n_cst_appmanager

112
 Chapter 5 Global Structures and Structure Objects

n_cst_sqlattrib
Description Structure object containing information used in n_cst_sql.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
s_columns String
s_group String
s_having String
s_order String
s_tables String
s_values String
s_verb String
s_where String

See also n_cst_sql

113
n_cst_textstyleattrib

n_cst_textstyleattrib
Description Structure object used by u_rte-based RichTextEdit controls to access text style
information.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ib_bold Boolean
ib_italic Boolean
ib_strikeout Boolean
ib_subscript Boolean
ib_superscript Boolean
ib_underlined Boolean

See also u_rte

114
 Chapter 5 Global Structures and Structure Objects

n_cst_tmgregisterattrib
Description Structure object containing information used by n_cst_tmgmultiple.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ii_notifystyle Integer
il_notifyinterval Long
ipo_notify PowerObject
is_notifyevent String

See also n_cst_tmgmultiple

115
n_cst_toolbarattrib

n_cst_toolbarattrib
Description Structure object containing information used in w_frame and w_toolbars.
Library PFCWNSRV.PBL
PFEWNSRV.PBL
Properties
Field Data type
b_visible Boolean
ib_largebuttonsenabled Boolean
ib_positionenabled Boolean
ib_tooltipsenabled Boolean
ib_visibleenabled Boolean
i_barindex Integer
s_displayname String
s_title String
e_alignment ToolbarAlignment
iw_owner Window

See also w_frame

116
 Chapter 5 Global Structures and Structure Objects

n_cst_trregistration
Description Structure object for tracking the Transaction object.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
b_used Boolean
tr_object n_tr

See also n_cst_trregistration

117
n_cst_tvattrib

n_cst_tvattrib
Description Structure object containing information used by tree views.
Library PFCMAIN.PBL
PFEMAIN.PBL
Properties
Field Data type
b_recursive Boolean
i_pictureindex Integer
i_selectedpictureindex Integer
i_statepictureindex Integer
i_overlaypictureindex Integer
ds_obj n_ds
tr_obj n_tr
s_datawindow String
s_labelcolumn String
s_retrieveargs String
s_pictureindexcol String
s_selectedpictureindexcol String
s_statepictureindexcol String
s_overlaypictureindexcol String

See also n_cst_tvsrvattrib

118
 Chapter 5 Global Structures and Structure Objects

n_cst_tvsrvattrib
Description Structure object containing information used by n_cst_tvsrv_levelsource.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
ib_recursive Boolean
ii_deletestyle Integer
ids_obj n_ds
itr_obj n_tr
is_dataobject String
is_filtercols String
is_keycolumns String
is_labelcolumn String
is_method String
is_overlaycolumn String
is_picturecolumn String
is_retrieveargs String
is_selectedcolumn String
is_statecolumn String

See also n_cst_tvsrv_levelsource

119
n_cst_winsrv_sheetmanagerattrib

n_cst_winsrv_sheetmanagerattrib
Description Structure object containing information on the previous state of active sheets.
Library PFCWNSRV.PBL
PFEWNSRV.PBL
Properties
Field Data type
w_obj Window
e_state Windowstate
i_width Integer
i_height Integer
i_x Integer
i_y Integer

See also n_cst_winsrv_sheetmanager

120
 Chapter 5 Global Structures and Structure Objects

n_cst_winsrv_statusbarattrib
Description Structure object containing information on status bar items.
Library PFCWNSRV.PBL
PFEWNSRV.PBL
Properties
Field Data type
s_id String
s_type String
s_value String
i_width Integer
i_bordertype Integer
i_gapwidth Integer

See also n_cst_winsrv_statusbar

121
n_cst_zoomattrib

n_cst_zoomattrib
Description Structure object containing information used in n_cst_dwsrv_printpreview and
w_zoom.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
idw_obj DataWindow
ii_zoom Integer

See also n_cst_dwsrv_printpreview

122
 Chapter 5 Global Structures and Structure Objects

s_pagesetupattrib
Description Global structure containing information used in n_cst_platform and
w_pagesetup.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
b_disablemargins Boolean
b_disableorientation Boolean
b_disablepaper Boolean
i_minmarginleft Integer
i_minmarginright Integer
i_minmargintop Integer
i_minmarginbottom Integer
i_marginleft Integer
i_marginright Integer
i_margintop Integer
i_marginbottom Integer
i_papersize Integer
i_papersource Integer
b_portraitorientation Boolean
str_papersize[ ] s_paperattrib
str_papersource[ ] s_paperattrib
i_units Integer
b_actiontaken Boolean

See also n_cst_platform

123
s_paperattrib

s_paperattrib
Description Global structure containing information used in s_pagestupattrib.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
i_val Integer
s_type String

See also n_cst_platform

s_pagesetupattrib

124
 Chapter 5 Global Structures and Structure Objects

s_printdlgattrib
Description Structure object containing information used by n_cst_platform for printing.
Library PFCAPSRV.PBL
PFEAPSRV.PBL
Properties
Field Data type
b_allpages Boolean
b_pagenums Boolean
b_selection Boolean
b_disablepagenums Boolean
b_disableselection Boolean
b_collate Boolean
l_copies Long
b_printtofile Boolean
b_disableprinttofile Boolean
b_hideprinttofile Boolean
l_frompage Long
l_topage Long
l_minpage Long
l_maxpage Long

See also n_cst_platform

125
s_svalue

s_svalue
Description Global structure containing information used in n_cst_dwsrv_querymode.
Library PFCDWSRV.PBL
PFEDWSRV.PBL
Properties
Field Data type
s_value String

See also n_cst_platform

s_pagesetupattrib

126
CH A PTE R 6 Standard Visual User Objects

About this chapter This chapter describes the standard visual user objects in PFC.
Contents The standard visual user objects are listed in alphabetical order. Each
object’s discussion includes an alphabetical listing of instance variables,
events, and object functions.

127
u_cb

u_cb
Description Command button visual user object.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
CommandButton. U_cb event scripts provide integration with PFC menus.
See also m_master
w_master

Events
U_cb includes a precoded event script:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent window.

Functions
U_cb includes precoded object functions:
of_GetParentWindow
of_MessageBox

128
 Chapter 6 Standard Visual User Objects

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_cb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_cb GetFocus event calls this function.
Examples This example is from the u_cb GetFocus event:
Window lw_parent

//Check for MicroHelp requirements.

IF gnv_app.of_GetMicrohelp() THEN
//Notify the parent.
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_cb
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

129
u_cb

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in CommandButtons.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’cb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

130
 Chapter 6 Standard Visual User Objects

u_cbx
Description CheckBox visual user object.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
CheckBox. U_cbx event scripts provide integration with PFC menus.
See also m_master
w_master

Events
U_cbx includes a precoded event script:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_cbx includes precoded object functions:
of_GetParentWindow
of_MessageBox

131
u_cbx

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_cbx
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_cbx GetFocus event calls this function.
Examples This example is from the u_cbx GetFocus event:
Window lw_parent

//Check for MicroHelp requirements.

IF gnv_app.of_GetMicrohelp() THEN
//Notify the parent.
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_cbx
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

132
 Chapter 6 Standard Visual User Objects

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in CheckBoxes.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’cbx_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

133
u_ddlb

u_ddlb
Description DropDownListBox visual user object ancestor. This object provides:
• Integration with PFC menus for the cut, copy, paste, clear, and select all
Edit menu choices
• A function to display a popup Edit menu when the user points at the
DropDownListBox and right-clicks
• An event you can use to scroll to the matching letters in the list as the user
types
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
DropDownListBox. U_ddlb event scripts provide integration with PFC menus.
Additionally, u_ddlb supports:
• Cut, copy, paste, clear, and select all These are triggered
automatically by the message router.
• Popup menu support The ContextMenu event enables you to use the
right mouse button to perform editing actions. To disable right mouse
button support, set ib_rmbmenu to FALSE in the dropdown listbox’s
Constructor event.
• Autoselect This means that text is selected when a user tabs to the
dropdown listbox. To disable autoselect, set ib_autoselect to FALSE in the
dropdown listbox’s Constructor event.

134
 Chapter 6 Standard Visual User Objects

• Autoscroll This means that PFC scrolls to matching dropdown listbox

entries as you type. To enable autoscroll, set ib_search to TRUE in the
dropdown listbox’s Constructor event.
See also m_master
m_edit
u_ddplb

Instance variables
U_ddlb includes instance variables:
Instance
variable Description Data type Access Usage
ib_autoselect Indicates whether PFC selects text Boolean Protected Set this to TRUE to
automatically when the control enable autoselect
receives focus (default is FALSE)
ib_rmbmenu Indicates whether the m_edit menu Boolean Protected Set this to FALSE to
displays when the user presses the disable right mouse
right mouse button button support
(default is TRUE)
ib_search Controls whether PFC automatically Boolean Protected Set this to TRUE to
scrolls to matching entries as the user enable autoscroll
types (default is FALSE)

Events
U_ddlb includes precoded event scripts:
CbnEditChange pfc_Cut
ContextMenu pfc_Paste
GetFocus pfc_PreRmbMenu
pfc_Clear pfc_SelectAll
pfc_Copy RButtonUp

CbnEditChange
Description Scrolls the DropDownListBox, based on the typed characters. For example, if
you press r, the event scrolls to the first entry beginning with r; if you then press
i, the event scrolls to the first entry beginning with ri.

135
u_ddlb

This event maps to the pbm_cbneditchange event.

This capability differs from the default DropDownListBox behavior, which
scrolls based on the first letter only. For example, if you press r, the list scrolls
to the first entry beginning with r; if you then press i, the list scrolls to the first
entry beginning with i.
Usage To use this functionality, you must enable the Allow Edit property for the
DropDownListBox. To disable this functionality, set ib_search to FALSE.

ContextMenu
Description Displays the m_edit popup menu.
Usage This event executes when the user releases the right mouse button over a
control based on u_ddlb.

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

pfc_Clear
Description Deletes selected text.
Return value Integer. Returns the number of characters deleted if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a DropDownListBox based on
u_ddlb has focus and the user selects Edit>Clear.

pfc_Copy
Description Copies selected text to the clipboard.
Return value Integer. Returns the number of characters copied if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a DropDownListBox based on
u_ddlb has focus and the user selects Edit>Copy.
This event is also called by the m_edit popup menu.

136
 Chapter 6 Standard Visual User Objects

pfc_Cut
Description Deletes selected text and stores it on the clipboard.
Return value Integer. Returns the number of characters removed if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a DropDownListBox based on
u_ddlb has focus and the user selects Edit>Cut.
This event is also called by the m_edit popup menu.

pfc_Paste
Description Inserts (pastes) the contents of the clipboard at the insertion point.
Return value Integer. Returns the number of characters that were pasted if the event succeeds
and -1 if an error occurs.
Usage The message router calls this event when a DropDownListBox based on
u_ddlb has focus and the user selects Edit>Paste.
This event is also called by the m_edit popup menu.

pfc_PreRmbMenu
Description User event allowing you to modify m_edit contents before display.
Syntax instancename.Event pfc_PreRmbMenu ( editmenu )
Argument Description
instancename Instance name of u_ddlb
editmenu M_edit variable containing the popup menu to be displayed
(passed by reference)

Return value None

Usage Optionally add logic to this event to selectively enable and disable m_edit
menu items.

pfc_SelectAll
Description Selects all text in the DropDownListBox.
Return value Integer. Returns the number of characters selected if the event succeeds and -1
if an error occurs.

137
u_ddlb

Usage The message router calls this event when a DropDownListBox based on
u_ddlb has focus and the user selects Edit>Select All.
This event is also called by the m_edit popup menu.

RButtonUp
Description Empty user event. PFC code previously assigned to this event is now in the
ContextMenu event.
Usage This event executes when the user releases the right mouse button over a
control based on u_ddlb.

Functions
U_ddlb includes precoded object functions:
of_GetParentWindow
of_MessageBox

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_ddlb
window Window variable into which the function places a reference to
the parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_ddlb GetFocus event calls this function.
Examples This example is from the u_ddlb GetFocus event:
Window lw_parent

//Check for MicroHelp requirements.

IF gnv_app.of_GetMicrohelp() THEN
//Notify the parent.
of_GetParentWindow(lw_parent)

138
 Chapter 6 Standard Visual User Objects

IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_ddlb
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in
DropDownListBoxes.

139
u_ddlb

The id argument is not used in the default implementation.

Examples This example calls the of_MessageBox function:
of_Messagebox(’ddlb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

140
 Chapter 6 Standard Visual User Objects

u_ddplb
Description DropDownPictureListBox user object ancestor. This object provides:
• Integration with PFC menus for the cut, copy, paste, clear, and select all
Edit menu choices
• A function to display a popup Edit menu when the user points at the
DropDownPictureListBox and right-clicks
• An event you can use to scroll to the matching letters in the list as the user
types
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
DropDownPictureListBox. U_ddplb event scripts provide integration with
PFC menus. Additionally, u_ddplb supports:
• Cut, copy, paste, clear, and select all These are triggered
automatically by the message router.
• Popup menu support The ContextMenu event enables you to use the
right mouse button to perform editing actions. To disable right mouse
button support, set ib_rmbmenu to FALSE in the dropdown
picturelistbox’s Constructor event.
• Autoselect This means that text is selected when a user tabs to the
dropdown picturelistbox. To disable autoselect, set ib_autoselect to
FALSE in the dropdown picturelistbox’s Constructor event.

141
u_ddplb

• Autoscroll This means that PFC scrolls to matching dropdown

picturelistbox entries as you type. To enable autoscroll, set ib_search to
TRUE in the dropdown picturelistbox’s Constructor event.
See also m_edit
u_ddlb

Instance variables
U_ddplb includes instance variables:
Instance
variable Description Data type Access Usage
ib_autoselect Indicates whether PFC selects Boolean Protected Set this to TRUE to
text automatically when the enable autoselect (default
control receives focus is FALSE)
ib_rmbmenu Controls whether the m_edit Boolean Protected Set this to FALSE to
menu displays when the user disable right mouse
presses the right mouse button button support (default is
TRUE)
ib_search Controls whether PFC Boolean Protected Set this to TRUE to
automatically scrolls to matching enable autoscroll (default
entries as the user types is FALSE)

Events
U_ddplb includes precoded event scripts:
CbnEditChange pfc_Cut
ContextMenu pfc_Paste
GetFocus pfc_PreRmbMenu
pfc_Clear pfc_SelectAll
pfc_Copy RButtonUp

CbnEditChange
Description Scrolls the DropDownPictureListBox, based on the typed characters. For
example, if you press r, the event scrolls to the first entry beginning with r; if
you then press i, the event scrolls to the first entry beginning with ri.
This event maps to the pbm_cbneditchange event.

142
 Chapter 6 Standard Visual User Objects

This capability differs from the default DropDownPictureListBox behavior,

which scrolls based on the first letter only. For example, if you press r, the list
scrolls to the first entry beginning with r; if you then press i, the list scrolls to
the first entry beginning with i.
Usage To use this functionality, you must enable the Allow Edit property for the
DropDownPictureListBox. To disable this functionality, set ib_search to
FALSE.

ContextMenu
Description Displays the m_edit popup menu.
Usage This event executes when the user releases the right mouse button over a
control based on u_ddplb.

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

pfc_Clear
Description Deletes selected text.
Return value Integer. Returns the number of characters deleted if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a DropDownPictureListBox based on
u_ddplb has focus and the user selects Edit>Clear.

pfc_Copy
Description Copies selected text to the clipboard.
Return value Integer. Returns the number of characters copied if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a DropDownPictureListBox based on
u_ddplb has focus and the user selects Edit>Copy.
This event is also called by the m_edit popup menu.

143
u_ddplb

pfc_Cut
Description Deletes selected text and stores it on the clipboard.
Return value Integer. Returns the number of characters removed if the event succeeds and -
1 if an error occurs.
Usage The message router calls this event when a DropDownPictureListBox based on
u_ddplb has focus and the user selects Edit>Cut.
This event is also called by the m_edit popup menu.

pfc_Paste
Description Inserts (pastes) the contents of the clipboard at the insertion point.
Return value Integer. Returns the number of characters that were pasted if the event succeeds
and -1 if an error occurs.
Usage The message router calls this event when a DropDownPictureListBox based on
u_ddplb has focus and the user selects Edit>Paste.
This event is also called by the m_edit popup menu.

pfc_PreRmbMenu
Description User event allowing you to modify m_edit contents before display.
Syntax instancename.Event pfc_PreRmbMenu ( editmenu )
Argument Description
instancename Instance name of u_ddplb
editmenu M_edit variable containing the popup menu to be displayed
(passed by reference)

Return value None

Usage Optionally add logic to this event to selectively enable and disable m_edit
menu items.

pfc_SelectAll
Description Selects all text in the DropDownPictureListBox.
Return value Integer. Returns the number of characters selected if the event succeeds and -1
if an error occurs.

144
 Chapter 6 Standard Visual User Objects

Usage The message router calls this event when a DropDownPictureListBox based on
u_ddplb has focus and the user selects Edit>Select All.
This event is also called by the m_edit popup menu.

RButtonUp
Description Empty user event. PFC code previously assigned to this event is now in the
ContextMenu event.
Usage This event executes when the user releases the right mouse button over a
control based on u_ddplb.

Functions
U_ddplb includes precoded object functions:
of_GetParentWindow
of_MessageBox

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_ddplb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_ddplb GetFocus event calls this function.
Examples This example is from the u_ddplb GetFocus event:
Window lw_parent

//Check for MicroHelp requirements.

IF gnv_app.of_GetMicrohelp() THEN
//Notify the parent.
of_GetParentWindow(lw_parent)

145
u_ddplb

IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_ddplb
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in
DropDownPictureListBoxes.

146
 Chapter 6 Standard Visual User Objects

The id argument is not used in the default implementation.

Examples This example calls the of_MessageBox function:
of_Messagebox(’ddplb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

147
u_dw

u_dw
Description Ancestor for all DataWindow controls in applications written using PFC. This
DataWindow user object includes:
• Functions to enable and disable DataWindow services
• Events that automatically make use of enabled DataWindow services
• Precoded user events that provide basic editing functionality
• Template user events to which you can add application-specific
functionality
U_dw is a self-updating object.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships m_dw
n_cst_conversion
n_cst_dwpropertyattrib

148
 Chapter 6 Standard Visual User Objects

n_cst_findattrib
n_cst_platform
n_cst_restorerowattrib
n_cst_string
s_pagesetupattrib
s_printdlgattrib
Although u_dw contains substantial standalone functionality, the DataWindow
services user objects (those objects whose name starts with n_cst_dwsrv) must
be available to get the most out of it.
Usage To use u_dw:
1 Place a u_dw user object in your window.
2 In the window Open event (or some other appropriate place), enable
DataWindow services as needed by your application.
3 Extend basic u_dw functionality by adding PowerScript code to events
and user events.
4 Add application-specific functionality as needed.
See also n_cst_dwsrv
n_cst_dwsrv_dropdownsearch
n_cst_dwsrv_filter
n_cst_dwsrv_find
n_cst_dwsrv_linkage
n_cst_dwsrv_multitable
n_cst_dwsrv_printpreview
n_cst_dwsrv_property
n_cst_dwsrv_querymode
n_cst_dwsrv_report
n_cst_dwsrv_reqcolumn
n_cst_dwsrv_resize
n_cst_dwsrv_rowmanager
n_cst_dwsrv_rowselection
n_cst_dwsrv_sort
u_calculator
u_calendar

Instance variables
U_dw contains instance variables and one shared variable:

149
u_dw

Instance variable Description Data type Access Usage

CONTINUE_ACTION Constant set to 1 Integer Public Internal
FAILURE Constant set to -1 Integer Public Internal
ib_isupdateable Indicates whether Boolean Protected Access through the
the DataWindow can of_GetUpdateable and
be updated of_SetUpdateable
functions. Default is
TRUE
ib_rmbfocuschange Used to track focus Boolean Protected Internal
change while the
right mouse button is
down
ib_rmbmenu Controls whether the Boolean Protected Set FALSE in the
m_dw menu displays DataWindow’s
when the user Constructor event to
presses the right disable right mouse
mouse button over button support
the DataWindow
control
inv_base Reference variable n_cst_dwsrv Public Use in dot notation to
for basic access n_cst_dwsrv
DataWindow functions and attributes
services
inv_dropdownsearch Reference variable n_cst_dwsrv_ Public Use in dot notation to
for the dropdown dropdownsearch access dropdown
DataWindow search DataWindow search
service functions and attributes
inv_filter Reference variable n_cst_dwsrv_filter Public Use in dot notation to
for the DataWindow access DataWindow
filter service filter service functions
and attributes
inv_find Reference variable n_cst_dwsrv_find Public Use in dot notation to
for the DataWindow access DataWindow
find service find service functions
and attributes
inv_linkage Reference variable n_cst_dwsrv_linkage Public Use in dot notation to
for the DataWindow access
linkage service n_cst_dwsrv_linkage
functions and attributes
inv_multitable Reference variable n_cst_dwsrv_ Public Use in dot notation to
for the DataWindow multitable access n_cst_dwsrv_
multitable update multitable functions
service and attributes

150
 Chapter 6 Standard Visual User Objects

Instance variable Description Data type Access Usage

inv_printpreview Reference variable n_cst_dwsrv_ Public Use in dot notation to
for the DataWindow printpreview access n_cst_dwsrv_
print preview service printpreview functions
and attributes
inv_property Reference variable n_cst_dwsrv_property Public Internal
for the DataWindow
property service
inv_querymode Reference variable n_cst_dwsrv_ Public Use in dot notation to
for the query mode querymode access n_cst_dwsrv_
service querymode functions
and attributes
inv_report Reference variable n_cst_dwsrv_report Public Use in dot notation to
for the reporting access
service n_cst_dwsrv_report
functions and attributes
inv_reqcolumn Reference variable n_cst_dwsrv_ Public Use in dot notation to
for the required reqcolumn access n_cst_dwsrv_
column service reqcolumn functions
and attributes
inv_resize Reference variable n_cst_dwsrv_resize Public Use in dot notation to
for the resize service access
n_cst_dwsrv_resize
functions and attributes
inv_rowmanager Reference variable n_cst_dwsrv_ Public Use in dot notation to
for the row manager rowmanager access n_cst_dwsrv_
service rowmanager functions
and attributes
inv_rowselect Reference variable n_cst_dwsrv_ Public Use in dot notation to
for the row selection rowselection access n_cst_dwsrv_
service rowselection functions
and attributes
inv_sort Reference variable n_cst_dwsrv_sort Public Use in dot notation to
for the sort service access
n_cst_dwsrv_sort
functions and attributes
is_updatesallowed Specifies allowable String Protected Internal
update types

151
u_dw

Instance variable Description Data type Access Usage

itr_object Transaction object n_tr Public DataWindow services
used by the use this instance
DataWindow variable to track the
transaction object
Set with
of_SetTransObject
iuo_calculator Reference variable u_calculator Public Use in dot notation to
for dropdown access u_calculator
calculator events, functions, and
attributes
iuo_calendar Reference variable u_calendar Public Use in dot notation to
for dropdown access u_calendar
calendar events, functions, and
attributes
NO_ACTION Constant set to 0 Integer Public Internal
PREVENT_ACTION Constant set to 0 Integer Public Internal
snv_property Shared reference n_cst_dwsrv_property Public Internal
variable for the
DataWindow
property service
SUCCESS Constant set to 1 Integer Public Internal

Events
U_dw contains two types of events/user events:
• Precoded events and user events that PFC uses to provide functionality
• Template user events to which you optionally add PowerScript code to
take advantage of DataWindow services
Clicked pfc_PrePrintDlg
DBError pfc_PreProperties
Destructor pfc_PreReplaceDlg
Dropdown pfc_PreRestoreRow
GetFocus pfc_PreRmbMenu
ItemChanged pfc_PreUpdate
ItemError pfc_PreviousPage
ItemFocusChanged pfc_Print
LButtonDown pfc_PrintDlg

152
 Chapter 6 Standard Visual User Objects

LButtonUp pfc_PrintImmediate
pfc_AcceptText pfc_PrintPreview
pfc_AddRow pfc_Properties
pfc_Clear pfc_ReplaceDlg
pfc_Copy pfc_ResetUpdate
pfc_Cut pfc_RestoreRow
pfc_DDCalculator pfc_Retrieve
pfc_DDCalendar pfc_RetrieveDDDW
pfc_Debug pfc_RowChanged
pfc_DeleteRow pfc_RowValidation
pfc_Descendant pfc_Ruler
pfc_FilterDlg pfc_SelectAll
pfc_FindDlg pfc_SortDlg
pfc_FirstPage pfc_Undo
pfc_InsertRow pfc_Update
pfc_LastPage pfc_UpdatePrep
pfc_NextPage pfc_UpdatesPending
pfc_Operators pfc_Validation
pfc_PageSetup pfc_Values
pfc_PageSetupDlg pfc_Zoom
pfc_Paste RButtonDown
pfc_PopulateDDDW RButtonUp
pfc_PostInsertRow Resize
pfc_PostUpdate RetrieveEnd
pfc_PreDeleteRow RetrieveStart
pfc_PreFindDlg RowFocusChanged
pfc_PreInsertRow SQLPreview
pfc_PrePageSetupDlg

Clicked
Description Notifies DataWindow selection service, linkage service, and sort service
functions, if enabled.
Usage This event executes when the user clicks in the DataWindow. The functions
called in the Clicked event automatically handle row selection and sorting, if
enabled.
For the selection service, you may need to add logic in other places to access
selected rows and perform application specific processing.

153
u_dw

DBError
Description Displays a message box informing the user that a database error occurred.
Usage This event is called when there is a database error.

Destructor
Description Destroys all existing DataWindow service objects.
Usage This event executes when the DataWindow closes.

Dropdown
Description Indicates whether the current dropdown object is associated with u_calculator
or u_calendar.
Usage This event executes when a DropDownListBox or DropDownDataWindow
begins the dropdown process.

GetFocus
Description Notifies the parent window so it can track the current control.
Usage This event executes when the DataWindow control gets focus. It triggers the
pfc_ControlGotFocus event in the parent.

ItemChanged
Description Notifies the linkage service that an item has changed.
Usage This event executes when a field in the DataWindow control has been modified
and loses focus.

ItemError
Description When an error occurs, calls the required column service, if enabled, to set the
ActionCode to 3, causing the DataWindow to accept the value.
Usage Use this event to add application-specific error-handling functionality.

154
 Chapter 6 Standard Visual User Objects

ItemFocusChanged
Description Notifies the linkage service that item focus has changed, Also, if MicroHelp is
enabled for the application, this event calls the pfc_Microhelp event on the
parent.
Usage This event executes when the user moves to a different item within a
DataWindow. It displays MicroHelp using text defined in the DataWindow
column’s tag value. The column’s tag value must specify
MICROHELP=microhelptext.
You enable MicroHelp display through the n_cst_appmanager
of_SetMicrohelp function.
If you are using the dropdown DataWindow search service
(n_cst_dwsrv_dropdownsearch), add code to this event that calls the
n_cst_dwsrv_dropdownsearch pfc_ItemFocusChanged event.
Examples This example shows the code you add to call the n_cst_dropdownsearch
pfc_ItemFocusChanged event:
inv_dropdownsearch.Event pfc_ItemFocusChanged &
(row, dwo)

LButtonDown
Description Calls the row selection service’s pfc_LButtonDown event.
Usage This event executes when the user presses the left mouse button over a
DataWindow.

LButtonUp
Description Calls the row selection service’s pfc_LButtonUp event.
Usage This event executes when the user releases the left mouse button over a
DataWindow.

pfc_AcceptText
Description Accepts text for the DataWindow control, optionally setting focus if an error
occurs.
Syntax instancename.Event pfc_AcceptText ( focusonerror )
Argument Description
instancename Instance name of u_dw

155
u_dw

Argument Description
focusonerror Boolean indicating whether focus should be set if an error occurs.
This argument is accessed through the ab_focusonerror argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the w_master event, as part of its default save process.

pfc_AddRow
Description Calls the row manager service to add a row at the end of the DataWindow. Also
notifies the linkage service, if enabled.
Return value Long. Returns the number of the new row if the event succeeds and -1 if an
error occurs.
Usage This event also calls the pfc_PreInsertRow and pfcPostInsertRow events.

pfc_Clear
Description Deletes selected text.
Return value Integer. Returns the number of characters deleted if the event succeeds and -1
if an error occurs.
Usage This event is triggered when the DataWindow has focus and the user selects
Edit>Clear from the menu bar of a menu descended from the PFC m_master
menu.

pfc_Copy
Description Copies selected text to the clipboard.
Return value Integer. Returns the number of characters copied if the event succeeds and -1
if an error occurs.
Usage This event is triggered when the DataWindow has focus and the user selects
Edit>Copy from the menu bar of a menu descended from the PFC m_master
menu. It is also triggered by the m_edit.m_copy clicked event.

pfc_Cut
Description Deletes selected text and stored it on the clipboard.
Return value Integer. Returns the number of characters removed if the event succeeds and -1
if an error occurs.

156
 Chapter 6 Standard Visual User Objects

Usage This event is triggered when the DataWindow has focus and the user selects
Edit>Cut from the menu bar of a menu descended from the PFC m_master
menu. It is also triggered by the m_edit.m_cut clicked event.

pfc_DDCalculator
Description Displays the dropdown calculator if the current column has been registered and
uses a numeric data type.
Return value Integer. Returns 1 if the function succeeds, 0 if the current DataWindow
column has not been registered, and -1 if an error occurs.
Usage Call this event to display the dropdown calculator programmatically. If the
current DataWindow column has been registered and uses a numeric data type,
the dropdown calculator displays.
The Dropdown event displays the dropdown calculator automatically for
registered columns.
Examples This example calls the pfc_DDCalculator event:
Integer li_return

li_return = dw_1.Event pfc_DDCalculator( )

...

pfc_DDCalendar
Description Displays the dropdown calendar if the current column has been registered and
uses a Date data type.
Return value Integer. Returns 1 if the function succeeds, 0 if the current DataWindow
column has not been registered, and -1 if an error occurs.
Usage Call this event to display the dropdown calendar programmatically. If the
current DataWindow column has been registered and uses a Date data type, the
dropdown calendar displays.
The Dropdown event displays the dropdown calendar automatically for
registered columns.
Examples This example calls the pfc_DDCalendar event:
Integer li_return

li_return = dw_1.Event pfc_DDCalendar()

...

157
u_dw

pfc_Debug
Description Calls the pfc_Properties event, which opens the DataWindow Properties
window, using either the inv_properties instance variable or the snv_properties
shared variable.
Usage This event is called when the user selects DataWindow Properties from the
m_dw popup menu.

pfc_DeleteRow
Description Deletes either the current row or, if the row manager service is enabled, all
selected rows. If the linkage service is enabled, this event calls that service’s
pfc_DeleteRow event.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Call this event to delete one or more rows.

pfc_Descendant
Description PFC events and functions may trigger this event to determine if the
DataWindow control is inherited from u_dw.
Return value Boolean. Always returns TRUE.
Usage Internal.

pfc_FilterDlg
Description Displays a filter dialog box by calling the n_cst_dwsrv_filter service’s
pfc_FilterDlg event.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called when the user selects View>Filter from the menu bar of a
menu descended from the PFC m_master menu.

pfc_FindDlg
Description Displays a find dialog box by calling the n_cst_dwsrv_find service’s
pfc_FindDlg event.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called when the user selects Edit>Find from the menu bar of a
menu descended from the PFC m_master menu.

158
 Chapter 6 Standard Visual User Objects

pfc_FirstPage
Description Scrolls to the first page of the DataWindow.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Call this event to scroll the DataWindow to the first page.

pfc_InsertRow
Description Inserts a row just before the current row and calls the n_cst_dwsrv_linkage
pfc_InsertRow event. It calls the pfc_PostInsertRow event for post-insert
functionality.
Return value Integer. Returns the number of the inserted row if the event succeeds and -1 if
an error occurs.
Usage Call this event to insert a row.

pfc_LastPage
Description Scrolls to the last page of the DataWindow.
Return value Long. Returns the row number displayed at the top of the last page if the event
succeeds and -1 if an error occurs.
Usage Call this event to scroll the DataWindow to the last page.

pfc_NextPage
Description Scrolls to the next page of the DataWindow.
Return value Long. Returns the row number at the top of the page if the event succeeds and
-1 if an error occurs.
Usage Call this event to scroll the DataWindow to the next page.

pfc_Operators
Description Calls the n_cst_dwsrv_querymode pfc_Operators event, which displays a
w_selection dialog box containing operators.
Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.
Usage This event is called by the m_dw popup menu.

159
u_dw

pfc_PageSetup
Description Calls the pfc_PageSetupDlg event to display the Page Setup dialog box.
Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.
Usage This event is called when the user selects File>Page Setup from the menu bar
of a menu descended from the PFC m_master menu.

pfc_PageSetupDlg
Description Displays the Page Setup dialog box by calling the n_cst_platform
of_PageSetupDlg function, passing the DataWindow’s page display properties.
Syntax instancename.Event pfc_PageSetupDlg ( attributes )
Argument Description
instancename Instance name of u_dw
attributes S_pagesetupattrib variable into which the event places page setup
information. This argument is accessed through the astr_pagesetup
argument (passed by reference)

Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.
Usage This event is called by the pfc_PageSetup event.

pfc_Paste
Description Inserts (pastes) the contents of the clipboard at the insertion point.
Return value Integer. Returns the number of characters that were pasted if the event succeeds
and -1 if an error occurs.
Usage This event is triggered when the DataWindow has focus and the user selects
Edit>Paste from the menu bar of a menu descended from the PFC m_master
menu. It is also triggered by the m_edit.m_paste Clicked event.

pfc_PopulateDDDW
Description Empty user event that you extend to populate the specified
DropDownDataWindow.
Syntax instancename.Event pfc_PopulateDDDW ( column, dddw )

160
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_dw
column String specifying the column containing the dropdown
DataWindow for which rows are retrieved. Access this value
through the as_colname argument
dddw DataWindowChild instance referencing the
DropDownDataWindow column. This argument is accessed
through the adwc_obj argument (passed by reference)

Return value Long. Returns the number of rows populated if the event succeeds and -1 if an
error occurs.
Usage The code you add to this event can populate the DropDownDataWindow in any
manner, including database retrieval, DataWindow caching, and retrieving
from a file.
Examples This example shows code you might add to the pfc_PopulateDDDW event:
IF adwc_obj.SetTransObject(SQLCA) = -1 THEN
Return -1
ELSE
Return adwc_obj.Retrieve()
END IF

pfc_PostInsertRow
Description Empty user event allowing you to perform post-insert processing.
Syntax instancename.Event pfc_PostInsertRow ( row )
Argument Description
instancename Instance name of u_dw
row Number of row added or inserted

Usage This event is posted from the pfc_AddRow and pfc_InsertRow events.

pfc_PostUpdate
Description Clears the DataWindow update flags.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage You can extend this event to code additional post-update processing.
Examples This example is from the of_PostUpdate function:
...

161
u_dw

If IsValid(inv_linkage) Then
li_rc = inv_linkage.of_PostUpdate()
Else
li_rc = this.Event pfc_postupdate()
End If
...

pfc_PreDeleteRow
Description Calls the n_cst_dwsrv_linkage pfc_PreDeleteRow event to allow for linkage
processing. This may include database updates as well as the prevention of
deletion processing.
Syntax instancename.Event pfc_PreDeleteRow ( )
Argument Description
instancename Instance name of u_dw

Return value Return 1 to continue deletion, 0 to prevent deletion, and -1 if an error occurs.
Usage You can extend this event to perform additional predelete processing.

pfc_PreFindDlg
Description Empty user event allowing you to modify the properties passed to the
pfc_FindDlg event.
Syntax instancename.Event pfc_PreFindDlg ( attributes )
Argument Description
instancename Instance name of u_dw
attributes N_cst_findattrib variable into which the event places additional
information. This argument is accessed through the anv_findattrib
argument (passed by reference)

Usage Use this event to modify or extend the information passed in the
n_cst_findattrib object.

pfc_PreInsertRow
Description Calls the n_cst_dwsrv_linkage pfc_PreInsertRow event to allow for linkage
processing. This may include prevention of insert processing.
Syntax instancename.Event pfc_PreInsertRow ( )

162
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_dw

Return value Return 1 to continue insertion, 0 to prevent insertion, and -1 if an error occurs.
Usage You can extend this event to perform additional preinsert processing.

pfc_PrePageSetupDlg
Description Empty user event allowing you to modify the properties passed to the
n_cst_platform of_PageSetupDlg function.
Syntax instancename.Event pfc_PrePageSetupDlg ( attributes )
Argument Description
instancename Instance name of u_dw
attributes S_pagesetupattrib variable into which the event places additional
page setup information. This argument is accessed through the
astr_pagesetup argument (passed by reference)

Usage This event is called by the pfc_PageSetupDlg event before calling the
n_cst_platform of_PageSetupDlg function.
You can use this event to modify or extend the information passed in the
s_pagesettupattrib structure.
Examples This example contains code you might add to the pfc_PrePageSetupDlg event:
// Sets page setup to portrait
astr_pagesetup.b_portraitorientation = TRUE

pfc_PrePrintDlg
Description Empty user event allowing you to modify the properties passed to the
n_cst_platform of_PrintDlg function.
Syntax instancename.Event pfc_PrePrintDlg ( attributes )
Argument Description
instancename Instance name of u_dw
attributes S_printdlgattrib variable into which the event places additional
printing information. This argument is accessed through the
astr_printdlg argument (passed by reference)

Return value None

163
u_dw

Usage This event is called by pfc_PrintDlg before calling the n_cst_platform

of_PrintDlg function.
You can use this event to modify or extend the information passed in the
s_printdlgattrib structure.
Examples This example contains code you might add to the pfc_PrePrintDlg event:
// Default copies to 1
astr_printdlg.l_copies = 1

pfc_PreProperties
Description Empty user event allowing you to modify the properties passed to the
DataWindow Properties dialog box.
Syntax instancename.Event pfc_PreProperties ( attributes )
Argument Description
instancename Instance name of u_dw
attributes N_cst_dwpropertyattrib variable into which the event places
additional information. This argument is accessed through the
anv_dwpropertyattrib argument (passed by reference)

Usage This event is called by the pfc_Debug event before calling the n_cst_property
of_OpenProperty function.
You can use this event to modify or extend the information passed in the
n_cst_propertyattrib object.

pfc_PreReplaceDlg
Description Empty user event allowing you to modify the properties passed to the
pfc_ReplaceDlg event.
Syntax instancename.Event pfc_PreReplaceDlg ( attributes )
Argument Description
instancename Instance name of u_dw
attributes N_cst_findattrib variable into which the event places additional
information. This argument is accessed through the anv_findattrib
argument (passed by reference)

Usage Use this event to modify or extend the information passed in the
n_cst_findattrib object.

164
 Chapter 6 Standard Visual User Objects

pfc_PreRestoreRow
Description Prepares the w_restorerow dialog box for display.
Syntax instancename.Event pfc_PreRestoreRow ( attributes )
Argument Description
instancename Instance name of u_dw
attributes N_cst_restorerowattrib variable into which the event places
additional information. This argument is accessed through the
anv_restorerowattrib argument (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The n_cst_rowmanager of_UnDelete function calls this event before opening
the w_restorerow window. It adds filter and sort information to the
n_cst_restorerowattrib structure.
You can extend this event to modify the information passed to the
w_restorerow window.
Examples This example is from the n_cst_dwsrv_rowmanager of_UnDelete function:
n_cst_restorerowattrib lnv_restorerowattrib

lnv_restorerowattrib.idw_active = idw_requestor
idw_requestor.Event pfc_PreRestoreRow &
(lnv_restorerowattrib)
OpenWithParm(w_restorerow, lnv_restorerowattrib)
...

pfc_PreRmbMenu
Description Empty user event allowing you to modify m_dw contents before display.
Syntax instancename.Event pfc_PreRmbMenu ( editmenu )
Argument Description
instancename Instance name of u_dw
editmenu M_dw variable containing the popup menu to be displayed. This
argument, which is accessed through the am_dw argument, is
passed by reference

Usage Optionally add logic to this event to selectively enable and disable m_edit
menu items.
Examples This example contains code you might add to the pfc_PreRmbMenu event:
// Always disable delete

165
u_dw

am_dw.m_table.m_delete.Enabled = FALSE

pfc_PreUpdate
Description Empty user event called by pfc_Update before updating rows.
Syntax instancename.Event pfc_PreUpdate ( )
Argument Description
instancename Instance name of u_dw

Return value Return 1 if the event succeeds and -1 to terminate update processing.
Usage Extend this event to add site-specific preupdate processing.
Examples This example contains code you might add to the pfc_PreUpdate event:
// Sets page setup to portrait
astr_pagesetup.b_portraitorientation = TRUE

pfc_PreviousPage
Description Scrolls to the previous page of the DataWindow.
Return value Long. Returns the row number at the top of the page if the event succeeds and
-1 if an error occurs.
Usage Call this event to scroll the DataWindow to the previous page.

pfc_Print
Description Calls the pfc_PrintDlg function and prints the DataWindow, as specified in the
Print dialog box.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is triggered when the DataWindow has focus and the user selects
File>Print from the menu bar of a menu descended from the PFC m_master
menu.

pfc_PrintDlg
Description Initializes the s_printdlgattrib structure with the DataWindow’s current
settings, displays the Print dialog box by calling the n_cst_platform
of_PrintDlg function, and resets the DataWindow’s settings, as specified by the
user.

166
 Chapter 6 Standard Visual User Objects

Syntax instancename.Event pfc_PrintDlg ( attributes )

Argument Description
instancename Instance name of u_dw
attributes S_printdlgattrib variable into which the event places printing
information. This argument, which is accessed through the
astr_printdlg argument, is passed by reference

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the pfc_Print event.

pfc_PrintImmediate
Description Prints the current DataWindow without displaying the Print dialog box.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called when the DataWindow has focus and the user selects
File>Print Immediate from the menu bar of a menu descended from the PFC
m_master menu.

Hiding Print Immediate

Consider hiding the Print Immediate menu item but enabling its toolbar button.
This provides functionality equivalent to many current software packages.

pfc_PrintPreview
Description Toggles the DataWindow between preview and edit modes.
Return value Boolean. Returns TRUE if the DataWindow is placed in preview mode and
FALSE if the DataWindow is placed in edit mode.
Usage To use this event, you must enable the print preview service by calling the
of_SetPrintPreview function.
This event is called when the DataWindow has focus and the user selects
File>Print Preview from a menu that descends from the PFC m_master menu.

pfc_Properties
Description Displays the DataWindow properties window.
Return value None.

167
u_dw

Usage To use this event, you must enable the DataWindow property service by calling
either of_SetProperty or of_SetSharedProperty.
This event is called when the user selects Properties from the m_dw popup
menu.

pfc_ReplaceDlg
Description Displays a Replace dialog box by calling the n_cst_dwsrv_find service’s
pfc_ReplaceDlg event.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called when the user selects View>Replace from the menu bar of
a menu descended from the PFC m_master menu.

pfc_ResetUpdate
Description Clears the DataWindow’s update flags.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called as part of the default pfc_Save process.

pfc_RestoreRow
Description Calls the row manager pfc_RestoreRow event, which displays the
w_restorerow dialog box.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the m_dw popup menu.

pfc_Retrieve
Description Empty user event to contain all database retrieve logic. PFC calls this event for
all database retrieves.
Return value Long. Returns the result of the Retrieve function.
Usage Add code to this event to retrieve rows for the DataWindow.
This event is called by the u_dw of_Retrieve function and by the
n_cst_dwsrv_linkage of_Retrieve function.
Examples This example shows the code you add to this event:
Return this.Retrieve()

168
 Chapter 6 Standard Visual User Objects

pfc_RetrieveDDDW
Description Obsolete. Use pfc_PopulateDDDW instead.
Syntax instancename.Event pfc_RetrieveDDDW ( column )
Argument Description
instancename Instance name of u_dw
column String specifying the column containing the dropdown
DataWindow for which rows are retrieved. Access this value
through the as_column argument

Return value Long. Returns the result of the Retrieve function.

pfc_RowChanged
Description Calls the linkage service’s pfc_RowFocusChanged function.
Usage This event is called whenever the DataWindow buffer has been sorted, filtered,
or otherwise modified such that the current row has not changed but the actual
row at that location is different.

pfc_RowValidation
Description Empty user event that you extend to perform site-specific row validation.
Syntax instancename.Event pfc_RowValidation ( row )
Argument Description
instancename Instance name of u_dw
row Long specifying the row to validate. Access this value through the
al_row argument

Return value Integer. Returns 1 if validation succeeds and -1 if an error occurs.

Usage Extend this event to perform additional row validation.
The n_cst_dwsrv_linkage of_Save function calls this event.

pfc_Ruler
Description Toggles the DataWindow between displaying and hiding rulers in print
preview mode.
Return value Boolean. Returns TRUE if print preview rulers are displayed and FALSE if
they are hidden.

169
u_dw

Usage To use this event, you must enable the print preview service by calling the
of_SetPrintPreview function.
This event is called when the DataWindow has focus and the user selects
View>Ruler from the menu bar of a menu descended from the PFC m_master
menu.

pfc_SelectAll
Description Selects all text in the current DataWindow cell.
Return value Integer. Returns the number of characters selected if the event succeeds and -1
if an error occurs.
Usage This event is triggered when the DataWindow has focus and the user selects
Edit>Select All from the menu bar of a menu descended from the PFC
m_master menu.

pfc_SortDlg
Description Displays a sort dialog box by calling the n_cst_dwsrv_sort service’s
pfc_SortDlg event.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called when the user selects View>Sort from the menu bar of a
menu descended from the PFC m_master menu.

pfc_Undo
Description Cancels the last edit to the DataWindow.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs or there is
nothing to undo.
Usage This event is triggered when the DataWindow has focus and the user selects
Edit>Undo from the menu bar of a menu descended from the PFC m_master
menu.

pfc_Update
Description Updates the DataWindow. If the multitable update service is enabled, this event
updates all specified tables.
Syntax instancename.Event pfc_Update ( accepttext, resetflags )

170
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_dw
accepttext Boolean specifying whether the DataWindow control should
automatically perform an AcceptText before performing the update
(TRUE) or not (FALSE)
resetflags Boolean specifying whether the DataWindow control should
automatically reset the update flags (TRUE) or not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage This event calls the pfc_PreUpdate event before updating rows.

pfc_UpdatePrep
Description Empty user event to which you can add code that prepares for update.
Return value Long. Return 1 if the update preparation succeeds and -1 to halt the update
process.
Usage The of_UpdatePrep function calls this function.

pfc_UpdatesPending
Description Determines if there are pending updates for the DataWindow.
Return value Integer. Returns 1 if there are pending updates for the DataWindow and 0 if
there are no pending updates.
Usage This event is called by the of_UpdatesPending function and by the
n_cst_dwsrv_linkage of_GetUpdatesPending function.

pfc_Validation
Description Checks for required fields.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the of_Validation function. You can extend this event to
perform additional validation.

pfc_Values
Description Calls the n_cst_dwsrv_querymode pfc_Values event, which displays a
w_selection dialog box containing a list of values.

171
u_dw

Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.
Usage This event is called by the m_dw popup menu.

pfc_Zoom
Description Displays the w_zoom dialog box, allowing the user to control DataWindow
display while in print preview mode.
Return value Integer. Returns the zoom level chosen by the user if the event succeeds, 0 if
the user cancels out of the w_zoom dialog box, and -1 if an error occurs.
Usage To use this event, you must enable the print preview service by calling the
of_SetPrintPreview function.
This event is called when the DataWindow has focus and the user selects
View>Zoom from the menu bar of a menu descended from the PFC m_master
menu.

RButtonDown
Description Calls the linkage service and row selection service’s pfc_RButtonDown event.
Usage This event executes when the user presses the right mouse button over a
DataWindow. The n_cst_dwsrv_linkage pfc_RButtonDown event can cancel
right-click processing.

RButtonUp
Description Displays the m_dw popup menu.
Usage This event executes when the user releases the right mouse button over the
DataWindow control.

Resize
Description Calls the DataWindow resize service’s pfc_Resize event, if the service is
enabled.
Usage This event executes when the DataWindow control resizes, either because it is
itself resizable or because it is registered as resizable with the window resize
service.

172
 Chapter 6 Standard Visual User Objects

RetrieveEnd
Description Calls the linkage service’s pfc_RetrieveEnd event, if the service is enabled.
Usage This event executes when a retrieval process completes.

RetrieveStart
Description Calls the linkage service’s pfc_RetrieveStart event, if the service is enabled.
Usage This event executes when a retrieval process begins.

RowFocusChanged
Description Used by the linkage service, if enabled, to coordinate scrolling among the
linkage chain.
Usage This event executes when the DataWindow first displays and again when the
user changes rows.
This event calls the n_cst_dwsrv_linkage pfc_RowFocusChanged event.

SQLPreview
Description Calls SQL Spy functions, if enabled for the application.
Usage This event executes just before accessing the database.

Functions
U_dw includes precoded object functions to control DataWindow services:
of_AcceptText of_SetMultiTable
of_CheckRequired of_SetPrintPreview
of_GetParentWindow of_SetProperty
of_GetUpdateable of_SetQuerymode
of_IsRoot of_SetReport
of_IsSharedProperty of_SetReqColumn
of_IsUpdateable of_SetResize
of_MessageBox of_SetRowManager
of_PostUpdate of_SetRowSelect
of_Reset of_SetSharedProperty
of_Retrieve of_SetSort

173
u_dw

of_SetBase of_SetTransObject
of_SetDropDownCalculator of_SetUpdateable
of_SetDropDownCalendar of_SetUpdateRequestor
of_SetDropDownSearch of_Update
of_SetFilter of_UpdatePrep
of_SetFind of_UpdatesPending
of_SetLinkage of_Validation

of_AcceptText
Description Performs an AcceptText function for the DataWindow.
Access Public
Syntax instancename.of_AcceptText ( focusonerror )
Argument Description
instancename Instance name of u_dw
focusonerror Boolean indicating whether PFC sets focus to the DataWindow
when an error occurs (TRUE) or not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize accept text processing,
extend the pfc_AcceptText event.
Examples This example is from the n_cst_luw of_AcceptText function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_AcceptText &
(ab_focusonerror)
If li_rc < 0 Then Return -1

...

of_CheckRequired
Description Determines if any required columns contain NULL values.
Access Public
Syntax instancename.of_CheckRequired ( buffer, row, column, colname,
updateonly )

174
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_dw
buffer DWBuffer enumerated data type specifying the DataWindow buffer
to check
row Long specifying the first row to check and into which the function
places the number of the row in error (passed by reference)
column Integer specifying the first column to check and into which the
function places the number of the column in error (passed by
reference)
colname String specifying the first column to check and into which the
function places the name of the column in error (passed by
reference)
updateonly Boolean indicating whether to validate only those rows and
columns that have changed (TRUE) or validate all rows and
columns

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
Usage The u_dw pfc_Validation event calls this function.
Examples This example is from the u_dw pfc_Validation event:
...
li_rc = &
of_CheckRequired(Primary!, ll_checkrow, &
li_checkcolumn, ls_checkcolname, &
ib_updateonly)
...

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_dw
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
Usage The u_dw GetFocus event calls this function.
Examples This example is from the u_dw GetFocus event:

175
u_dw

...
of_GetParentWindow(lw_parent)
If IsValid(lw_parent) Then
...

of_GetUpdateable
Description Obsolete. Call of_IsUpdateable instead.
Access Public
Syntax instancename.of_GetUpdateable ( )
Argument Description
instancename Instance name of u_dw

Return value Boolean. Returns TRUE if the DataWindow is updatable and FALSE if it is
not.

of_IsRoot
Description Reports whether the DataWindow is a root DataWindow. A root DataWindow
does not have a master DataWindow.
Access Public
Syntax instancename.of_IsRoot ( )
Argument Description
instancename Instance name of u_dw

Return value Boolean. Returns TRUE if the DataWindow is a root and FALSE if it is not.
Examples This example calls the of_IsRoot function:
IF dw_1.of_IsRoot() THEN
MessageBox("dw_1", "DW is a root")
ELSE
MessageBox("dw_1", "DW is not a root")
END IF

of_IsSharedProperty
Description Reports whether the DataWindow shared property service is enabled.
Access Public
Syntax instancename.of_IsSharedProperty ( )

176
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_dw

Return value Boolean. Returns TRUE if the DataWindow shared property service is enabled
and FALSE if it is not.
Examples This example calls the of_IsSharedProperty function:
IF dw_1.of_IsSharedProperty() THEN
MessageBox("DW", "Shared property enabled")
ELSE
MessageBox("DW", "Shared property disabled")
END IF

of_IsUpdateable
Description Reports whether the DataWindow is updatable.
Access Public
Syntax instancename.of_IsUpdateable ( )
Argument Description
instancename Instance name of u_dw

Return value Boolean. Returns TRUE if the DataWindow is updatable and FALSE if it is
not.
Usage The pfc_UpdatesPending event calls this function.
Examples This example is from the pfc_UpdatesPending event:
...
IF NOT of_IsUpdateable( ) THEN
Return 0
END IF
...

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_dw

177
u_dw

Argument Description
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in DataWindow
controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’dw_dberror’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

of_PostUpdate
Description Calls the pfc_PostUpdate event, which clears update flags and allows you to
code additional post-update processing.
Access Public

178
 Chapter 6 Standard Visual User Objects

Syntax instancename.of_PostUpdate ( )
Argument Description
instancename Instance name of u_dw

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize post update processing,
extend the pfc_PostUpdate event.
Examples This example is from the n_cst_luw of_PostUpdate function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_PostUpdate()
...

of_Reset
Description Resets either a single DataWindow or all DataWindows in a linkage chain.
Access Public
Syntax instancename.of_Reset ( )
Argument Description
instancename Instance name of u_dw

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_Reset function:
...
dw_1.of_Reset()
...

of_Retrieve
Description Retrieves rows for either a single DataWindow or all DataWindows in a
linkage chain. This function calls the pfc_Retrieve event.
Access Public
Syntax instancename.of_Retrieve ( )
Argument Description
instancename Instance name of u_dw

179
u_dw

Return value Integer. Returns the number of rows retrieved if the function succeeds and -1 if
an error occurs.
Usage Call this function to retrieve rows in a DataWindow. You code the actual
Retrieve function in the pfc_Retrieve event.
Examples This example calls the of_Retrieve function:
dw_emplist.of_Retrieve()

of_SetBase
Description Enables or disables n_cst_dwsrv, which provides basic DataWindow services.
Access Public
Syntax instancename.of_SetBase ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) basic DataWindow services

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv. This instance
is named inv_base.
Because all DataWindow services are descendants of n_cst_dwsrv (and have
n_cst_dwsrv functions available to them), use this object when you require
basic DataWindow services only.
Examples This example calls the of_SetBase function to enable basic DataWindow
services:
dw_employee.of_SetBase(TRUE)

of_SetDropDownCalculator
Description Enables or disables u_calculator, which provides a dropdown calculator for
registered columns.
Access Public
Syntax instancename.of_SetDropDownCalculator ( boolean )
Argument Description
instancename Instance name of u_dw

180
 Chapter 6 Standard Visual User Objects

Argument Description
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) the dropdown calculator service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Call this function to enable or disable the dropdown calculator. The u_dw
instance variable for this service is iuo_calculator.
Examples This example calls the of_SetDropDownCalculator function to enable an
instance of the dropdown calculator:
dw_employee.of_SetDropDownCalculator(TRUE)

of_SetDropDownCalendar
Description Enables or disables u_calendar, which provides a dropdown calendar for
registered columns.
Access Public
Syntax instancename.of_SetDropDownCalendar ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) the dropdown calendar service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Call this function to enable or disable the dropdown calendar. The u_dw
instance variable for this service is iuo_calendar.
Examples This example calls the of_SetDropDownCalendar function to enable an
instance of the dropdown calendar:
dw_employee.of_SetDropDownCalendar(TRUE)

of_SetDropDownSearch
Description Enables or disables n_cst_dwsrv_dropdownsearch, which provides dropdown
DataWindow search services.
Access Public
Syntax instancename.of_SetDropDownSearch ( boolean )

181
u_dw

Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) the dropdown DataWindow search service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Call this function to enable or disable DropDownDataWindow search services.
The u_dw instance variable for DropDownDataWindow search services is
inv_dropdownsearch.
Examples This example calls the of_SetDropDownSearch function to enable the
dropdown DataWindow search service:
dw_employee.of_SetDropDownSearch(TRUE)

of_SetFilter
Description Controls or destroys an instance of n_cst_dwsrv_filter, which provides filtering
services.
Access Public
Syntax instancename.of_SetFilter ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the filter service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_filter. This
instance is named inv_filter.
Examples This example calls the of_SetFilter function to enable the filter service:
dw_employee.of_SetFilter(TRUE)

of_SetFind
Description Enables or disables n_cst_dwsrv_find, which provides the DataWindow find
service.
Access Public

182
 Chapter 6 Standard Visual User Objects

Syntax instancename.of_SetFind ( boolean )

Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the DataWindow find service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Call this function to enable or disable the DataWindow find service. The u_dw
instance variable for the DataWindow find service is inv_find.
Examples This example calls the of_SetFind function to enable the DataWindow find
service:
dw_employee.of_SetFind(TRUE)

of_SetLinkage
Description Enables or disables an instance of n_cst_dwsrv_linkage, which provides
master/detail services.
Access Public
Syntax instancename.of_SetLinkage ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the linkage service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_linkage. This
instance is named inv_linkage.
Examples This example calls the of_SetLinkage function to enable the linkage service:
dw_employee.of_SetLinkage(TRUE)

of_SetMultiTable
Description Enables or disables an instance of n_cst_dwsrv_multitable, which provides
multitable update services.
Access Public

183
u_dw

Syntax instancename.of_SetMultiTable ( boolean )

Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the multitable update service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_multitable.
This instance is named inv_multitable.
Examples This example calls the of_SetMultiTable function to enable the multitable
update service:
dw_employee.of_SetMultiTable(TRUE)

of_SetPrintPreview
Description Enables or disables an instance of n_cst_dwsrv_printpreview, which provides
the print preview service.
Access Public
Syntax instancename.of_SetPrintPreview ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the print preview service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_printpreview.
This instance is named inv_printpreview.
Examples This example calls the of_SetPrintPreview function to enable the print preview
service:
dw_employee.of_SetPrintPreview(TRUE)

of_SetProperty
Description Enables or disables an instance of n_cst_dwsrv_property, which provides the
DataWindow property service.

184
 Chapter 6 Standard Visual User Objects

Access Public
Syntax instancename.of_SetProperty ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the DataWindow property service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_property.
This instance is named inv_property.
Examples This example calls the of_SetProperty function to enable the DataWindow
property service:
dw_employee.of_SetProperty(TRUE)

of_SetQuerymode
Description Enables or disables an instance of n_cst_dwsrv_querymode, which provides
querymode services.
Access Public
Syntax instancename.of_SetQuerymode ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the querymode service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_querymode.
This instance is named inv_querymode.
Examples This example calls the of_SetQuerymode function to enable the querymode
service:
dw_employee.of_SetQuerymode(TRUE)

185
u_dw

of_SetReport
Description Enables or disables an instance of n_cst_dwsrv_report, which provides
reporting services.
Access Public
Syntax instancename.of_SetReport ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the report service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_report. This
instance is named inv_report.
Examples This example calls the of_SetReport function to enable the reporting service:
dw_employee.of_SetReport(TRUE)

of_SetReqColumn
Description Enables or disables an instance of n_cst_dwsrv_reqcolumn, which provides
DataWindow required-field services.
Access Public
Syntax instancename.of_SetReqColumn ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the required column service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_reqcolumn.
This instance is named inv_reqcolumn.
Examples This example calls the of_SetReqColumn function to enable the required
column service:
dw_employee.of_SetReqColumn(TRUE)

186
 Chapter 6 Standard Visual User Objects

of_SetResize
Description Enables or disables an instance of n_cst_dwsrv_resize, which provides the
DataWindow resize service.
Access Public
Syntax instancename.of_SetResize ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the DataWindow resize service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_resize. This
instance is named inv_resize.
Examples This example calls the of_SetResize function to enable the DataWindow resize
service:
dw_employee.of_SetResize(TRUE)

of_SetRowManager
Description Enables or disables an instance of n_cst_dwsrv_rowmanager, which provides
row management services.
Access Public
Syntax instancename.of_SetRowManager ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the row management service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_rowmanager.
This instance is named inv_rowmanager.
Examples This example calls the of_SetRowManager function to enable the row
management service:
dw_employee.of_SetRowManager(TRUE)

187
u_dw

of_SetRowSelect
Description Enables or disables an instance of n_cst_dwsrv_rowselection, which provides
row-selection services.
Access Public
Syntax instancename.of_SetRowSelect ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the row selection service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_rowselection.
This instance is named inv_rowselect.
Examples This example calls the of_SetRowSelect function to enable the row selection
service:
dw_employee.of_SetRowSelect(TRUE)

of_SetSharedProperty
Description Enables or disables a shared instance of n_cst_dwsrv_property, which provides
the DataWindow property service.
Access Public
Syntax instancename.of_SetSharedProperty ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the DataWindow property service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy a shared instance of
n_cst_dwsrv_property. This instance is named snv_property.
Examples This example calls the of_SetSharedProperty function to enable the
DataWindow property service:
dw_employee.of_SetSharedProperty(TRUE)

188
 Chapter 6 Standard Visual User Objects

of_SetSort
Description Enables or disables an instance of n_cst_dwsrv_sort, which provides sorting
services.
Access Public
Syntax instancename.of_SetSort ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the sort service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_sort. This
instance is named inv_sort.
Examples This example calls the of_SetSort function to enable the sort service:
dw_employee.of_SetSort(TRUE)

of_SetTransObject
Description Sets the transaction object for either a single DataWindow or all DataWindows
in a linkage chain. This function also initializes instance variables for use by
DataWindow services.
Access Public
Syntax instancename.of_SetTransObject ( transaction )
Argument Description
instancename Instance name of u_dw
transaction N_tr variable specifying the Transaction object to use for the
DataWindow

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to establish a Transaction object for a DataWindow that uses
DataWindow services.
Examples This example calls the of_SetTransObject function. It assumes you have
associated n_tr with SQLCA in the Application painter:
dw_employee.of_SetTransObject(SQLCA)

189
u_dw

of_SetUpdateable
Description Specifies whether the DataWindow is updatable.
Access Public
Syntax instancename.of_SetUpdateable ( boolean )
Argument Description
instancename Instance name of u_dw
boolean Boolean indicating whether the DataWindow is updatable. All
updatable DataWindows are included in w_master’s default save
processing

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to disable default save processing for DataWindows that are
not updatable.

Shared DataWindows
If your application uses shared data, be sure that only one of the DataWindows
using the shared data is declared as updatable.

Examples This example disables default save processing for the dw_report DataWindow:
dw_report.of_SetUpdateable(FALSE)

of_SetUpdateRequestor
Description Creates a reference to the object requesting an update within a logical unit of
work.
Access Public
Syntax instancename.of_SetUpdateRequestor ( requestor )
Argument Description
instancename Instance name of u_dw
requestor PowerObject containing the object requesting the update

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_Update function:
...
Else
If this.of_SetUpdateRequestor(apo_requestor) <0 Then

190
 Chapter 6 Standard Visual User Objects

Return FAILURE
End If
li_rc = this.of_Update(ab_accepttext, ab_resetflag)
...

of_Update
Updates either a single DataWindow or all DataWindows in a linkage chain.
There are two syntaxes:
To Use
Update data, optionally controlling update type Syntax 1
Update data passing the requestor object Syntax 2

Syntax 1 Update data, optionally controlling update type

Description Updates rows in the DataWindow. With this syntax, you can optionally control
the update types:
• Insert
• Update
• Delete
Access Public
Syntax instancename.of_Update ( accepttext, resetflags {, insert, update, delete } )
Argument Description
instancename Instance name of u_dw
accepttext Boolean indicating whether the DataWindow should
automatically perform an AcceptText before performing the
update:
TRUE—Perform AcceptText (default)
FALSE—Do not perform AcceptText
resetflags Boolean indicating whether instancename should automatically
reset the update flags:
TRUE—Reset the flags (default)
FALSE—Do not reset the flags
insert Boolean indicating whether to insert rows:
(optional) TRUE—Insert rows (default)
FALSE—Do not insert rows
update Boolean indicating whether to modify changed rows:
(optional) TRUE—Modify rows (default)
FALSE—Do not modify rows

191
u_dw

Argument Description
delete Boolean indicating whether to delete rows:
(optional) TRUE—Delete rows (default)
FALSE—Do not delete rows

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage This function calls the pfc_Update event.
For more information on update flags, see the Update function in the
PowerScript Reference.
Examples This example calls the of_Update function:
Integer li_return

li_return = dw_emp.of_Update(TRUE, TRUE)

Syntax 2 Update data passing the requestor object

Description Updates rows in the DataWindow, passing a reference to the requestor object.
Access Public
Syntax instancename.of_Update ( accepttext, resetflags, requestor )
Argument Description
instancename Instance name of u_dw
accepttext Boolean indicating whether the DataWindow should
automatically perform an AcceptText before performing the
update:
TRUE—Perform AcceptText (default)
FALSE—Do not perform AcceptText
resetflags Boolean indicating whether instancename should automatically
reset the update flags:
TRUE—Reset the flags (default)
FALSE—Do not reset the flags
requestor PowerObject containing the requestor object

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update processing, extend
the pfc_Update event.
Examples This example is from the n_cst_luw of_Update function:
...

192
 Chapter 6 Standard Visual User Objects

If lb_defined Then
li_rc = lpo_tocheck.Function Dynamic of_Update &
(ab_accepttext, ab_resetflag, &
lpo_updaterequestor)
If li_rc < 0 Then Return -1
Continue
End If
...

of_UpdatePrep
Description Perform update preparation for either a single DataWindow or all
DataWindows in a linkage chain. This function calls the pfc_UpdatePrep
event, which allows you to code additional update preparation logic.
Access Public
Syntax instancename.of_UpdatePrep ( )
Argument Description
instancename Instance name of u_dw

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update preparation
processing, extend the pfc_UpdatePrep event.
Examples This example is from the n_cst_luw of_UpdatePrep function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_UpdatePrep()
If li_rc < 0 Then Return -1
Continue
End If
...

of_UpdatesPending
Description Determines if there are updates pending for either a single DataWindow or all
DataWindows in a linkage chain.
Access Public
Syntax instancename.of_UpdatesPending ( )

193
u_dw

Argument Description
instancename Instance name of u_dw

Return value Integer. Returns values as follows:

•1 Updates are pending
•0 No updates pending
•-1 An error occurred
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize pending updates
processing, extend the pfc_UpdatesPending event.
Examples This example calls the of_UpdatesPending function:
...
If lb_defined Then
la_rc = lpo_tocheck.Dynamic of_UpdatesPending ()
...

of_Validation
Description Performs validation for either a single DataWindow or all DataWindows in a
linkage chain.
Access Public
Syntax instancename.of_Validation ( )
Argument Description
instancename Instance name of u_dw

Return value Integer. Returns 1 if the function succeeds and -1 if a validation error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize validation processing,
extend the pfc_Validation event.
Examples This example calls the of_Validation function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_Validation()
...

194
 Chapter 6 Standard Visual User Objects

u_em
Description EditMask visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
EditMask. U_em event scripts provide integration with PFC menus.
Additionally, u_em supports:
• Cut, copy, paste, clear, and select all These are triggered
automatically by the message router.
• Popup menu support The ContextMenu event enables you to use the
right mouse button to perform editing actions. To disable right mouse
button support, set ib_rmbmenu to FALSE in the edit mask’s Constructor
event.
• Autoselect This means that text is selected when a user tabs to the edit
mask. To disable autoselect, set ib_autoselect to FALSE in the edit mask’s
Constructor event.
• Dropdown calculator You can enable the display of u_calculator, the
dropdown calculator, to enable enhanced input for numeric fields.
• Dropdown calendar You can enable the display of u_calendar, the
dropdown calendar, to enable enhanced input for date fields.
See also m_edit
u_calculator
u_calendar

195
u_em

Instance variables
U_em has instance variables:
Instance variable Description Data type Ancestry Usage
ib_autoselect Indicates whether PFC Boolean Protected Set to FALSE to disable
selects text when the autoselect
control receives focus
ib_rmbmenu Indicates whether the Boolean Protected Set to FALSE to disable
m_edit menu displays right mouse button support
when the user presses
the right mouse button
iuo_calculator Reference variable for u_calculator Public Use in dot notation to
dropdown calculator access u_calculator events,
functions, and attributes
iuo_calendar Reference variable for u_calendar Public Use in dot notation to
dropdown calendar access u_calendar events,
functions, and attributes

Events
U_em includes precoded events:
ContextMenu pfc_DDCalendar
Destructor pfc_Paste
GetFocus pfc_PreRmbMenu
pfc_Clear pfc_SelectAll
pfc_Copy pfc_Undo
pfc_Cut RButtonUp
pfc_DDCalculator

ContextMenu
Description Displays the m_edit popup menu.
Usage This event executes when the user releases the right mouse button over a
control based on u_em.

Destructor
Description Destroys instances of u_calculator and u_calendar.

196
 Chapter 6 Standard Visual User Objects

Usage This event executes when the DataWindow closes.

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

pfc_Clear
Description Deletes selected text.
Return value Integer. Returns the number of characters deleted if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when an EditMask based on u_em has
focus and the user selects Edit>Clear.

pfc_Copy
Description Copies selected text to the clipboard.
Return value Integer. Returns the number of characters copied if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when an EditMask based on u_em has
focus and the user selects Edit>Copy.
This event is also called by the m_edit popup menu.

pfc_Cut
Description Deletes selected text and stores it on the clipboard.
Return value Integer. Returns the number of characters removed if the event succeeds and -
1 if an error occurs.
Usage The message router calls this event when an EditMask based on u_em has
focus and the user selects Edit>Cut.
This event is also called by the m_edit popup menu.

pfc_DDCalculator
Description Displays the dropdown calculator.
Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.

197
u_em

Usage Call this event to display the dropdown calculator.

Examples This example calls the pfc_DDCalculator event:
Integer li_return

li_return = em_1.Event pfc_DDCalculator()

...

pfc_DDCalendar
Description Displays the dropdown calendar.
Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this event to display the dropdown calendar.
Examples This example calls the pfc_DDCalendar event:
Integer li_return

li_return = em_1.Event pfc_DDCalendar()

...

pfc_Paste
Description Inserts (pastes) the contents of the clipboard at the insertion point.
Return value Integer. Returns the number of characters that were pasted if the event succeeds
and -1 if an error occurs.
Usage The message router calls this event when an EditMask based on u_em has
focus and the user selects Edit>Paste.
This event is also called by the m_edit popup menu.

pfc_PreRmbMenu
Description User event allowing you to modify m_edit contents before display.
Syntax instancename.Event pfc_PreRmbMenu ( editmenu )
Argument Description
instancename Instance name of u_em
editmenu M_edit variable containing the popup menu to be displayed (passed
by reference)

Return value None

198
 Chapter 6 Standard Visual User Objects

Usage Optionally add logic to this event to selectively enable and disable m_edit
menu items.

pfc_SelectAll
Description Selects all text in the EditMask.
Return value Integer. Returns the number of characters selected if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when an EditMask based on u_em has
focus and the user selects Edit>Select All.
This event is also called by the m_edit popup menu.

pfc_Undo
Description Cancels the last change to the EditMask, restoring the text to the content before
the last change.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The message router calls this event when an EditMask based on u_em has
focus and the user selects Edit>Undo.

RButtonUp
Description Empty user event. PFC code previously assigned to this event is now in the
ContextMenu event.
Usage This event executes when the user releases the right mouse button over a
control based on u_em.

Functions
U_em includes precoded object functions:
of_GetParentWindow of_SetDropDownCalculator
of_MessageBox of_SetDropDownCalendar

of_GetParentWindow
Description Retrieves a reference to the parent window.

199
u_em

Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_em
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_em GetFocus event calls this function.
Examples This example is from the u_em GetFocus event:
Window lw_parent
IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_em
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!

200
 Chapter 6 Standard Visual User Objects

Argument Description
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in EditMasks.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’em_error’,’Save’, &
as_error, StopSign!, Ok!, 1)

of_SetDropDownCalculator
Description Enables or disables u_calculator, which provides a dropdown calculator.
Access Public
Syntax instancename.of_SetDropDownCalculator ( boolean )
Argument Description
instancename Instance name of u_em
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) the dropdown calculator service

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to enable or disable the dropdown calculator. The u_em
instance variable for this service is iuo_calculator.
Examples This example calls the of_SetDropDownCalculator function to enable an
instance of the dropdown calculator:
em_1.of_SetDropDownCalculator(TRUE)

201
u_em

of_SetDropDownCalendar
Description Enables or disables u_calendar, which provides a dropdown calendar for
registered columns.
Access Public
Syntax instancename.of_SetDropDownCalendar ( boolean )
Argument Description
instancename Instance name of u_em
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) the dropdown calendar service

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to enable or disable the dropdown calendar.
Examples This example calls the of_SetDropDownCalendar function to enable an
instance of the dropdown calendar:
em_1.of_SetDropDownCalendar(TRUE)

202
 Chapter 6 Standard Visual User Objects

u_gb
Description GroupBox visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this visual object in windows instead of the standard PowerBuilder
GroupBox.

203
u_gr

u_gr
Description Graph visual user object.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual user object in windows instead of the standard PowerBuilder
Graph control. U_gr scripts provide integration with PFC menus.
See also w_master

Events
U_gr includes a precoded event script:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_gr includes precoded object functions:
of_GetParentWindow
of_MessageBox

204
 Chapter 6 Standard Visual User Objects

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_gr
window Window variable into which the function places a reference to
the parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_gr GetFocus event calls this function.
Examples This example is from the u_gr GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_gr
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

205
u_gr

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in Graph controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’gr_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

206
 Chapter 6 Standard Visual User Objects

u_hpb
Description HorizontalProgressBar visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
HorizonalProgressBar. U_hpb event scripts provide integration with PFC
menus.
See also u_progressbar
u_vpb
w_master

Events
U_hpb includes one precoded event:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_hpb includes precoded object functions:
of_GetParentWindow
of_MessageBox

207
u_hpb

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_hpb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_hpb GetFocus event calls this function.
Examples This example is from the u_hpb GetFocus event:
Window lw_parent

//Check for MicroHelp requirements.

IF gnv_app.of_GetMicrohelp() THEN
//Notify the parent.
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_hpb
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

208
 Chapter 6 Standard Visual User Objects

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in
HorizontalProgressBars.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’hpb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

209
u_hsb

u_hsb
Description HorizontalScrollBar visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
HorizonalScrollBar. U_hsb event scripts provide integration with PFC menus.
See also w_master
u_vsb

Events
U_hsb includes one precoded event:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_hsb includes precoded object functions:
of_GetParentWindow
of_MessageBox

210
 Chapter 6 Standard Visual User Objects

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_hsb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_hsb GetFocus event calls this function.
Examples This example is from the u_hsb GetFocus event:
Window lw_parent

//Check for MicroHelp requirements.

IF gnv_app.of_GetMicrohelp() THEN
//Notify the parent.
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_hsb
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

211
u_hsb

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in
HorizontalScrollBars.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’hsb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

212
 Chapter 6 Standard Visual User Objects

u_htb
Description HorizontalTrackBar visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
HorizonalTrackBar. U_htb event scripts provide integration with PFC menus.
See also w_master
u_vtb

Events
U_htb includes one precoded event:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_htb includes precoded object functions:
of_GetParentWindow
of_MessageBox

213
u_htb

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_htb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_htb GetFocus event calls this function.
Examples This example is from the u_htb GetFocus event:
Window lw_parent

//Check for MicroHelp requirements.

IF gnv_app.of_GetMicrohelp() THEN
//Notify the parent.
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_htb
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

214
 Chapter 6 Standard Visual User Objects

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in
HorizontalTrackBars.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’htb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

215
u_lb

u_lb
Description ListBox visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual user object in windows instead of the standard PowerBuilder
ListBox control. U_lb event scripts provide integration with PFC menus.
See also w_master
u_ddlb
u_ddplb
u_plb

Events
U_lb includes precoded events:
GetFocus pfc_SelectAll
pfc_InvertSelection

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

pfc_InvertSelection
Description Inverts the rows selected in the ListBox. Unselected rows become selected;
selected rows are unselected.

216
 Chapter 6 Standard Visual User Objects

Return value Integer. Returns the number of selected rows if the event succeeds and 0 if this
is an invalid operation.
Usage To use this event, add a menu item that uses the message router to call
pfc_InvertSelection.

pfc_SelectAll
Description Selects all rows in the ListBox.
Return value Integer. Returns the number of selected rows if the event succeeds and 0 if this
is an invalid operation.
Usage The message router calls this event when the user selects Edit>Select All from
the menu bar.

Functions
U_lb includes precoded object functions:
of_GetParentWindow of_MessageBox
of_GetSelected

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_lb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_lb GetFocus event calls this function.
Examples This example is from the u_lb GetFocus event:
Window lw_parent
IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)

217
u_lb

IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_GetSelected
Description Populates the passed structure object with the selected entries in the ListBox.
Access Public
Syntax instancename.of_GetSelected ( itemattrib )
Argument Description
instancename Instance name of u_lb
itemattrib N_cst_itemattrib array into which the function places text and an
item index (passed by reference)

Return value Integer. Returns the number of elements in the itemattrib array if the function
succeeds and 0 if this is not a valid operation.
Examples This example calls the of_GetSelected function:
n_cst_itemattrib lnv_items[ ]
Integer li_selected

li_selected = lb_list.of_GetSelected(lnv_items)
IF li_selected = 0 THEN
MessageBox("LB", "Invalid LB operation")
Return
END IF
// Logic to read lnv_items follows
...

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_lb
id String specifying an ID for the message
title String specifying the title of the MessageBox

218
 Chapter 6 Standard Visual User Objects

Argument Description
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in ListBoxes.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’lb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

219
u_lvs

u_lvs
Description Service-based ListView visual user object ancestor. This object uses
DataStores to display data in a ListView.
U_lvs is a self-updating object.

U_lvs replaces u_lv

U_lv is the ListView control supported in earlier PFC versions. Although PFC
still provides u_lv, it’s best to use u_lvs.

Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master. U_lvs also uses:
m_lvs
n_cst_infoattrib
n_cst_luw

220
 Chapter 6 Standard Visual User Objects

n_cst_lvsrv
n_cst_lvsrv_datasource
n_cst_lvsrv_sort
n_ds
Usage Use this visual user object in windows instead of the standard PowerBuilder
ListView control. U_lvs functions make it easy for you to populate a ListView
from rows in a DataWindow. U_lvs event scripts also provide integration with
PFC menus.
U_lvs includes right mouse button support. If the user clicks the right mouse
button over a u_lvs-based ListView control, the m_lvs menu displays. M_lvs
allows you to control ListView icon display.
To use u_lvs:
1 Place a u_lvs user object in your window.
2 In the window pfc_PreOpen event (or some other appropriate place),
enable ListView services as needed by your application:
lv_1.of_SetDataSource(TRUE)
lv_1.of_SetSort(TRUE)
3 Specify sorting information:
String ls_exclude[ ]

lv_1.inv_sort.of_SetColumnHeader(TRUE)
ls_exclude[1] = "emp_phone_number"
lv_1.inv_sort.of_SetExclude(ls_exclude)
4 Specify data source information:
Integer li_count

lv_1.inv_datasource.of_Register("emp_lname", &
"d_emplist", SQLCA)
li_count = &
lv_1.inv_datasource.of_RegisterReportColumn()
lv_1.inv_datasource.of_SetPictureColumn("1")
5 Populate the ListView with information from the registered data source:
lv_1.Event pfc_Populate()

221
u_lvs

6 Extend the pfc_Retrieve event to retrieve rows:

Any la_args[20]

la_args[1] = "windows" // Retrieval argument

this.of_Retrieve(la_args, ads_data)
7 Extend basic u_lvs functionality by adding PowerScript code to events and
user events.
For more information on the ListView control, see the PowerBuilder User’s
Guide.
See also m_lvs
n_ds
u_tvs

Instance variables
U_lvs includes instance variables:
Instance variable Description Data type Access Usage
CONTINUE_ACTION Constant set to 1 Integer Public Internal
ib_alwaysvalidate Controls whether the Boolean Protected Set with
save process includes of_SetAlwaysValidate
all objects in the (default is FALSE)
validation process
ib_isupdateable Indicates whether the Boolean Protected Set with of_SetUpdateable
ListView can be (default is FALSE)
updated
ib_rmbmenu Controls right mouse Boolean Protected Use to enable or disable
button support right mouse button support
(default is TRUE)
Set with of_SetRMBMenu
il_rightclicked Contains the handle of Long Protected PFC uses this instance
the right-clicked variable to track the right-
ListView item clicked item
INSERT_AFTER Constant set to "after" String Public Internal
INSERT_BEFORE Constant set to "before" String Public Internal
INSERT_FIRST Constant set to "first" String Public Internal
INSERT_LAST Constant set to "last" String Public Internal

222
 Chapter 6 Standard Visual User Objects

Instance variable Description Data type Access Usage

inv_base Reference variable for n_cst_lvsrv Public Use in dot notation to
basic ListView services access n_cst_lvsrv
functions and attributes
inv_datasource Reference variable for n_cst_lvsrv_ Public Use in dot notation to
the ListView data datasource access
source service n_cst_lvsrv_datasource
functions and attributes
inv_luw Reference variable for n_cst_luw Protected Implements the save
logical unit of work process
service
inv_sort Reference variable for n_cst_lvsrv_ Public Use in dot notation to
ListView sort service sort access n_cst_lvsrv_sort
functions and attributes
ipo_pendingupdates[ ] Objects that could be PowerObject Protected Internal
updated
ipo_updaterequestor Owner of the save PowerObject Protected Internal
process
NO_ACTION Constant set to 0 Integer Public Internal
PREVENT_ACTION Constant set to 0 Integer Public Internal

Events
U_lvs includes precoded event scripts:
ColumnClick pfc_PreRefreshItem
ContextMenu pfc_PreRmbMenu
Destructor pfc_Properties
EndLabelEdit pfc_Refresh
GetFocus pfc_RefreshItem
KeyDown pfc_RenameItem
pfc_AcceptText pfc_Retrieve
pfc_AddAll pfc_SelectAll
pfc_AddItem pfc_SetItemAttributes
pfc_DeleteItem pfc_Undo
pfc_InsertItem pfc_Update
pfc_InvertSelection pfc_UpdatePrep
pfc_NewItem pfc_UpdatesPending
pfc_Populate pfc_Validation

223
u_lvs

pfc_PostUpdate RButtonUp
pfc_PreDeleteItem RightClicked
pfc_PreInsertItem Sort

ColumnClick
Description Sorts the ListView contents, using the column whose heading was clicked. If
the column is already sorted, this event reverses the sort order.
Usage To use this event, n_cst_lvsrv_sort must be enabled. This event executes when
the user clicks a ListView control’s column heading.

ContextMenu
Description Displays the m_lvs popup menu.
Usage This event executes when the user releases the right mouse button.

Destructor
Description Destroys all existing ListView service objects.
Usage This event executes when the ListView is destroyed or the window closes.

EndLabelEdit
Description Updates the DataStore with user edits to the item label.
This function updates the DataStore only. You must update the database
explicitly, using the of_Update or the n_cst_luw of_Save function.
Return value Integer. Returns 0 if the label update is allowed and 1 if PowerBuilder should
prevent the label update.
Usage This event executes when the user finishes editing an item label.
PFC allows label update only when the associated label column is updatable.
If the label column is a computed column, you must override this event or the
n_cst_lvsrv_datasource pfc_EndLabelEdit event to update the computed
column and return a 0.

GetFocus
Description Updates the parent window so it can set MicroHelp.

224
 Chapter 6 Standard Visual User Objects

Usage This event calls the pfc_ControlGotFocus event in the parent.

KeyDown
Description Checks to see if the DELETE key was pressed.
Usage This event executes when the user presses a key and is not editing a label.

pfc_AcceptText
Description Accepts text for the ListView control data source, optionally setting focus if an
error occurs.
Syntax instancename.EVENT pfc_AcceptText ( controls, focusonerror )
Argument Description
instancename Instance name of u_lvs
controls PowerObject array containing the objects on which to accept text.
This argument is accessed through the apo_control argument
focusonerror Boolean indicating whether focus should be set if an error occurs.
This argument is accessed through the ab_focusonerror argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Extend this event to perform additional accept text processing.

pfc_AddAll
Description Adds all rows in the passed DataStore to the ListView.
Syntax instancename.EVENT pfc_AddAll ( data )
Argument Description
instancename Instance name of u_lvs
data N_ds-based DataStore containing rows to be added. This
argument is accessed through the ads_source argument

Return value Integer. Returns the number of items added if the event succeeds and -1 if an
error occurs.
Examples This example is from the pfc_Refresh event:
...
inv_datasource.of_getdatasource(lds_source)
return this.event pfc_AddAll(lds_source)
...

225
u_lvs

pfc_AddItem
Description Adds the specified row in the data source to the end of the ListView.
Syntax instancename.EVENT pfc_AddItem ( data, row )
Argument Description
instancename Instance name of u_lvs
data N_ds-based DataStore containing rows to be added. This
argument is accessed through the ads_source argument
row Long specifying the row containing the data to be added to the
ListView. This argument is accessed through the al_row
argument

Return value Long. Returns the ListView index of the new row if the event succeeds and -1
if an error occurs.
Examples This example is from the of_AddItem function:
...
li_newindex = this.event pfc_additem &
(lds_datastore, ll_row)
...

pfc_DeleteItem
Description Deletes the selected rows from the ListView and the DataStore.
Return value Integer. Returns the number of rows deleted if the event succeeds and -1 if an
error occurs.
Examples This example calls the pfc_DeleteItem event:
...
li_return = lv_1.Event pfc_DeleteItem()
...

pfc_InsertItem
Description Inserts a new item into the ListView at the specified position.
Syntax instancename.EVENT pfc_InsertItem (datastore, row, position, item )
Argument Description
instancename Instance name of u_lvs

226
 Chapter 6 Standard Visual User Objects

Argument Description
datastore N_ds containing the data for the new item. This can be either the
DataStore maintained by n_cst_lvsrv_datasource or another
DataStore. If this is another DataStore, the associated
DataWindow objects must be the same and the function also
adds the row to the DataStore maintained by
n_cst_lvsrv_datasource. This argument is accessed through the
ads_source argument
row Long specifying the row containing the item. This argument is
accessed through the al_row argument
position String specifying the position or location in which to insert the
new item. Valid values are:
• First
• Last
• Before
• After
This argument is accessed through the as_position argument
item Integer containing an index relative to the current position. The
function uses this argument if you specify Before or After for
position. This argument is accessed through the ai_index
argument

Return value Integer. Returns the index of the new item if the function succeeds and -1 if an
error occurs.
Usage This event calls the pfc_SetItemAttributes and pfc_PreInsertItem events before
inserting the item.
Examples This example is from the pfc_AddAll event:
...
For ll_row = 1 to ll_rowcount
If this.event pfc_insertitem(ads_source, &
ll_row, "last", 0) < 1 then
Return -1
End If
...

pfc_InvertSelection
Description Inverts the rows selected in the ListView. Unselected rows become selected;
selected rows are unselected.
Return value Integer. Returns the number of selected rows if the event succeeds and -1 if this
is an invalid operation.

227
u_lvs

Usage To use this event, add a menu item that uses the message router to call
pfc_InvertSelection.

pfc_NewItem
Description Empty user event that you extend to add information to both the data source
and the ListView.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage You typically use this event to open a dialog box prompting the user for
complete information, adding it to the data source and the ListView (via the
pfc_InsertItem event) when it closes.

pfc_Populate
Description Retrieves the data source and uses it to populate the ListView.
Return value Integer. Returns the number of items added to the ListView if the event
succeeds and -1 of an error occurs.
Usage You must add code to the pfc_Retrieve event to retrieve the data.
Examples This example calls the pfc_Populate event:
String ls_exclude[ ]
Integer li_count

// ListView Constructor event

this.of_SetDataSource(TRUE)
this.of_SetSort(TRUE)
this.inv_sort.of_SetColumnHeader(TRUE)
ls_exclude[1] = "emp_phone_number"
this.inv_sort.of_SetExclude(ls_exclude)
this.inv_datasource.of_Register("emp_lname", &
"d_emplist", SQLCA)
li_count = &
this.inv_datasource.of_RegisterReportColumn()
this.inv_datasource.of_SetPictureColumn("1")
this.Event pfc_Populate()

pfc_PostUpdate
Description Calls the n_cst_luw of_PostUpdate function to perform post-update processing
on the specified controls.
Syntax instancename.EVENT pfc_PostUpdate ( controls )

228
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_lvs
controls PowerObject array containing the objects on which to perform
postupdate processing. This argument is accessed through the
apo_control argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Extend this event to perform additional post-update processing.

pfc_PreDeleteItem
Description Empty user event to which you add logic to perform predelete processing.
Syntax instancename.EVENT pfc_PreDeleteItem ( index )
Argument Description
instancename Instance name of u_lvs
index Integer specifying the index of the ListView item to be deleted.
This argument is accessed through the ai_index argument

Usage The pfc_DeleteItem event calls this event.

pfc_PreInsertItem
Description Empty user event to which you add logic to perform pre-insert processing.
Syntax instancename.Event pfc_PreInsertItem ( data, row, lvitem )
Argument Description
instancename Instance name of u_lvs
data N_ds containing the data for the new item. This argument is
accessed through the ads_obj argument
row Long specifying the row containing the new item. This argument
is accessed through the al_row argument
lvitem ListViewItem to be inserted. This argument is accessed through
the alvi_item argument (passed by reference)

Usage The pfc_InsertItem event calls this event.

pfc_PreRefreshItem
Description Empty user event to which you add logic that changes ListView item properties
before a ListView item is refreshed.

229
u_lvs

Syntax instancename.EVENT pfc_PreRefreshItem ( index, data, row, lvitem )

Argument Description
instancename Instance name of u_lvs
index Integer specifying the index of the refreshed item. This argument
is accessed through the ai_index argument
data N_ds containing the data for the refreshed item. This argument
is accessed through the ads_obj argument
row Long specifying the row containing the refreshed item. This
argument is accessed through the al_row argument
lvitem ListViewItem to be refreshed. This argument is accessed
through the alvi_item argument (passed by reference)

Usage The pfc_RefreshItem event calls this event.

pfc_PreRmbMenu
Description Empty user event allowing you to modify m_lvs contents before display.
Syntax instancename.Event pfc_PreRmbMenu ( editmenu )
Argument Description
instancename Instance name of u_lvs
editmenu M_lvs variable containing the popup menu to be displayed
(passed by reference)

Usage Optionally add logic to this event to selectively enable and disable m_lvs menu
items.

pfc_Properties
Description Empty user event to which you might add logic to display a Properties dialog.
Return value Integer. Return 1 if the event succeeds and -1 if an error occurs.

pfc_Refresh
Description Refresh the ListView items with data from the data source.
Return value Integer. Returns the number of items refreshed if the event succeeds and -1 if
an error occurs.
Examples This example is from the pfc_Populate event:
...
If this.event pfc_refresh() <> 1 Then Return -3

230
 Chapter 6 Standard Visual User Objects

...

pfc_RefreshItem
Description Refreshes the specified ListView item, resetting all properties to the defaults
specified in the data source.
Syntax instancename.EVENT pfc_RefreshItem ( index )
Argument Description
instancename Instance name of u_lvs
index Integer specifying the ListView index of the item to refresh

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Examples This example calls the pfc_RefreshItem event:
...
lv_1.Event pfc_RefreshItem(1)
...

pfc_RenameItem
Description Renames the selected item.
Usage To use this event, the Edit Labels property must be enabled for the ListView.

pfc_Retrieve
Description Retrieves rows into the ListView’s data source.
Syntax instancename.EVENT pfc_Retrieve ( datasource )
Argument Description
instancename Instance name of u_lvs
datasource N_ds into which rows are retrieved. This argument is accessed
through the ads_data argument (passed by reference)

Return value Long. Return the number of items retrieved if the event succeeds and -1 if an
error occurs.
Usage Add code to this event that calls the of_Retrieve function to retrieve rows for
the data source.
Examples This example shows code you might add to the pfc_Retrieve event:
Any la_args[20]

231
u_lvs

la_args[1] = "windows" // Retrieval argument

this.of_Retrieve(la_args, ads_data)

pfc_SelectAll
Description Selects all rows in the ListView.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The message router calls this event when the user selects Edit>Select All from
the menu bar.

pfc_SetItemAttributes
Description Sets default properties for the ListView item before insertion.
Syntax instancename.EVENT pfc_SetItemAttributes ( data, row, lvitem )
Argument Description
instancename Instance name of u_lvs
data N_ds containing the data for the item. This argument is accessed
through the ads_obj argument
row Long specifying the row containing the item. This argument is
accessed through the al_row argument
lvitem ListViewItem to be inserted. This argument is accessed through
the alvi_item argument (passed by reference)

Usage Optionally extend this event to change ListView item properties before
insertion.

pfc_Undo
Description Cancels the last change to the ListView, restoring the text to the content before
the last change.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The message router calls this event when a ListView based on u_lvs has focus
and the user selects Edit>Undo.

pfc_Update
Description Calls the n_cst_luw of_Update function to update the specified controls.
Syntax instancename.EVENT pfc_Update ( controls, accepttext, resetflags )

232
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_lvs
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument
accepttext Boolean specifying whether n_cst_luw should automatically
perform an AcceptText before performing the Update (TRUE) or
not (FALSE)
resetflags Boolean specifying whether n_cst_luw should automatically reset
DataWindow update flags (TRUE) or not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The of_Update function calls this event.

pfc_UpdatePrep
Description Empty user event to which you can add code that prepares for update.
Syntax instancename.EVENT pfc_UpdatePrep ( controls )
Argument Description
instancename Instance name of u_lvs
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument

Return value Long. Return 1 if the update preparation succeeds and -1 to halt the update
process.
Usage The of_UpdatePrep function calls this function.

pfc_UpdatesPending
Description Determines if there are pending updates for the ListView.
Syntax instancename.EVENT pfc_UpdatesPending ( controls, pending )
Argument Description
instancename Instance name of u_lvs
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument
pending PowerObject array into which the event places objects with
pending updates. This argument is accessed through the
apo_pending argument (passed by reference)

233
u_lvs

Return value Integer. Returns 1 if there are pending updates, 0 if there are no pending
updates, and -1 if an error occurs.
Usage This event is called by the of_GetUpdatesPending function.

pfc_Validation
Description Checks for required fields.
Syntax instancename.EVENT pfc_Validation ( controls )
Argument Description
instancename Instance name of u_lvs
controls PowerObject array containing the objects to validate. This
argument is accessed through the apo_control argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the of_Validation function.

RButtonUp
Description Empty user event. PFC code previously assigned to this event is now in the
ContextMenu event.
Usage This event executes when the user releases the right mouse button.

RightClicked
Description Tracks the clicked item and displays the m_lvs popup menu.
Usage This event executes when the user presses the right mouse button.

Sort
Description Performs the sort comparison when the sort type is UserDefined!.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Extend the n_cst_lvsrv_sort pfc_Sort event to create site-specific sort logic.

Functions
U_lvs includes precoded object functions:

234
 Chapter 6 Standard Visual User Objects

of_AcceptText of_PostUpdate
of_AddItem of_Reset
of_CanUndo of_Retrieve
of_GetInfo of_SetAlwaysValidate
of_GetColumnInfo of_SetBase
of_GetObjects of_SetDataSource
of_GetParentWindow of_SetLogicalUnitOfWork
of_GetRow of_SetRMBMenu
of_GetUpdateRequestor of_SetSort
of_InsertItem of_SetUpdateable
of_IsAlwaysValidate of_SetUpdateRequestor
of_IsRMBMenu of_Update
of_IsUpdateable of_UpdatePrep
of_MessageBox of_UpdatesPending
of_Populate of_Validation

of_AcceptText
Description Performs an AcceptText function for the data source.
Access Public
Syntax instancename.of_AcceptText ( focusonerror )
Argument Description
instancename Instance name of u_lvs
focusonerror Boolean indicating whether PFC sets focus to the first item in error
when an error occurs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize accept text processing,
extend the pfc_AcceptText event.
Examples This example is from the n_cst_luw of_AcceptText function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_AcceptText &
(ab_focusonerror)
If li_rc < 0 Then Return -1

235
u_lvs

...

of_AddItem
Description Adds a new item to the end of the ListView control.
Access Public
Syntax instancename.of_AddItem ( rowinfo )
Argument Description
instancename Instance name of u_lvs
rowinfo Any array containing data for the row

Return value Long. Returns the index of the added item if the functions succeeds and -1 if
an error occurs.
Usage If the information in rowinfo is not already in the data source, this function adds
the new row to the data source. If you are using the ListView data source
service, the data types of the elements in rowinfo must match those in the
DataWindow object specified in the n_cst_lvsrv_datasource of_Register
function.
Examples This example calls the of_AddItem function:
Any la_row[ ]

la_row[1] = 500
la_row[2] = "Nelsen"
la_row[3] = "Rodney"
lv_1.of_AddItem(la_row)

of_CanUndo
Description Reports whether the ListView can undo the last edit, insertion, or deletion,
returning the operation type.
Access Public
Syntax instancename.of_CanUndo ( undotype )
Argument Description
instancename Instance name of u_lvs

236
 Chapter 6 Standard Visual User Objects

Argument Description
undotype String into which the function places the type of the last
operation (passed by reference):
• "Edit" Edit
• "Insert" Insertion
• "Delete" Deletion

Return value Boolean. Returns TRUE if the last operation can be undone and FALSE if it
cannot.
Examples This example calls the of_CanUndo function:
String ls_undotype

IF lv_1.of_CanUndo(ls_undotype) THEN
MessageBox("ListView", "Can undo")
ELSE
MessageBox("ListView", "Cannot undo")
END IF

of_GetColumnInfo
Description Retrieves column information from the ListView.
Access Public
Syntax instancename.of_GetColumnInfo ( column, colattrib )
Argument Description
instancename Instance name of the u_lvs-based ListView control
column Integer specifying the column from the ListView
colattrib N_cst_columnattrib into which the function places column
information (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Column information is used in detail view only.
Examples This example calls the of_GetColumnInfo:
n_cst_columnattrib lnv_colinfo

lv_1.of_GetColumnInfo(3, lnv_colinfo)
...

237
u_lvs

of_GetInfo
Description Retrieves object information.
Access Public
Syntax instancename.of_GetInfo ( infoobject )
Argument Description
instancename Instance name of u_lvs
infoobject N_cst_infoattrib instance into which the function places
information (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_GetInfo function:
n_cst_infoattrib lnv_info

lv_1.of_GetInfo(lnv_info)
MessageBox("Info", &
"Description: " + lnv_info.is_description &
+ ". Name: " + lnv_info.is_name)

of_GetObjects
Description Retrieves the objects to be updated.
Access Protected
Syntax instancename.of_GetObjects ( objects )
Argument Description
instancename Instance name of u_lvs
objects PowerObject array into which the function places objects to be
updated (passed by reference)

Return value Integer. Returns the number of elements in the objects array if the function
succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_AcceptText function:
...
Else
this.of_Getobjects(lpo_updatearray)
End If
...

238
 Chapter 6 Standard Visual User Objects

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_lvs
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_lvs GetFocus event calls this function.
Examples This example is from the u_lvs GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_GetRow
Description Retrieves the DataStore and DataStore row for the specified ListView index.
Access Public
Syntax instancename.of_GetRow ( index, data, row )
Argument Description
instancename Instance name of u_lvs
index Integer specifying the index for the row to be retrieved
data N_ds into which the function places a reference to the DataStore
(passed by reference)
row Long into which the function places the row number that
corresponds to index (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_GetRow function:

239
u_lvs

n_ds lds_data
Long ll_row

lv_1.of_GetRow(1, lds_data, ll_row)

MessageBox("ListView", &
"DataObject is: " + lds_data.DataObject &
+ " Row is: " + String(ll_row))

of_GetUpdateRequestor
Description Retrieves a reference to the object requesting an update.
Access Public
Syntax instancename.of_GetUpdateRequestor ( requestor )
Argument Description
instancename Instance name of u_lvs
requestor PowerObject into which the function places a reference to the
object requesting the update (passed by reference)

Return value Integer. Returns 1 if the function succeeds, 0 if there is no update requestor, and
-1 if an error occurs.
Usage Call this function if you are extending the pfc_Save process and need to access
the update requestor.

of_InsertItem
Inserts an item into the ListView. There are two syntaxes:
To Use
Insert from a DataStore Syntax 1
Insert from an array Syntax 2

Syntax 1 Insert an item from a DataStore

Description Adds a new item to the ListView using a row from a DataStore.
Access Public
Syntax instancename.of_InsertItem ( datastore, row {, position, index } )
Argument Description
instancename Instance name of u_lvs

240
 Chapter 6 Standard Visual User Objects

Argument Description
datastore N_ds containing the data for the new item. This can be either the
DataStore maintained by n_cst_lvsrv_datasource or another
DataStore. If this is another DataStore, the associated
DataWindow objects must be the same and the function also
adds the row to the DataStore maintained by
n_cst_lvsrv_datasource (passed by reference)
row Long specifying the row containing data for the new item
position String specifying the position under the current parent in which
(optional) to insert the new item. Valid values are:
• First
• Last (default)
• Before
• After
index Integer containing an index relative to the current position. The
(optional) function uses this argument if you specify Before or After for
position

Return value Integer. Returns the index of the new item if the function succeeds and -1 if an
error occurs.
Examples This example calls the of_InsertItem function:
Long ll_row

ll_row = ids_data.GetRow()
lv_1.of_InsertItem(ids_data, ll_row)

Syntax 2 Insert an item from an array

Description Adds a new item to the ListView using a value from an array.
Access Public
Syntax instancename.of_InsertItem ( colvalues {, position, index } )
Argument Description
instancename Instance name of u_lvs
colvalues Any array containing data for the ListView

241
u_lvs

Argument Description
position String specifying the position or location in which to insert the
(optional) new item. Valid values are:
• First
• Last (default)
• Before
• After
index Integer containing an index relative to the current position. The
(optional) function uses this argument if you specify Before or After for
position

Return value Integer. Returns the index of the new item if the function succeeds and -1 if an
error occurs.
Examples This example calls the of_InsertItem function:
Any la_row[ ]

la_row[1] = 500
la_row[2] = "Nelsen"
la_row[3] = "Rodney"
lv_1.of_InsertItem(la_row, "First", 0)

of_IsAlwaysValidate
Description Reports whether the default save process always performs validation.
Access Public
Syntax instancename.of_IsAlwaysValidate ( )
Argument Description
instancename Instance name of u_lvs

Return value Boolean. Returns TRUE if the default save process always performs validation
and FALSE if it does not.
Examples This example calls the of_IsAlwaysValidate function:
IF lv_1.of_IsAlwaysValidate() = TRUE THEN
MessageBox("LV", "Always validate")
ELSE
MessageBox("LV", "Sometimes validate")
END IF

242
 Chapter 6 Standard Visual User Objects

of_IsRMBMenu
Description Reports whether the popup menu is enabled.
Access Public
Syntax instancename.of_IsRMBMenu ( )
Argument Description
instancename Instance name of u_lvs

Return value Boolean. Returns TRUE if the m_lvs popup menu is enabled and FALSE if it
is not.
Examples This example calls the of_IsRMBMenu function:
IF lv_1.of_IsRMBMenu() = TRUE THEN
MessageBox("LV", "RMB enabled")
ELSE
MessageBox("LV", "RMB disabled")
END IF

of_IsUpdateable
Description Reports whether the ListView’s data source is updatable and should be
included in a window's default save processing.
Access Public
Syntax instancename.of_IsUpdateable ( )
Argument Description
instancename Instance name of u_lvs

Return value Boolean. Returns TRUE if the ListView’s data source is updatable and FALSE
if it is not.
Usage The pfc_UpdatesPending event calls this function.
Examples This example is from the pfc_UpdatesPending event:
...
If Not of_IsUpdateable() Then Return NO_UPDATESPENDING
...

of_MessageBox
Description Displays a MessageBox.
Access Protected

243
u_lvs

Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )

Argument Description
instancename Instance name of u_lvs
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in ListViews.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’lv_error’,’Save’, &
as_error, StopSign!, Ok!, 1)

of_Populate
Description Retrieves the data source and populates a ListView.
Access Public

244
 Chapter 6 Standard Visual User Objects

Syntax instancename.of_Populate ( )
Argument Description
instancename Instance name of u_lvs

Return value Integer. Returns the number of items added if the function succeeds and -1 if
an error occurs.
Usage Internal.
Examples The example is from the pfc_Populate event:
Return of_populate()

of_PostUpdate
Description Calls the pfc_PostUpdate event, which clears update flags and allows you to
code additional post-update processing.
Access Public
Syntax instancename.of_PostUpdate ( )
Argument Description
instancename Instance name of u_lvs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize post-update processing,
extend the pfc_PostUpdate event.
Examples This example is from the n_cst_luw of_PostUpdate function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_PostUpdate()
...

of_Reset
Description Deletes all items from both the ListView and the data source.
Access Public
Syntax instancename.of_Reset ( )
Argument Description
instancename Instance name of u_lvs

245
u_lvs

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Examples This example calls the of_Reset function:
lv_1.of_Reset()

of_Retrieve
Description Retrieves rows into a DataStore.
Syntax instancename.EVENT of_Retrieve ( args, data )
Argument Description
instancename Instance name of u_lvs
args 20-element Any array specifying retrieval arguments
data N_ds into which the function places the retrieved rows (passed by
reference)

Return value Long. Returns the number of items retrieved if the function succeeds, 0 if no
action was taken, and -1 if an error occurs.
Examples This example (from a pfc_Retrieve event) calls the of_Retrieve function:
Long ll_count
Any la_args[20]

ll_count = this.of_Retrieve(la_args, ads_data)

Return ll_count

of_SetAlwaysValidate
Description Specifies whether the default save process always performs validation.
Access Public
Syntax instancename.of_SetAlwaysValidate ( boolean )
Argument Description
instancename Instance name of u_lvs
boolean Boolean specifying whether the default save process always
perform validation (TRUE) or only performs validation if a
control has pending updates

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetAlwaysValidate function:
lv_1.of_SetAlwaysValidate(TRUE)

246
 Chapter 6 Standard Visual User Objects

of_SetBase
Description Enables or disables n_cst_lvsrv, which provides basic ListView services.
Access Public
Syntax instancename.of_SetBase ( boolean )
Argument Description
instancename Instance name of u_lvs
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) basic ListView services

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_lvsrv. This instance
is named inv_base.
Because all ListView services are descendants of n_cst_lvsrv (and have
n_cst_lvsrv functions available to them), use this object when you require basic
ListView services only.
Examples This example calls the of_SetBase function to enable basic ListView services:
lv_1.of_SetBase(TRUE)

of_SetDataSource
Description Enables or disables n_cst_lvsrv_datasource, which provides data access for
ListViews.
Access Public
Syntax instancename.of_SetDataSource ( boolean )
Argument Description
instancename Instance name of u_lvs
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) n_cst_lvsrv_datasource

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_lvsrv_datasource.
This instance is named inv_datasource.
Examples This example calls the of_SetDataSource function:
lv_1.of_SetDataSource(TRUE)

247
u_lvs

of_SetLogicalUnitOfWork
Description Enables or disables n_cst_luw, which provides the logical unit of work service.
Access Public
Syntax instancename.of_SetLogicalUnitOfWork ( boolean )
Argument Description
instancename Instance name of u_lvs
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) n_cst_luw

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_luw. This instance is
named inv_luw. If you do not enable n_cst_luw, u_lvs enables it automatically.
Examples This example calls the of_SetLogicalUnitOfWork function:
lv_1.of_SetLogicalUnitOfWork(TRUE)

of_SetRMBMenu
Description Enables or disables right mouse button support for m_lvs, the ListView popup
menu.
Access Public
Syntax instancename.of_SetRMBMenu ( boolean )
Argument Description
instancename Instance name of u_lvs
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) right mouse button support

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetRMBMenu function:
lv_1.of_SetRMBMenu(TRUE)

of_SetSort
Description Enables or disables n_cst_lvsrv_sort, which provides the ListView sort service.
Access Public
Syntax instancename.of_SetSort ( boolean )

248
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_lvs
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) the ListView sort service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_lvsrv_sort. This
instance is named inv_sort.
Examples This example calls the of_SetSort function:
lv_1.of_SetSort(TRUE)

of_SetUpdateable
Description Specifies whether the ListView is updatable and should be included in the
default save process.
Access Public
Syntax instancename.of_SetUpdateable ( boolean )
Argument Description
instancename Instance name of u_lvs
boolean Boolean indicating whether the ListView is updatable. All
updatable ListViews are included in the default save processing

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to enable default save processing for ListViews (by default,
they are not updatable).
Examples This example calls the of_SetUpdateable function:
lv_1.of_SetUpdateable(TRUE)

of_SetUpdateRequestor
Description Creates a reference to the object requesting an update within a logical unit of
work.
Access Public
Syntax instancename.of_SetUpdateRequestor ( requestor )

249
u_lvs

Argument Description
instancename Instance name of u_lvs
requestor PowerObject containing the object requesting the update

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example calls the of_SetUpdateRequestor function:
...
lv_1.of_SetUpdateRequestor(lv_1)
...

of_Update
Description Saves all rows in the DataStore associated with the ListView.
Access Public
Syntax instancename.of_Update ( accept, resetflag {, requestor } )
Argument Description
instancename Instance name of u_lvs
accept Boolean indicating whether the Update function performs an
AcceptText before saving rows to the database
resetflag Boolean indicating whether the Update function resets the update
flags
requestor PowerObject containing the requestor object

Return value Integer. Returns 1 if the update succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update processing, extend
the pfc_Update event.
Examples This example is from the n_cst_luw of_Update function:
...
If lb_defined Then
li_rc = lpo_tocheck.Function Dynamic of_Update &
(ab_accepttext, ab_resetflag, &
lpo_updaterequestor)
If li_rc < 0 Then Return -1
Continue
End If
...

250
 Chapter 6 Standard Visual User Objects

of_UpdatePrep
Description Calls the pfc_UpdatePrep event, which allows you to code additional update
preparation logic.
Access Public
Syntax instancename.of_UpdatePrep ( )
Argument Description
instancename Instance name of u_lvs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the n_cst_luw of_UpdatePrep function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_UpdatePrep ()
If li_rc < 0 Then Return -1
Continue
End If
...

of_UpdatesPending
Description Determines if there are updates pending in the ListView.
Access Public
Syntax instancename.of_UpdatesPending ( )
Argument Description
instancename Instance name of u_lvs

Return value Integer. Returns values as follows:

• 1 Updates are pending
• 0 No updates pending
• -1 An error occurred
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize pending updates
processing, extend the pfc_UpdatesPending event.

251
u_lvs

Examples This example calls the of_UpdatesPending function:

...
If lb_defined Then
la_rc = lpo_tocheck.Dynamic of_UpdatesPending()
...

of_Validation
Description Performs validation on the ListView data source.
Access Public
Syntax instancename.of_Validation ( )
Argument Description
instancename Instance name of u_lvs

Return value Integer. Returns 1 if the function succeeds and -1 if a validation error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize validation processing,
extend the pfc_Validation event.
Examples This example calls the of_Validation function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_Validation()
...

252
 Chapter 6 Standard Visual User Objects

u_mle
Description MultiLineEdit visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
MultiLineEdit. U_mle event scripts provide integration with PFC menus.
Additionally, u_mle supports:
• Cut, copy, paste, clear, and select all These are triggered
automatically by the message router.
• Popup menu support The ContextMenu event enables you to use the
right mouse button to perform editing actions. To disable right mouse
button support, set ib_rmbmenu to FALSE in the MultiLineEdit’s
Constructor event.
• Autoselect This means that text is selected when a user tabs to the edit
mask. To disable autoselect, set ib_autoselect to FALSE in the
MultiLineEdit’s Constructor event.
See also m_edit

253
u_mle

Instance variables
U_mle includes instance variables:
Instance variable Description Data type Access Usage
ib_autoselect Indicates whether PFC Boolean Protected Set this to TRUE to
selects text enable autoselect (default
automatically when the is FALSE)
control receives focus
ib_rmbmenu Indicates whether the Boolean Protected Set this to FALSE to
m_edit menu displays disable right mouse
when the user presses button support (default is
the right mouse button TRUE)

Events
U_mle includes precoded events:
ContextMenu pfc_Paste
GetFocus pfc_PreRmbMenu
pfc_Clear pfc_SelectAll
pfc_Copy pfc_Undo
pfc_Cut RButtonUp

ContextMenu
Description Displays the m_edit popup menu.
Usage This event executes when the user releases the right mouse button over a
control based on u_mle.

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

pfc_Clear
Description Deletes selected text.
Return value Integer. Returns the number of characters deleted if the event succeeds and -1
if an error occurs.

254
 Chapter 6 Standard Visual User Objects

Usage The message router calls this event when a MultiLineEdit based on u_mle has
focus and the user selects Edit>Clear from the menu bar.

pfc_Copy
Description Copies selected text to the clipboard.
Return value Integer. Returns the number of characters copied if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a MultiLineEdit based on u_mle has
focus and the user selects Edit>Copy from the menu bar. This event is also
called by the m_edit popup menu.

pfc_Cut
Description Deletes selected text and stored it on the clipboard.
Return value Integer. Returns the number of characters removed if the event succeeds and -
1 if an error occurs.
Usage The message router calls this event when a MultiLineEdit based on u_mle has
focus and the user selects Edit>Cut from the menu bar. This event is also called
by the m_edit popup menu.

pfc_Paste
Description Inserts (pastes) the contents of the clipboard at the insertion point.
Return value Integer. Returns the number of characters that were pasted if the event succeeds
and -1 if an error occurs.
Usage The message router calls this event when a MultiLineEdit based on u_mle has
focus and the user selects Edit>Paste from the menu bar. This event is also
called by the m_edit popup menu.

pfc_PreRmbMenu
Description User event allowing you to modify m_edit contents before display.
Syntax instancename.EVENT pfc_PreRmbMenu ( editmenu )
Argument Description
instancename Instance name of u_mle
editmenu M_edit variable containing the popup menu to be displayed
(passed by reference)

255
u_mle

Usage Add logic to this event to selectively enable and disable m_edit menu items.

pfc_SelectAll
Description Selects all text in the MultiLineEdit.
Return value Integer. Returns the number of characters selected if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a MultiLineEdit based on u_mle has
focus and the user selects Edit>Select All from the menu bar. This event is also
called by the m_edit popup menu.

pfc_Undo
Description Cancels the last change to the MultiLineEdit, restoring the text to the content
before the last change.
Return value Integer. Returns 1 if the event succeeds 0 and -1 if an error occurs.
Usage The message router calls this event when a MultiLineEdit based on u_mle has
focus and the user selects Edit>Undo.

RButtonUp
Description Empty user event. PFC code previously assigned to this event is now in the
ContextMenu event.
Usage This event executes when the user releases the right mouse button over a
control based on u_mle.

Functions
U_mle includes precoded object functions:
of_GetParentWindow
of_MessageBox

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )

256
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_mle
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
Usage The u_mle GetFocus event calls this function.
Examples This example is from the u_mle GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event pfc_ControlGotFocus &
(this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_mle
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to
display on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!

257
u_mle

Argument Description
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed
in the enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be
the default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in MultiLineEdits.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’mle_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

258
 Chapter 6 Standard Visual User Objects

u_oc
Description OLE visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder OLE
2.0 window control. U_oc event scripts provide integration with PFC menus.
Additionally, u_oc supports:
• Cut, copy, paste, paste special, clear, and select all These are
triggered automatically by the message router.
• Popup menu support The ContextMenu event enables you to use the
right mouse button to perform editing actions. To disable right mouse
button support, set ib_rmbmenu to FALSE in the OLE control’s
Constructor event.
• Object actions U_oc provides events to activate the object (inplace and
offsite), update links, and insert an object into the OLE control.
See also m_oc

259
u_oc

Instance variables
U_oc contains one instance variable:
Instance variable Description Data type Ancestry Usage
ib_rmbmenu Indicates whether the Boolean Protected Set this to FALSE to
m_oc menu displays when disable right mouse
the user presses the right button support
mouse button

Events
U_oc includes precoded events:
ContextMenu pfc_OpenObject
GetFocus pfc_Paste
pfc_Clear pfc_PasteSpecial
pfc_Copy pfc_PreRmbMenu
pfc_Cut pfc_UpdateLinks
pfc_EditObject RButtonUp
pfc_InsertObject

ContextMenu
Description Displays the m_oc popup menu.
Usage This event executes when the user releases the right mouse button over a
control based on u_oc.

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

pfc_Clear
Description Deletes the OLE object.
Return value Integer. Returns 0 if the event succeeds and -9 if an error occurs.

260
 Chapter 6 Standard Visual User Objects

Usage The message router calls this event when an OLE control based on u_oc has
focus and the user selects Edit>Clear from a menu that descends from the PFC
m_master menu.

pfc_Copy
Description Copies the OLE object to the clipboard.
Return value Integer. Returns one of the following values:
0 Success
-1 Container is empty
-2 Copy failed
-9 Other error
Usage The message router calls this event when an OLE control based on u_oc has
focus and the user selects Edit>Copy from a menu that descends from the PFC
m_master menu. This event is also called by the m_oc popup menu.

pfc_Cut
Description Deletes the selected item or text and stores it on the clipboard.
Return value Integer. Returns values as follows:
-1 Container is empty
-2 Cut failed
-9 Other error
Usage The message router calls this event when an OLE control based on u_oc has
focus and the user selects Edit>Cut. This event is also called by the m_oc
popup menu.

pfc_EditObject
Description Activates the object in place.
Return value Integer. Returns values as follows:
0 Success
-1 Control is empty
-2 Invalid verb for the object
-3 Verb not implemented by the object
-4 No verbs supported by the object
-5 Object can’t execute the verb now
-9 Other error
Usage Call this event to activate an object in-place.

261
u_oc

The message router calls this event when an OLE control based on u_oc has
focus and the user selects Edit>Object>Edit from a menu that descends from
the PFC m_master menu. This event is also called by the m_oc popup menu.

pfc_InsertObject
Description Displays the Insert Object dialog box, which allows you to insert an object into
the OLE control.
Return value Integer. Returns values as follows:
0 Success
1 The user canceled out of the dialog box
-9 Other error
Usage Call this event to insert an object into the OLE control.
The message router triggers this event when an OLE control based on u_oc has
focus and the user selects Edit>Insert Object from a menu that descends from
the PFC m_master menu.

pfc_OpenObject
Description Activates the object offsite.
Return value Integer. Returns values as follows:
0 Success
-1 Control is empty
-2 Invalid verb for the object
-3 Verb not implemented by the object
-4 No verbs supported by the object
-5 Object can’t execute the verb now
-9 Other error
Usage Call this event to activate an object offsite.
The message router calls this event when an OLE control based on u_oc has
focus and the user selects Edit>Object>Open from a menu that descends from
the PFC m_master menu. This event is also called by the m_oc popup menu.

pfc_Paste
Description Inserts (pastes) the contents of the clipboard at the insertion point.
Return value Integer. Returns values as follows:
0 Success

262
 Chapter 6 Standard Visual User Objects

-1 No data or clipboard contents cannot be embedded

-9 Other error
Usage The message router calls this event when an OLE control based on u_oc has
focus and the user selects Edit>Paste from a menu that descends from the PFC
m_master menu. This event is also called by the m_oc popup menu.

pfc_PasteSpecial
Description Displays a standard OLE 2.0 dialog box allowing the user to choose whether
to embed or link the OLE object on the clipboard when pasting it in the
specified control. Embedding is the equivalent of calling the Paste function and
linking is the same as calling PasteLink.
Return value Integer. Returns values as follows:
0 Success
1 User canceled out of the OLE 2.0 dialog box
-1 No data found
-9 Other error
Usage The message router calls this event when an OLE control based on u_oc has
focus and the user selects Edit>Paste Special from a menu that descends from
the PFC m_master menu.

pfc_PreRmbMenu
Description User event allowing you to modify m_oc contents prior to display.
Syntax instancename.Event pfc_PreRmbMenu ( editmenu )
Argument Description
instancename Instance name of u_oc
editmenu M_oc variable containing the popup menu to be displayed (passed
by reference)

Usage Optionally add logic to this event to selectively enable and disable m_oc menu
items.

pfc_UpdateLinks
Description Attempts to find a file linked to an OLE container. If the linked file is not found,
a dialog tells the user and lets them bring up a second dialog for find the file or
changing the link.
Return value Integer. Returns 0 if the event succeeds and -1 if an error occurs.

263
u_oc

Usage Call this event to update links for an OLE control.

The message router triggers this event when an OLE control based on u_oc has
focus and the user selects Edit>Update Links from a menu that descends from
the PFC m_master menu.

RButtonUp
Description Empty user event. PFC code previously assigned to this event is now in the
ContextMenu event.
Usage This event executes when the user releases the right mouse button over a
control based on u_oc.

Functions
U_oc includes precoded object functions:
of_GetParentWindow
of_MessageBox

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_oc
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
Usage The u_oc GetFocus event calls this function.
Examples This example is from the u_oc GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event pfc_ControlGotFocus &

264
 Chapter 6 Standard Visual User Objects

(this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_oc
id String specifying an ID for the message
title String specifying the title of the OLEControl
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in OLE controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:

265
u_oc

of_Messagebox(’oc_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

266
 Chapter 6 Standard Visual User Objects

u_p
Description Picture visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder Picture
control. U_p event scripts provide integration with PFC menus.
See also u_pb
u_phl
u_plb

Events
U_p includes a precoded event script:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_p includes precoded object functions:
of_GetParentWindow
of_MessageBox

267
u_p

of_GetParentWindow
Description Returns a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_p
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_p GetFocus event calls this function.
Examples This example is from the u_p GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus(this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_p
id String specifying an ID for the message
title String specifying the title of the Picture control
message String specifying the message text

268
 Chapter 6 Standard Visual User Objects

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in Picture controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’p_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

269
u_pb

u_pb
Description PictureButton visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
PictureButton control. U_pb event scripts provide integration with PFC menus.
See also u_cb
u_p

Events
U_pb includes a precoded event script:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_pb includes precoded object functions:
of_GetParentWindow
of_MessageBox

270
 Chapter 6 Standard Visual User Objects

of_GetParentWindow
Description Returns a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_pb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_pb GetFocus event calls this function.
Examples This example is from the u_pb GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_pb
id String specifying an ID for the message
title String specifying the title of the PictureButton
message String specifying the message text

271
u_pb

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in PictureButtons.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’pb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

272
 Chapter 6 Standard Visual User Objects

u_phl
Description PictureHyperlink visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
PictureHyperlink control. U_phl event scripts provide integration with PFC
menus.
See also u_p
u_sth

Events
U_phl includes a precoded event script:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_phl includes precoded object functions:
of_GetParentWindow
of_MessageBox

273
u_phl

of_GetParentWindow
Description Returns a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_phl
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_phl GetFocus event calls this function.
Examples This example is from the u_phl GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_phl
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

274
 Chapter 6 Standard Visual User Objects

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior for PictureHyperlink
controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’phl_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

275
u_plb

u_plb
Description PictureListBox user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
PictureListBox. U_plb event scripts provide integration with PFC menus.
See also u_lb

Events
U_plb includes precoded events:
GetFocus pfc_SelectAll
pfc_InvertSelection

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

pfc_InvertSelection
Description Inverts the rows selected in the PictureListBox. Unselected rows become
selected; selected rows are cleared.
Return value Integer. Returns the number of selected rows if the event succeeds and 0 if this
is an invalid operation.

276
 Chapter 6 Standard Visual User Objects

Usage The message router calls this event when the user selects Edit>Invert Selection
from the menu bar.

pfc_SelectAll
Description Selects all rows in the PictureListBox.
Return value Integer. Returns the number of selected rows if the event succeeds and 0 if this
is an invalid operation.
Usage The message router calls this event when the user selects Edit>Select All from
the menu bar.

Functions
U_plb includes precoded object functions:
of_GetParentWindow of_MessageBox
of_GetSelected

of_GetParentWindow
Description Returns a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_plb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_plb GetFocus event calls this function.
Examples This example is from the u_plb GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &

277
u_plb

pfc_ControlGotFocus(this)
END IF
END IF

of_GetSelected
Description Populates a passed object with all selected entries in the PictureListBox.
Access Public
Syntax instancename.of_GetSelected ( selecteditems )
Argument Description
instancename Instance name of u_plb
selecteditems N_cst_itemattrib array into which the function places selected
items (passed by reference)

Return value Integer. Returns the number of selected items if the function succeeds and 0 if
this is an invalid operation.
Usage Call this function to access selected items.
Examples This example calls the of_GetSelected function:
n_cst_itemattrib lnv_items[ ]
Integer li_selected

li_selected = plb_list.of_GetSelected(lnv_items)
IF li_selected = 0 THEN
MessageBox("PLB", "Invalid PLB operation")
Return
END IF
// Logic to read lnv_items follows
...

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_plb
id String specifying an ID for the message
title String specifying the title of the PictureListBox
message String specifying the message text

278
 Chapter 6 Standard Visual User Objects

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in PictureListBoxes.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’plb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

279
u_rb

u_rb
Description RadioButton visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
RadioButton control. U_rb event scripts provide integration with PFC menus.
See also u_cbx

Events
U_rb includes a precoded event script:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_rb includes precoded object functions:
of_GetParentWindow
of_MessageBox

280
 Chapter 6 Standard Visual User Objects

of_GetParentWindow
Description Returns a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_rb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_rb GetFocus event calls this function.
Examples This example is from the u_rb GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus(this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_rb
id String specifying an ID for the message
title String specifying the title of the RadioButton
message String specifying the message text

281
u_rb

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in RadioButtons.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’rb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

282
 Chapter 6 Standard Visual User Objects

u_rte
Description RichTextEdit visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master. U_rte also uses:
F_SetFileSrv
M_edit
N_cst_filesrv
N_cst_rtefind
N_cst_textstyleattrib
S_printdlgattrib
Usage Use this visual user object in windows instead of the standard PowerBuilder
RichTextEdit control. U_rte event scripts provide integration with PFC menus.

U_rte is a window control

U_rte is a subclassed version of the RichTextEdit window control. It is not a
DataWindow control using the Rich Text presentation style.

283
u_rte

U_rte is fully integrated with menus that descend from PFC’s m_master menu,
including events that respond to the appropriate menu items. Additionally,
u_rte includes right mouse button support. If the user clicks the right mouse
button over a u_rte-based RichTextEdit control, the m_edit menu displays.
M_edit allows you to perform basic editing functions.
To use u_rte:
1 Place a u_rte user object in your window.
2 (Optional) Enable the find service:
rte_doc.of_SetFind(TRUE)
3 Associate a document with the RichTextEdit control. This example uses
the of_OpenDocument function to display a dialog box prompting the user
for the file:
String ls_document

rte_doc.of_OpenDocument(ls_document)
4 Call additional u_rte events and functions, as needed.
For more information on the RichTextEdit control, see the PowerBuilder
User’s Guide.
See also n_cst_rtefind
u_dw

Instance variables
U_rte includes instance variables:
Instance variable Description Data type Access Usage
ib_continuouspages Indicates whether Boolean Protected Use of_GetContinuousPages and
continuous page of_SetContinuousPages to access
numbering is enabled
when printing
ib_ignorefileexists Indicates whether u_rte Boolean Protected Use of_GetIgnoreFileExists and
asks the user to confirm of_SetIgnoreFileExists to access
when saving a file that
already exists
ib_ongoingfind Indicates whether a find Boolean Protected Internal
operation is in progress

284
 Chapter 6 Standard Visual User Objects

Instance variable Description Data type Access Usage

ib_rmbmenu Indicates whether right Boolean Protected When this is TRUE, PFC displays
mouse button support is the m_edit popup menu when a
enabled user presses the right mouse
button over this control
To disable right mouse button
support, set this variable to
FALSE in the control’s
Constructor event
il_currentinstance Tracks continuous Long Protected Internal
printing
il_currentprintpage Tracks current page Long Protected Internal
number
il_startpagenumber Specifies the first page Boolean Protected Use of_GetStartPageNumber and
that receives a page of_SetStartPageNumber to
number access
inv_filesrv Reference variable for n_cst_filesrv Protected Internal
the file service
inv_find Structure containing n_cst_rtefind Public Internal
information used in find
and replace processing
is_filename Name of the current file String Protected Use the of_GetFileName and
of_SetFileName functions to
access
is_pageinputfield Specifies the name of String Protected Use of_GetPageInputField and
the field that PFC uses of_SetPageInputField to access
to place the page
number

Events
U_rte includes precoded event scripts:
Destructor pfc_PreRmbMenu
FileExists pfc_PreviousPage
GetFocus pfc_Print
pfc_Clear pfc_PrintDlg
pfc_Copy pfc_PrintImmediate
pfc_Cut pfc_PrintPreview
pfc_FindDlg pfc_ReplaceDlg
pfc_FirstPage pfc_Ruler

285
u_rte

pfc_InsertFile pfc_Save
pfc_InsertPicture pfc_SaveAs
pfc_LastPage pfc_SelectAll
pfc_NextPage pfc_Undo
pfc_Open PrintHeader
pfc_Paste RButtonUp
pfc_PrePrintDlg

Destructor
Description Destroys the inv_filesrv instance.
Usage This event executes when the u_rte-based control is destroyed or the window
closes.

FileExists
Description Prompts the user that the file to be saved already exists. If the
ib_ignorefileexists instance variable is TRUE, PFC does not prompt the user.
Usage This event executes when the user saves a file that already exists.

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

pfc_Clear
Description Deletes selected text.
Return value Integer. Returns the number of characters deleted if the event succeeds and -1
if an error occurs.
Usage This event is triggered when a RichTextEdit control based on u_rte has focus
and the user selects Edit>Clear from the menu bar of a menu descended from
the PFC m_master menu.

pfc_Copy
Description Copies selected text to the clipboard.

286
 Chapter 6 Standard Visual User Objects

Return value Integer. Returns the number of characters copied if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects Edit>Copy from the menu bar of a menu
descended from the PFC m_master menu. This event is also called by the
m_edit popup menu.

pfc_Cut
Description Deletes selected text and stores it on the clipboard.
Return value Integer. Returns the number of characters removed if the event succeeds and -
1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects Edit>Cut from the menu bar of a menu descended
from the PFC m_master menu. This event is also called by the m_edit popup
menu.

pfc_FindDlg
Description Displays a Find dialog box by calling the n_cst_rtefind service’s pfc_FindDlg
event.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called when the user selects Edit>Find from the menu bar of a
menu descended from the PFC m_master menu.

pfc_FirstPage
Description Scrolls to the first page.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects View>First Page from the menu bar of a menu
descended from the PFC m_master menu.

pfc_InsertFile
Description Displays a dialog box prompting the user to choose a file to be copied at the
current insertion point.

287
u_rte

Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects Insert>File from the menu bar of a menu
descended from the PFC m_master menu.

pfc_InsertPicture
Description Displays a dialog box prompting the user to choose a bitmap to be copied at the
current insertion point.
Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects Insert>Picture from the menu bar of a menu
descended from the PFC m_master menu.

pfc_LastPage
Description Scrolls to the last page.
Return value Integer. Returns the number of the last page if the event succeeds and -1 if an
error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects View>Last Page from the menu bar of a menu
descended from the PFC m_master menu.

pfc_NextPage
Description Scrolls to the next page.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects View>Next Page from the menu bar of a menu
descended from the PFC m_master menu.

pfc_Open
Description Prompts the user for a file to open and places the specified file in the
RichTextEdit control. If there is already a document in the control, the function
prompts the user to save it.

288
 Chapter 6 Standard Visual User Objects

Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects File>Open from the menu bar of a menu
descended from the PFC m_master menu.

pfc_Paste
Description Inserts (pastes) the contents of the clipboard at the insertion point.
Return value Integer. Returns the number of characters that were pasted if the event succeeds
and -1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects Edit>Paste from the menu bar of a menu
descended from the PFC m_master menu.

pfc_PrePrintDlg
Description Empty user event allowing you to modify the properties passed to the
n_cst_platform of_PrintDlg function.
Syntax instancename.EVENT pfc_PrePrintDlg ( attributes )
Argument Description
instancename Instance name of u_rte
attributes S_printdlgattrib variable into which the event places additional
printing information. This argument is accessed through the
astr_printdlg argument (passed by reference)

Usage This event is called by pfc_PrintDlg before calling the n_cst_platform

of_PrintDlg function.
You can use this event to modify or extend the information passed in the
s_printdlgattrib structure.
Examples This example contains code you might add to the pfc_PrePrintDlg event:
// Default copies to 1
astr_printdlg.l_copies = 1

pfc_PreRmbMenu
Description User event allowing you to modify m_edit contents before display.
Syntax instancename.EVENT pfc_PreRmbMenu ( editmenu )

289
u_rte

Argument Description
instancename Instance name of u_rte
editmenu M_edit variable containing the popup menu to be displayed
(passed by reference)

Usage You can add logic to this event to selectively enable and disable m_edit menu
items.

pfc_PreviousPage
Description Scrolls to the Previous page.
Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects View>Previous Page from the menu bar of a
menu descended from the PFC m_master menu.

pfc_Print
Description Calls the pfc_PrintDlg function and prints the RichTextEdit control, as
specified in the Print dialog box.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is triggered when the RichTextEdit control has focus and the user
selects File>Print from the menu bar of a menu descended from the PFC
m_master menu.

pfc_PrintDlg
Description Initializes the s_printdlgattrib structure with the RichTextEdit control’s current
settings, displays the Print dialog box by calling the n_cst_platform
of_PrintDlg function, and resets the settings, as specified by the user.
Syntax instancename.EVENT pfc_PrintDlg ( attributes )
Argument Description
instancename Instance name of u_rte
attributes S_printdlgattrib variable into which the event places printing
information. This argument is accessed through the astr_printdlg
argument (passed by reference)

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.

290
 Chapter 6 Standard Visual User Objects

Usage This event is called by the pfc_Print event.

pfc_PrintImmediate
Description Prints the current RichTextEdit control without displaying the Print dialog box.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called when the RichTextEdit control has focus and the user
selects File>Print Immediate from the menu bar of a menu descended from the
PFC m_master menu.

pfc_PrintPreview
Description Toggles between print preview and edit mode.
Return value Boolean. Returns TRUE if the RichTextEdit control has been placed in
preview mode and FALSE if it has been placed in edit mode.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects File>Print Preview from the menu bar of a menu
descended from the PFC m_master menu.

pfc_ReplaceDlg
Description Displays a Replace dialog box by calling the n_cst_rtefind service’s
pfc_ReplaceDlg event.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called when the user selects View>Replace from the menu bar of
a menu descended from the PFC m_master menu.

pfc_Ruler
Description Toggles display of the ruler and tab bar.
Return value Boolean. Returns TRUE if the ruler has been displayed and FALSE if it has
been hidden.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects View>Ruler from the menu bar of a menu
descended from the PFC m_master menu.

291
u_rte

pfc_Save
Description Saves the current contents of the RichTextEdit control. If the current contents
is not associated with a file, the function displays a dialog box prompting the
user to specify a filename.
Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects File>Save from the menu bar of a menu
descended from the PFC m_master menu.

pfc_SaveAs
Description Saves the current contents of the RichTextEdit control, prompting the user to
specify a filename.
Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects File>Save As from the menu bar of a menu
descended from the PFC m_master menu.

pfc_SelectAll
Description Selects all text in the RichTextEdit control.
Return value Integer. Returns the number of characters selected if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects Edit>Select All from the menu bar of a menu
descended from the PFC m_master menu.

pfc_Undo
Description Cancels the last change to the RichTextEdit control, restoring the text to the
content before the last change.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The message router calls this event when a RichTextEdit control based on u_rte
has focus and the user selects Edit>Undo from the menu bar of a menu
descended from the PFC m_master menu.

292
 Chapter 6 Standard Visual User Objects

PrintHeader
Description Sets page numbers for printing.
Usage This event executes when you print the RichTextEdit control.

RButtonUp
Description Displays the m_edit popup menu.
Usage This event executes when the user releases the right mouse button over a
control based on u_rte.

Functions
U_rte includes precoded object functions:
of_GetContinuousPages of_SetFileName
of_GetFileName of_SetFind
of_GetIgnoreFileExists of_SetIgnoreFileExists
of_GetPageInputField of_SetPageInputField
of_GetParentWindow of_SetStartPageNumber
of_GetStartPageNumber of_SetTextStyleBold
of_GetTextStyle of_SetTextStyleItalic
of_InsertDocument of_SetTextStyleStrikeout
of_InsertPicture of_SetTextStyleSubscript
of_MessageBox of_SetTextStyleSuperscript
of_OpenDocument of_SetTextStyleUnderline
of_SetContinuousPages

of_GetContinuousPages
Description Reports whether PFC uses continuous page numbering when the RichTextEdit
control is shared to a DataWindow.
Access Public
Syntax instancename.of_GetContinuousPages ( )
Argument Description
instancename Instance name of u_rte

293
u_rte

Return value Boolean. Returns TRUE if continuous page numbering is enabled and FALSE
if it is not.
Examples This example calls the of_GetContinuousPages function:
IF rte_doc.of_GetContinuousPages() THEN
MessageBox("RTE", &
"Continuous page numbering is enabled")
ELSE
MessageBox("RTE", &
"Continuous page numbering is disabled")
END IF

of_GetFileName
Description Retrieves the name of the file associated with the RichTextEdit control.
Access Public
Syntax instancename.of_GetFileName ( )
Argument Description
instancename Instance name of u_rte

Return value String. Returns the current filename or an empty string if one has not been set
with the of_SetFilename function.
Examples This example calls the of_GetFileName function:
String ls_filename

ls_filename = rte_doc.of_GetFileName()
MessageBox("RTE", "Filename is " + ls_filename)

of_GetIgnoreFileExists
Description Reports whether PFC displays a message before overwriting an existing file.
Access Public
Syntax instancename.of_GetIgnoreFileExists ( )
Argument Description
instancename Instance name of u_rte

Return value Boolean. Returns TRUE if PFC displays no message before overwriting an
existing file and FALSE if PFC prompts the user before overwriting an existing
file.

294
 Chapter 6 Standard Visual User Objects

Examples This example calls the of_GetIgnoreFileExists function:

IF rte_doc.of_GetIgnoreFileExists() THEN
MessageBox("RTE", "No prompt before overwriting")
ELSE
MessageBox("RTE", "PFC prompts before overwriting")
END IF

of_GetPageInputField
Description Retrieves the name of the field PFC uses to place the page number.
Access Public
Syntax instancename.of_GetPageInputField ( )
Argument Description
instancename Instance name of u_rte

Return value String. Returns the name of the field PFC uses to place the page number.
Examples This example calls the of_GetPageInputField function:
String ls_field

ls_field = rte_doc.of_GetPageInputField( )
MessageBox("RTE", "Page input field is " + ls_field)

of_GetParentWindow
Description Returns the parent of the current window.
Access Public
Syntax instancename.of_GetParentWindow ( parent )
Argument Description
instancename Instance name of u_rte
parent Window variable into which the function places the parent of the
current window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the GetFocus event.
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN

295
u_rte

of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_GetStartPageNumber
Description Retrieves the number of the page on which page numbers are initially
displayed. For example, if this value is 3, the first two pages do not display
page numbers and the third page displays a 3.
Access Public
Syntax instancename.of_GetStartPageNumber ( )
Argument Description
instancename Instance name of u_rte

Return value Long. Returns the number of the page upon which page numbers are initially
displayed
Examples This example calls the of_GetStartPageNumber function:
Long ll_return

ll_return = rte_doc.of_GetStartPageNumber()
MessageBox("RTE", &
"Start page number is " + String(ll_return))

of_GetTextStyle
Description Calculates all text style settings for the currently selected text.
Access Public
Syntax instancename.of_GetTextStyle ( textstyle )
Argument Description
instancename Instance name of u_rte
textstyle N_cst_textstyleattrib instance into which the function places text
style settings (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to determine text style settings for the currently selected text.

296
 Chapter 6 Standard Visual User Objects

Examples This example calls the of_GetTextStyle function:

n_cst_textstyleattrib lnv_style
Integer li_return
n_cst_conversion lnv_conv

li_return = rte_doc.of_GetTextStyle &

(lnv_style)
IF li_return = -1 THEN
MessageBox("RTE", "GetTextStyle error")
ELSE
MessageBox("RTE", &
+ "Text styles are as follows:~r~n" &
+ "Bold: " &
+lnv_conv.of_String(lnv_style.ib_bold) &
+ "~r~nItalic: " &
+ lnv_conv.of_String(lnv_style.ib_italic) &
+ "~r~nStrikeout: " &
+ lnv_conv.of_String(lnv_style.ib_strikeout) &
+ "~r~nSubscript: " &
+ lnv_conv.of_String(lnv_style.ib_subscript) &
+ "~r~nSuperscript: " &
+ lnv_conv.of_String(lnv_style.ib_superscript) &
+ "~r~nUnderlined: " &
+ lnv_conv.of_String(lnv_style.ib_underlined))
END IF

of_InsertDocument
Description Displays the Insert File dialog box, prompting the user for the name of the file
to copy into the current document, placing it at the current insertion point.
Access Public
Syntax instancename.of_InsertDocument ( filename )
Argument Description
instancename Instance name of u_rte
filename String into which the function places the fully qualified name of
the file inserted into the document

Return value Integer. Returns 1 if the function succeeds, 0 if the user cancels out of the
dialog box, and -1 if an error occurs.
Examples This example calls the of_InsertDocument function:
Integer li_return
String ls_filename

297
u_rte

li_return = rte_doc.of_InsertDocument(ls_filename)
IF li_return = -1 THEN
MessageBox("RTE", "Insert file error")
ELSE
gnv_app.of_GetFrame().SetMicroHelp &
("Inserted file: " + String(ls_filename))
END IF

of_InsertPicture
Description Displays the Insert Picture dialog box, prompting the user for the name of the
bitmap to copy into the current document, placing it at the current insertion
point.
Access Public
Syntax instancename.of_InsertPicture ( bitmap )
Argument Description
instancename Instance name of u_rte
bitmap String into which the function places the fully qualified name of
the bitmap inserted into the document

Return value Integer. Returns 1 if the function succeeds, 0 if the user cancels out of the
dialog box, and -1 if an error occurs.
Examples This example calls the of_InsertPicture function:
Integer li_return
String ls_filename

li_return = rte_doc.of_InsertPicture(ls_filename)
IF li_return = -1 THEN
MessageBox("RTE", "Insert file error")
ELSE
gnv_app.of_GetFrame().SetMicroHelp &
("Inserted file: " + String(ls_filename))
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )

298
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_rte
id String specifying an ID for the message
title String specifying the title of the RichTexEdit control
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in RichTextEdit
controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’rte_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

299
u_rte

of_OpenDocument
Description Displays the Open dialog box, prompting the user for the name of the file to
place into the RichTextEdit control. This function prompts you before
discarding the control’s current contents.
Access Public
Syntax instancename.of_OpenDocument ( filename )
Argument Description
instancename Instance name of u_rte
filename String into which the function places the fully qualified name of
the selected file

Return value Integer. Returns 1 if the function succeeds, 0 if the user cancels out of the
dialog box, and -1 if an error occurs.
Examples This example calls the of_OpenDocument function:
String ls_filename
Integer li_return

li_return = rte_doc.of_OpenDocument(ls_filename)
IF li_return = -1 THEN
MessageBox("RTE", "File open error")
Return
END IF

of_SetContinuousPages
Description Specifies whether PFC uses continuous page numbering when the
RichTextEdit control is shared to a DataWindow.
Access Public
Syntax instancename.of_SetContinuousPages ( boolean )
Argument Description
instancename Instance name of u_rte
boolean Boolean specifying whether continuous page numbering is
used (TRUE) or not (FALSE)

Return value None

Examples This example calls the of_SetContinuousPages function:
rte_doc.of_SetContinuousPages(TRUE)

300
 Chapter 6 Standard Visual User Objects

of_SetFileName
Description Specifies the name of the file associated with the RichTextEdit control.
Access Public
Syntax instancename.of_SetFileName ( filename )
Argument Description
instancename Instance name of u_rte
filename String specifying the fully qualified name of the file displayed in
the RichTextEdit control

Return value None

Usage The of_OpenDocument function automatically specifies the name of the file
associated with the RichTextEdit control. But if you open a document with
of_InsertDocument or the PowerScript InsertDocument function, you should
call this function to set the filename.
Examples This example calls the of_SetFileName function:
Integer li_return
String ls_filename

li_return = rte_doc.of_InsertDocument(ls_filename)
IF li_return = -1 THEN
MessageBox("RTE", "Insert file error")
ELSE
rte_doc.of_SetFileName(ls_filename)
END IF

of_SetFind
Description Enables or disables n_cst_rtefind, which provides the find and replace service.
Access Public
Syntax instancename.of_SetFind ( boolean )
Argument Description
instancename Instance name of u_rte
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) the find and replace service

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_rtefind. This instance
is named inv_find.

301
u_rte

Examples This example calls the of_SetFind function to enable the RichTextEdit find and
replace service:
rte_doc.of_SetFind(TRUE)

of_SetIgnoreFileExists
Description Specifies whether PFC displays a message before overwriting an existing file.
Access Public
Syntax instancename.of_SetIgnoreFileExists ( boolean )
Argument Description
instancename Instance name of u_rte
boolean Boolean specifying whether PFC displays a message before
overwriting an existing file (TRUE) or not (FALSE)

Return value None

Examples This example calls the of_SetIgnoreFileExists function:
String ls_filename
Integer li_return

li_return = &
rte_doc.of_OpenDocument(ls_filename)
IF li_return = -1 THEN
MessageBox("RTE", "File open error")
Return
ELSE
rte_doc.of_SetIgnoreFileExists(TRUE)
END IF

of_SetPageInputField
Description Specifies the name of the field PFC uses to place the page number.
Access Public
Syntax instancename.of_SetPageInputField ( )
Argument Description
instancename Instance name of u_rte

Return value None

Examples This example calls the of_SetPageInputField function:

302
 Chapter 6 Standard Visual User Objects

rte_doc.of_SetContinuousPages(TRUE)
rte_doc.of_SetPageInputField("PAGE NUMBER")
rte_doc.of_SetStartPageNumber(2)

of_SetStartPageNumber
Description Specifies the number of the page upon which page numbers are initially
displayed. For example, if this value is 3, the first two pages do not display
page numbers and the third page displays a 3.
Access Public
Syntax instancename.of_SetStartPageNumber ( firstpage )
Argument Description
instancename Instance name of u_rte
firstpage Long specifying the number of the page upon which page
numbers are initially displayed

Return value None

Examples This example calls the of_SetStartPageNumber function:
rte_doc.of_SetContinuousPages(TRUE)
rte_doc.of_SetPageInputField("PAGE NUMBER")
rte_doc.of_SetStartPageNumber(2)

of_SetTextStyleBold
Description Sets the currently selected text to bold, leaving all other text attributes as they
were.
Access Public
Syntax instancename.of_SetTextStyleBold ( boolean )
Argument Description
instancename Instance name of u_rte
boolean Boolean indicating whether to add the bold attribute (TRUE) or
remove it (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetTextStyleBold function:
Integer li_return

li_return = rte_doc.of_SetTextStyleBold(TRUE)

303
u_rte

IF li_return = -1 THEN
MessageBox("RTE","Error setting text style")
END IF

of_SetTextStyleItalic
Description Sets the currently selected text to italic, leaving all other text attributes as they
were.
Access Public
Syntax instancename.of_SetTextStyleItalic ( boolean )
Argument Description
instancename Instance name of u_rte
boolean Boolean indicating whether to add the italic attribute (TRUE) or
remove it (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetTextStyleItalic function:
Integer li_return

li_return = rte_doc.of_SetTextStyleItalic(TRUE)
IF li_return = -1 THEN
MessageBox("RTE","Error setting text style")
END IF

of_SetTextStyleStrikeout
Description Sets the currently selected text to strikeout, leaving all other text attributes as
they were.
Access Public
Syntax instancename.of_SetTextStyleStrikeout ( boolean )
Argument Description
instancename Instance name of u_rte
boolean Boolean indicating whether to add the strikeout attribute (TRUE)
or remove it (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.

304
 Chapter 6 Standard Visual User Objects

Examples This example calls the of_SetTextStyleStrikeout function:

Integer li_return

li_return = rte_doc.of_SetTextStyleStrikeout(TRUE)
IF li_return = -1 THEN
MessageBox("RTE","Error setting text style")
END IF

of_SetTextStyleSubscript
Description Sets the currently selected text to subscript, leaving all other text attributes as
they were.
Access Public
Syntax instancename.of_SetTextStyleSubscript ( boolean )
Argument Description
instancename Instance name of u_rte
boolean Boolean indicating whether to add the subscript attribute (TRUE)
or remove it (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetTextStyleSubscript function:
Integer li_return

li_return = rte_doc.of_SetTextStyleSubscript(TRUE)
IF li_return = -1 THEN
MessageBox("RTE","Error setting text style")
END IF

of_SetTextStyleSuperscript
Description Sets the currently selected text to superscript, leaving all other text attributes as
they were.
Access Public
Syntax instancename.of_SetTextStyleSuperscript ( boolean )
Argument Description
instancename Instance name of u_rte
boolean Boolean indicating whether to add the superscript attribute
(TRUE) or remove it (FALSE)

305
u_rte

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetTextStyleSuperscript function:
Integer li_return

li_return = rte_doc.of_SetTextStyleSuperscript(TRUE)
IF li_return = -1 THEN
MessageBox("RTE","Error setting text style")
END IF

of_SetTextStyleUnderline
Description Sets the currently selected text to underline, leaving all other text attributes as
they were.
Access Public
Syntax instancename.of_SetTextStyleUnderline ( boolean )
Argument Description
instancename Instance name of u_rte
boolean Boolean indicating whether to add the underline attribute
(TRUE) or remove it (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetTextStyleUnderline function:
Integer li_return

li_return = rte_doc.of_SetTextStyleUnderline(TRUE)
IF li_return = -1 THEN
MessageBox("RTE","Error setting text style")
END IF

306
 Chapter 6 Standard Visual User Objects

u_sle
Description SingleLineEdit visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
SingleLineEdit control. U_sle event scripts provide integration with PFC
menus. Additionally, u_sle supports:
• Cut, copy, paste, clear, and select all These events are called by PFC
menus.
• Popup menu support The ContextMenu event enables you to use the
right mouse button to perform editing actions. To disable right mouse
button support, set ib_rmbmenu to FALSE in the SingleLineEdit’s
Constructor event.
• Autoselect This means that text is selected when a user tabs to the edit
mask. To disable autoselect, set ib_autoselect to FALSE in the
SingleLineEdit’s Constructor event.
See also u_mle

307
u_sle

Instance variables
U_sle includes instance variables:
Instance variable Description Data type Access Usage
ib_autoselect Indicates whether PFC Boolean Protected Set this to TRUE to enable
selects text automatically autoselect (default is FALSE)
when the control receives
focus
ib_rmbmenu Indicates whether the Boolean Protected Set this to FALSE to disable
m_edit menu displays right mouse button support
when the user presses the (default is TRUE)
right mouse button

Events
U_sle includes precoded events:
ContextMenu pfc_Paste
GetFocus pfc_PreRmbMenu
pfc_Clear pfc_SelectAll
pfc_Copy pfc_Undo
pfc_Cut RButtonUp

ContextMenu
Description Displays the m_edit popup menu.
Usage This event executes when the user releases the right mouse button over a
control based on u_sle.

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

pfc_Clear
Description Deletes selected text.
Return value Integer. Returns the number of characters deleted if the event succeeds and -1
if an error occurs.

308
 Chapter 6 Standard Visual User Objects

Usage This event is triggered when a SingleLineEdit control based on u_sle has focus
and the user selects Edit>Clear from the menu bar of a menu descended from
the PFC m_master menu.

pfc_Copy
Description Copies selected text to the clipboard.
Return value Integer. Returns the number of characters copied if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a SingleLineEdit control based on
u_sle has focus and the user selects Edit>Copy from the menu bar of a menu
descended from the PFC m_master menu. This event is also called by the
m_edit popup menu.

pfc_Cut
Description Deletes selected text and stored it on the clipboard.
Return value Integer. Returns the number of characters removed if the event succeeds and -
1 if an error occurs.
Usage The message router calls this event when a SingleLineEdit control based on
u_sle has focus and the user selects Edit>Cut from the menu bar of a menu
descended from the PFC m_master menu. This event is also called by the
m_edit popup menu.

pfc_Paste
Description Inserts (pastes) the contents of the clipboard at the insertion point.
Return value Integer. Returns the number of characters that were pasted if the event succeeds
and -1 if an error occurs.
Usage The message router calls this event when a SingleLineEdit control based on
u_sle has focus and the user selects Edit>Paste from the menu bar of a menu
descended from the PFC m_master menu. This event is also called by the
m_edit popup menu.

pfc_PreRmbMenu
Description User event allowing you to modify m_edit contents prior to display.
Syntax instancename.EVENT pfc_PreRmbMenu ( editmenu )

309
u_sle

Argument Description
instancename Instance name of u_sle
editmenu M_edit variable containing the popup menu to be displayed
(passed by reference)

Usage You can add logic to this event to selectively enable and disable m_edit menu
items.

pfc_SelectAll
Description Selects all text in the SingleLineEdit.
Return value Integer. Returns the number of characters selected if the event succeeds and -1
if an error occurs.
Usage The message router calls this event when a SingleLineEdit control based on
u_sle has focus and the user selects Edit>Select All from the menu bar of a
menu descended from the PFC m_master menu. This event is also called by the
m_edit popup menu.

pfc_Undo
Description Cancels the last change to the SingleLineEdit control, restoring the text to the
content before the last change.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The message router calls this event when a SingleLineEdit control based on
u_sle has focus and the user selects Edit>UndoAll from the menu bar of a menu
descended from the PFC m_master menu.

RButtonUp
Description Empty user event. PFC code previously assigned to this event is now in the
ContextMenu event.
Usage This event executes when the user releases the right mouse button over a
control based on u_sle.

Functions
U_sle includes precoded object functions:

310
 Chapter 6 Standard Visual User Objects

of_GetParentWindow
of_MessageBox

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_sle
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_sle GetFocus event calls this function.
Examples This example is from the u_sle GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_sle
id String specifying an ID for the message
title String specifying the title of the SingleLineEdit
message String specifying the message text

311
u_sle

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in SingleLineEdits.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’sle_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

312
 Chapter 6 Standard Visual User Objects

u_st
Description StaticText visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
StaticText control. U_st event scripts provide integration with PFC menus.
Descendants u_st_splitbar
See also u_mle
u_sle
u_sth

Events
U_st includes one precoded event:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

313
u_st

Functions
U_st includes precoded object functions:
of_GetParentWindow
of_MessageBox

of_GetParentWindow
Description Returns a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_st
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_st GetFocus event calls this function.
Examples This example is from the u_st GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_st
id String specifying an ID for the message

314
 Chapter 6 Standard Visual User Objects

Argument Description
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in StaticText controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’st_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

315
u_sth

u_sth
Description StaticTextHyperlink visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
StaticTextHyperlink control. U_sth event scripts provide integration with PFC
menus.
See also u_phl
u_st

Events
U_sth includes one precoded event:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_sth includes precoded object functions:
of_GetParentWindow
of_MessageBox

316
 Chapter 6 Standard Visual User Objects

of_GetParentWindow
Description Returns a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_sth
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_sth GetFocus event calls this function.
Examples This example is from the u_sth GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_sth
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

317
u_sth

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in StaticTextHyperlink
controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’sth_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

318
 Chapter 6 Standard Visual User Objects

u_tab
Description Tab control visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use descendants of this visual user object in the User Object painter instead of
the visual standard tab user object. Using the User Object painter, add u_tabpg-
based tab pages, coding events and functions as needed.
U_tab is a self-updating object.
You typically do not place this object directly into the Window painter.
See also n_cst_resize
u_tabpg

Instance variables
U_tab includes instance variables:
Instance variable Description Data type Access Usage
ib_alwaysvalidate Controls whether the Boolean Protected Set with of_SetAlwaysValidate
save process includes (default is FALSE)
all objects in the
validation process
ib_isupdateable Indicates whether the Boolean Protected Set with of_SetUpdateable
Tab control can be (default is FALSE)
updated

319
u_tab

Instance variable Description Data type Access Usage

inv_luw Reference variable for n_cst_luw Protected Implements the update process
logical unit of work
service
inv_resize Reference variable for n_cst_resize Public Use in dot notation to access
the resize service n_cst_resize functions and
attributes
ipo_pendingupdates[ ] Objects that could be PowerObject Protected Internal
updated
ipo_updateobjects[ ] Objects to be updated PowerObject Protected Internal
ipo_updaterequestor Owner of the save PowerObject Protected Internal
process
NO_ACTION Constant set to 0 Integer Public Internal

Events
U_tab includes a precoded event:
pfc_AcceptText pfc_UpdatesPending
pfc_PostUpdate pfc_Validation
pfc_Update Resize
pfc_UpdatePrep

pfc_AcceptText
Description Calls the n_cst_luw of_AcceptText function.
Syntax instancename.Event pfc_AcceptText ( controls, focusonerror )
Argument Description
instancename Instance name of u_tab
controls PowerObject array containing the objects on which to accept text.
This argument is accessed through the apo_control argument
focusonerror Boolean indicating whether focus should be set if an error occurs.
This argument is accessed through the ab_focusonerror argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The of_AcceptText function calls this event.

320
 Chapter 6 Standard Visual User Objects

pfc_PostUpdate
Description Calls the n_cst_luw of_PostUpdate function.
Syntax instancename.Event pfc_PostUpdate ( controls )
Argument Description
instancename Instance name of u_tab
controls PowerObject array containing the objects on which to perform
post-update processing. This argument is accessed through the
apo_control argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Internal.

pfc_Update
Description Calls the n_cst_luw of_Update function to update the specified controls.
Syntax instancename.Event pfc_Update ( controls, accepttext, resetflags )
Argument Description
instancename Instance name of u_tab
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument
accepttext Boolean specifying whether n_cst_luw should automatically
perform an AcceptText prior to performing the Update (TRUE) or
not (FALSE)
resetflags Boolean specifying whether n_cst_luw should automatically reset
DataWindow update flags (TRUE) or not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The of_Update function calls this event.

pfc_UpdatePrep
Description Calls the n_cst_luw of_UpdatePrep function.
Syntax instancename.Event pfc_UpdatePrep ( controls )
Argument Description
instancename Instance name of u_tab
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument

321
u_tab

Return value Long. Return 1 if the update preparation succeeds and -1 to halt the update
process.
Usage The of_UpdatePrep function calls this function.

pfc_UpdatesPending
Description Calls the n_cst_luw of_GetUpdatesPending function.
Syntax instancename.Event pfc_UpdatesPending ( controls, pending )
Argument Description
instancename Instance name of u_tab
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument
pending PowerObject array into which the event places objects with
pending updates. This argument is accessed through the
apo_pending argument (passed by reference)

Return value Integer. Returns 1 if there are pending updates, 0 if there are no pending
updates, and -1 if an error occurs.
Usage This event is called by the of_GetUpdatesPending function.

pfc_Validation
Description Calls the n_cst_luw of_Validation function.
Syntax instancename.Event pfc_Validation ( controls )
Argument Description
instancename Instance name of u_tab
controls PowerObject array containing the objects to validate. This
argument is accessed through the apo_control argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the of_Validation function.

Resize
Description Triggers automatic resize processing, if enabled in n_cst_resize.
Usage This event executes when the user resizes the window.

322
 Chapter 6 Standard Visual User Objects

Functions
U_tab includes precoded object functions:
of_AcceptText of_SetLogicalUnitOfWork
of_GetInfo of_SetResize
of_GetParentWindow of_SetUpdateable
of_GetUpdateObjects of_SetUpdateObjects
of_IsAlwaysValidate of_SetUpdateRequestor
of_IsUpdateable of_Update
of_MessageBox of_UpdatePrep
of_PostUpdate of_UpdatesPending
of_SetAlwaysValidate of_Validation

of_AcceptText
Description Performs an AcceptText function for controls on the tab’s tab pages.
Access Public
Syntax instancename.of_AcceptText ( focusonerror )
Argument Description
instancename Instance name of u_tab
focusonerror Boolean indicating whether PFC sets focus to the first item in
error when an error occurs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize accept text processing,
extend the pfc_AcceptText event.
Examples This example is from the n_cst_luw of_AcceptText function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_AcceptText &
(ab_focusonerror)
If li_rc < 0 Then Return -1

...

323
u_tab

of_GetInfo
Description Retrieves object information.
Access Public
Syntax instancename.of_GetInfo ( infoobject )
Argument Description
instancename Instance name of u_tab
infoobject N_cst_infoattrib instance into which the function places
information (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_GetInfo function:
n_cst_infoattrib lnv_info

tab_1.of_GetInfo(lnv_info)
MessageBox("Info", &
"Description: " + lnv_info.is_description &
+ ". Name: " + lnv_info.is_name)

of_GetParentWindow
Description Returns a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_tab
window Window variable into which the function places a reference to the
parent window

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage Call this function from within a tab to determine the parent window.
Examples This example calls the of_GetParentWindow function:
Window lw_parent

of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
... // Continue processing
END IF

324
 Chapter 6 Standard Visual User Objects

of_GetUpdateObjects
Description Retrieves the current default array of objects affected by the update process.
Access Protected
Syntax instancename.of_GetUpdateObjects ( objects )
Argument Description
instancename Instance name of u_tab
objects PowerObject array into which the function places objects to be
updated (passed by reference)

Return value Integer. Returns the number of elements in the objects array if the function
succeeds and -1 if an error occurs.
Examples This example calls the of_GetUpdateObjects function:
PowerObject lpo_objs[ ]
Integer li_return, li_count

li_return = this.of_GetUpdateObjects(lpo_objs)
FOR li_count = 1 to li_return
IF lpo_objs[li_count] = ids_data THEN
Return 1
END IF
NEXT
li_return++
lpo_objs[li_return] = ids_data
Return this.of_SetUpdateObjects(lpo_objs)

of_IsAlwaysValidate
Description Reports whether the default save process always performs validation,
regardless of whether objects have updates pending.
Access Public
Syntax instancename.of_IsAlwaysValidate ( )
Argument Description
instancename Instance name of u_tab

Return value Boolean. Returns TRUE if the default save process always performs validation
and FALSE if it does not.
Examples This example calls the of_IsAlwaysValidate function:
IF tab_1.of_IsAlwaysValidate() = TRUE THEN
MessageBox("Tab", "Always validate")

325
u_tab

ELSE
MessageBox("Tab", "Sometimes validate")
END IF

of_IsUpdateable
Description Reports whether controls on the Tab control’s tab pages are updatable.
Access Public
Syntax instancename.of_IsUpdateable ( )
Argument Description
instancename Instance name of u_tab

Return value Boolean. Returns TRUE if controls are updatable and FALSE if they is not.
Examples This example is from the pfc_UpdatesPending event:
...
If Not of_IsUpdateable() Then Return NO_UPDATESPENDING
...

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_tab
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!

326
 Chapter 6 Standard Visual User Objects

Argument Description
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in Tab controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’tab_error’,’Save’, &
as_error, StopSign!, Ok!, 1)

of_PostUpdate
Description Calls the pfc_PostUpdate event, which clears update flags and allows you to
code additional post update processing.
Access Public
Syntax instancename.of_PostUpdate ( )
Argument Description
instancename Instance name of u_tab

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage To customize post update processing, extend the pfc_PostUpdate event.
N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize post-update processing,
extend the pfc_PostUpdate event.

327
u_tab

Examples This example is from the n_cst_luw of_PostUpdate function:

...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_PostUpdate()
...

of_SetAlwaysValidate
Description Specifies whether the default save process always performs validation,
regardless of whether there are pending updates.
Access Public
Syntax instancename.of_SetAlwaysValidate ( boolean )
Argument Description
instancename Instance name of u_tab
boolean Boolean specifying whether the default save process always
perform validation (TRUE) or only performs validation if a
control has pending updates (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetAlwaysValidate function:
tab_1.of_SetAlwaysValidate(TRUE)

of_SetLogicalUnitOfWork
Description Enables or disables n_cst_luw, which provides the logical unit of work service.
Access Public
Syntax instancename.of_SetLogicalUnitOfWork ( boolean )
Argument Description
instancename Instance name of u_tab
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) n_cst_luw

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_luw. This instance is
named inv_luw. If you do not enable n_cst_luw, u_tab enables it automatically.

328
 Chapter 6 Standard Visual User Objects

Examples This example calls the of_SetLogicalUnitOfWork function:

tab_1.of_SetLogicalUnitOfWork(TRUE)

of_SetResize
Description Enables or disables n_cst_resize, the resize service.
Access Public
Syntax instancename.of_SetResize ( boolean )
Argument Description
instancename Instance name of u_tab
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) an instance of n_cst_resize

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_resize. This instance
is named inv_resize.
Examples This example calls the of_SetResize function in a window Open event to
enable the resize service for tab_1:
tab_1.of_SetResize(TRUE)

of_SetUpdateable
Description Specifies whether the Tab is updatable.
Access Public
Syntax instancename.of_SetUpdateable ( boolean )
Argument Description
instancename Instance name of u_tab
boolean Boolean indicating whether the Tab is updatable. All updatable
Tabs are included in the default save processing

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetUpdateable function:
tab_1.of_SetUpdateable(FALSE)

of_SetUpdateObjects
Description Sets a new default array containing objects for which updates are attempted.

329
u_tab

Access Protected
Syntax instancename.of_SetUpdateObjects ( requester )
Argument Description
instancename Instance name of u_tab
requester PowerObject array containing the object to be updated

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.

of_SetUpdateRequestor
Description Creates a reference to the object requesting an update within a logical unit of
work.
Access Public
Syntax instancename.of_SetUpdateRequestor ( requester )
Argument Description
instancename Instance name of u_tab
requester PowerObject containing the object requesting the update

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_Update function:
...
If IsValid(inv_luw) Then
inv_luw.of_SetUpdateRequestor(apo_requestor)
End If
...

of_Update
Description Calls the pfc_Update event.
Access Public
Syntax instancename.of_Update ( accept, resetflag {, requestor} )
Argument Description
instancename Instance name of u_tab
accept Boolean indicating whether the Update function performs an
AcceptText before saving rows to the database

330
 Chapter 6 Standard Visual User Objects

Argument Description
resetflag Boolean indicating whether the Update function resets the update
flags
requestor PowerObject containing the requestor object

Return value Integer. Returns 1 if the update succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update processing, extend
the pfc_Update event.
Examples This example is from the n_cst_luw of_Update function:
...
If lb_defined Then
li_rc = lpo_tocheck.Function Dynamic of_Update &
(ab_accepttext, ab_resetflag, &
lpo_updaterequestor)
If li_rc < 0 Then Return -1
Continue
End If
...

of_UpdatePrep
Description Calls the pfc_UpdatePrep event.
Access Public
Syntax instancename.of_UpdatePrep ( )
Argument Description
instancename Instance name of u_tab

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update preparation
processing, extend the pfc_UpdatePrep event.
Examples This example is from the n_cst_luw of_UpdatePrep function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_UpdatePrep ()
If li_rc < 0 Then Return -1
Continue

331
u_tab

End If
...

of_UpdatesPending
Description Calls the pfc_UpdatesPending event.
Access Public
Syntax instancename.of_UpdatesPending ( )
Argument Description
instancename Instance name of u_tab

Return value Integer. Returns values as follows:

• 1 Updates are pending
• 0 No updates pending
• -1 An error occurred
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize pending updates
processing, extend the pfc_UpdatesPending event.
Examples This example calls the of_UpdatesPending function:
...
If lb_defined Then
la_rc = lpo_tocheck.Dynamic of_UpdatesPending ()
...

of_Validation
Description Calls the pfc_Validation event.
Access Public
Syntax instancename.of_Validation ( )
Argument Description
instancename Instance name of u_tab

Return value Integer. Returns 1 if the function succeeds and -1 if a validation error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize validation processing,
extend the pfc_Validation event.

332
 Chapter 6 Standard Visual User Objects

Examples This example calls the of_Validation function:

...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_Validation()
...

333
u_tvs

u_tvs
Description Service-based TreeView visual user object ancestor. This object uses
DataStores to display data in a TreeView.
U_tvs is a self-updating object.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master. U_tvs also uses:
m_tv
n_cst_infoattrib
n_ds
n_cst_luw
n_cst_tvsrv
n_cst_tvsrv_levelsource
n_cst_print

334
 Chapter 6 Standard Visual User Objects

Usage Use this visual user object in windows instead of the standard PowerBuilder
TreeView control. U_tvs event scripts provide integration with PFC menus.
To use u_tvs:
1 Place a u_tvs user object in your window.
2 Enable TreeView services as needed:
this.of_SetPrint(TRUE)
this.of_SetLevelSource(TRUE)
this.of_SetBase(TRUE)
3 Specify the data source for each TreeView level:
String ls_sql
Integer li_return

ls_keys[1] = "dept_id"
this.inv_levelsource.of_Register(1, &
"dept_name", "", "d_deptlist", SQLCA, "")
ls_keys[1] = "emp_id"
this.inv_levelsource.of_Register(2, &
"emp_lname", ":parent.1.dept_id", &
"d_empbydept", SQLCA, "")
4 Specify additional TreeView display information as needed:
this.inv_levelsource.of_SetPictureColumn(1, "1")
this.inv_levelsource.of_SetSelectedPictureColumn &
(1, "2")
this.inv_levelsource.of_SetPictureColumn(2, "4")
this.inv_levelsource.of_SetSelectedPictureColumn &
(2, "5")
5 Retrieve rows for the first level of the TreeView:
this.event pfc_populate(0)
6 Extend the pfc_Retrieve event to implement retrieval arguments:
Any la_args[20]
Integer li_level

IF IsValid(inv_levelsource) THEN
li_level = this.of_GetNextLevel(al_parent)
this.inv_levelsource.of_GetArgs(al_parent, &
li_level, la_args)
END IF

335
u_tvs

Return this.of_Retrieve(al_parent, la_args, &

ads_data)
7 Call additional u_tvs functions as needed.
For more information on the TreeView control, see the PowerBuilder User’s
Guide.
See also m_tvs
u_lvs
n_cst_tvsrv
n_cst_tvsrv_levelsource
n_cst_tvsrv_print

Instance variables
U_tvs includes instance variables:
Instance variable Description Data type Access Usage
ib_alwaysvalidate Controls whether the Boolean Protected Set with
save process includes of_SetAlwaysValidate
all objects in the (default is FALSE)
validation process
ib_isupdateable Indicates whether the Boolean Protected Set with
TreeView can be of_SetUpdateable
updated (default is FALSE)
ib_rmbmenu Controls right mouse Boolean Protected Set with of_SetRmbMenu
button support
il_dragsource Handle of the dragged Long Public PFC uses this instance
item variable to track a dragged
TreeView item
il_dragtarget Handle of drag target Long Public PFC uses this instance
variable to track a dragged
TreeView item
il_rightclicked Item clicked with the Long Protected Internal
right mouse button
im_view Popup menu m_tvs Protected Internal
inv_base Reference variable for n_cst_tvsrv Public Use in dot notation to
basic TreeView access n_cst_tvsrv
services functions and attributes

336
 Chapter 6 Standard Visual User Objects

Instance variable Description Data type Access Usage

inv_levelsource Reference variable for n_cst_tvsrv_ Public Use in dot notation to
the TreeView data levelsource access
source service n_cst_tvsrv_levelsource
functions and attributes
inv_luw Reference variable for n_cst_luw Protected Implements the save
logical unit of work process
service
inv_print Reference variable for n_cst_tvsrv_ Public Use in dot notation to
TreeView print service print access n_cst_tvsrv_print
functions and attributes
ipo_pendingupdates[ ] Objects that could be PowerObject Protected Internal
updated
ipo_updaterequestor Owner of the save PowerObject Protected Internal
process

Events
U_tvs includes precoded events:
BeginDrag pfc_PreRefreshItem
Destructor pfc_PreRefreshLevel
DragDrop pfc_PreRmbMenu
EndLabelEdit pfc_Properties
GetFocus pfc_RefreshItem
KeyDown pfc_RefreshLevel
ItemExpanding pfc_RenameItem
pfc_AcceptText pfc_Retrieve
pfc_AddAll pfc_SearchCompare
pfc_AddItem pfc_SetItemAttributes
pfc_DeleteItem pfc_Undo
pfc_InsertItem pfc_Update
pfc_NewItem pfc_UpdatePrep
pfc_Populate pfc_UpdatesPending
pfc_PostUpdate pfc_Validation
pfc_PreDeleteItem RightClicked
pfc_PreInsertItem

337
u_tvs

BeginDrag
Description Saves the handle of a dragged item in the il_dragsource public instance
variable.
Usage This event executes when the user drags a label.

Destructor
Description Destroys all enabled service objects.
Usage This event executes when the TreeView is destroyed or the window closes.

DragDrop
Description Saves the handle of the dropped item in the il_dragtarget instance variable.
Usage This event executes when the user releases a dragged object over the TreeView.
You should extend this event to allow dragging and dropping of TreeView
items from one branch to another. Be sure to verify that the drag source is the
current TreeView control.

EndLabelEdit
Description Updates the DataStore with user edits to the item label.
This function updates the DataStore only. You must update the database
explicitly, using the of_Update function or the w_master pfc_Save process.
Usage This event executes when the user finishes editing an item label.
If you are using computed columns to display item labels, override this event
to update DataStore rows as appropriate.

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event executes when the control receives focus. It triggers the
pfc_ControlGotFocus event in the parent.

KeyDown
Description Checks to see if the DELETE key was pressed.
Usage This event executes when the user presses a key and is not editing a label.

338
 Chapter 6 Standard Visual User Objects

ItemExpanding
Description Populates an item with its children.
Usage This event executes when the user expands an item.

pfc_AcceptText
Description Accepts text for the data displayed in a TreeView control, optionally setting
focus if an error occurs.
Syntax instancename.EVENT pfc_AcceptText ( controls, focusonerror )
Argument Description
instancename Instance name of u_tvs
controls PowerObject array containing the objects on which to accept text.
This argument is accessed through the apo_control argument
focusonerror Boolean indicating whether focus should be set if an error occurs.
This argument is accessed through the ab_focusonerror argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Extend this event to perform additional accept text processing.

pfc_AddAll
Description Adds all rows in the passed DataStore under the specified TreeView item.
Syntax instancename.EVENT pfc_AddAll ( parent, data )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item under which
the new items are added. This argument is accessed through the
al_parent argument
data N_ds-based DataStore containing rows to be added. This
argument is accessed through the ads_source argument

Return value Long. Returns the number of items added if the event succeeds and -1 if an
error occurs.
Examples This example is from the of_Populate function:
...
Return this.event pfc_AddAll(al_parent, lds_data)
...

339
u_tvs

pfc_AddItem
Description Adds the specified row as the last item under the specified parent.
Syntax instancename.EVENT pfc_AddItem ( parent, data, row )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item under which
the new item is added. This argument is accessed through the
al_parent argument
data N_ds-based DataStore containing the row to be added. This
argument is accessed through the ads_source argument
row Long specifying the row containing the data to be added to the
TreeView. This argument is accessed through the al_row
argument

Return value Long. Returns the handle of the new item if the event succeeds and -1 if an
error occurs.
Examples This example is from the of_AddItem function:
...
ll_newindex = this.event pfc_additem &
(al_parent, lds_datastore, ll_row)
...

pfc_DeleteItem
Description Deletes the selected item from the TreeView and the DataStore.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Examples This example calls the pfc_DeleteItem event:
...
li_return = tv_1.Event pfc_DeleteItem()
...

pfc_InsertItem
Description Inserts a new item into the TreeView.
Syntax instancename.EVENT pfc_InsertItem ( parent, datastore, row, position,
item )
Argument Description
instancename Instance name of u_tvs

340
 Chapter 6 Standard Visual User Objects

Argument Description
parent Long specifying the handle of the TreeView item under which the
new item is added. This argument is accessed through the al_parent
argument
datastore N_ds containing the data for the new item. This can be either the
DataStore maintained by n_cst_tvsrv_levelsource or another
DataStore. If this is another DataStore, the associated DataWindow
objects must be the same and the function also adds the row to the
DataStore maintained by n_cst_tvsrv_levelsource. This argument is
accessed through the ads_source argument
row Long specifying the row containing the item to be inserted. This
argument is accessed through the al_row argument
position String specifying the position under the current parent in which to
insert the new item Values are:
• First
• Last
• Sort
• After
This argument is accessed through the as_position argument
item Long containing the handle to the item before the item to be
inserted. The function uses this argument if you specify After for
position. This argument is accessed through the al_handle argument

Return value Integer. Returns the handle of the new item if the function succeeds and -1 if
an error occurs.
Usage This event calls the pfc_SetItemAttributes and pfc_PreInsertItem events before
inserting the item.
Examples This example is from the pfc_AddAll event:
...
For ll_row = 1 to ll_rowcount
If this.event pfc_insertitem(al_parent, &
ads_source, ll_row, "last", 0) < 1 then
Return -1
End If
ll_count++
...

pfc_NewItem
Description Empty user event that you extend to add information to both the data source
and the TreeView.

341
u_tvs

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage You typically use this event to open a dialog box prompting the user for
complete information, adding it to the data source and the TreeView (via the
n_cst_tvsrv_levelsource of_InsertItem function) when it closes.

pfc_Populate
Description Retrieves the data source and uses it to populate the TreeView as children of
the specified parent.
Syntax instancename.EVENT pfc_Populate ( parent )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item under which
the new items are added. This argument is accessed through the
al_parent argument

Return value Long. Returns the number of items added if the event succeeds and -1 if an
error occurs.
Usage You must also add code to the pfc_Retrieve event.
Examples This example is from the ItemExpanding event:
...
If This.FindItem(ChildTreeItem!, handle) = -1 Then
if this.GetItem(handle, ltvi_This) = 1 then
li_rc = this.event pfc_Populate(handle)
If li_rc < 1 Then
...

pfc_PostUpdate
Description Calls the n_cst_luw of_PostUpdate function to perform post-update processing
on the specified controls.
Syntax instancename.EVENT pfc_PostUpdate ( controls )
Argument Description
instancename Instance name of u_tvs
controls PowerObject array containing the objects on which to perform
post-update processing. This argument is accessed through the
apo_control argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.

342
 Chapter 6 Standard Visual User Objects

Usage Extend this event to perform additional post-update processing.

pfc_PreDeleteItem
Description Empty user event to which you add logic to perform pre-delete processing.
Syntax instancename.EVENT pfc_PreDeleteItem ( handle )
Argument Description
instancename Instance name of u_tvs
handle Long specifying the handle of the TreeView item to be deleted.
This argument is accessed through the al_handle argument

Usage The pfc_DeleteItem event calls this event.

pfc_PreInsertItem
Description Empty user event to which you add logic to perform pre-insert processing.
Syntax instancename.EVENT pfc_PreInsertItem ( parent, data, row, tvitem )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item under which the
new item is added. This argument is accessed through the
al_parent argument
data N_ds containing the data for the new item. This argument is
accessed through the ads_obj argument
row Long specifying the row containing the new item. This argument
is accessed through the al_row argument
tvitem TreeViewItem to be inserted. This argument is accessed through
the atvi_item argument (passed by reference)

Usage The pfc_InsertItem event calls this event.

pfc_PreRefreshItem
Description Empty user event to which you add logic that changes properties before a
TreeView item is refreshed.
Syntax instancename.EVENT pfc_PreRefreshItem ( handle, data, row, tvitem )
Argument Description
instancename Instance name of u_tvs

343
u_tvs

Argument Description
handle Long specifying the handle of the TreeView item to be
refreshed. This argument is accessed through the al_handle
argument
data N_ds containing the data for the refreshed item. This argument
is accessed through the ads_obj argument
row Long specifying the row containing the refreshed item. This
argument is accessed through the al_row argument
tvitem TreeViewItem to be refreshed. This argument is accessed
through the atvi_item argument (passed by reference)

Usage The pfc_RefreshItem event calls this event. The code you add here will likely
be the same as code you add to pfc_PreInsertItem.

pfc_PreRefreshLevel
Description Empty user event to which you add logic that executes before a TreeView level
is refreshed.
Syntax instancename.EVENT pfc_PreRefreshLevel ( level )
Argument Description
instancename Instance name of u_tvs
level Integer specifying the TreeView level to refresh. This argument
is accessed through the ai_level argument

Usage The pfc_RefreshLevel event calls this event.

pfc_PreRmbMenu
Description Empty user event allowing you to modify m_tvs contents before display.
Syntax instancename.EVENT pfc_PreRmbMenu ( editmenu )
Argument Description
instancename Instance name of u_tvs
editmenu M_tvs variable containing the popup menu to be displayed
(passed by reference)

Usage Optionally add logic to this event to selectively enable and disable m_lvs menu
items.

344
 Chapter 6 Standard Visual User Objects

pfc_Properties
Description Empty user event to which you might add logic to display a Properties dialog.
Return value Integer. Return 1 if the event succeeds and -1 if an error occurs.

pfc_RefreshItem
Description Refreshes the specified TreeView item, resetting all properties to the defaults
specified in the data source.
Syntax instancename.EVENT pfc_RefreshItem ( handle )
Argument Description
instancename Instance name of u_tvs
handle Long specifying the handle of the TreeView item to refresh. This
argument is accessed through the ai_level argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Examples This example is from the pfc_RefreshLevel event:
...
For ll_row = 1 to ll_rowcount
ll_handle = inv_levelsource.of_GetHandle &
(lds_source, ll_row, ai_level)
If ll_handle < 1 Then Continue
If this.event pfc_RefreshItem &
(ll_Handle) = -1 Then Return -1
Next
...

pfc_RefreshLevel
Description Refreshes the specified TreeView level., resetting all properties to the defaults
specified in the data source.
Syntax instancename.EVENT pfc_RefreshLevel ( level )
Argument Description
instancename Instance name of u_tvs
level Integer specifying the TreeView level to refresh

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.

345
u_tvs

Examples This example calls the pfc_RefreshLevel event:

...
tv_1.Event pfc_RefreshLevel(1)
...

pfc_RenameItem
Description Renames the selected item.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Internal.

pfc_Retrieve
Description Retrieves rows into a data source.
Syntax instancename.EVENT pfc_Retrieve ( parent, data )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item under which
new items are retrieved. This argument is accessed through the
al_parent argument
data N_ds into which the event places the retrieved rows. This
argument is accessed through the ads_data argument (passed by
reference)

Return value Long. Returns the number of items retrieved if the event succeeds and -1 if an
error occurs.
Usage Extend this event to perform retrieval.
Examples This example shows code you might add to the pfc_Retrieve event:
Any la_args[20]
Integer li_level

IF IsValid(inv_levelsource) THEN
li_level = this.of_GetNextLevel(al_parent)
this.inv_levelsource.of_GetArgs(al_parent, &
li_level, la_args)
END IF

Return this.of_Retrieve(al_parent, la_args, &

ads_data)

346
 Chapter 6 Standard Visual User Objects

pfc_SearchCompare
Description Compares TreeView data or item text with a target string.
Syntax instancename.EVENT pfc_SearchCompare ( handle, attribute, target,
respectcase, fullcompare )
Argument Description
instancename Instance name of u_tvs
handle Long containing the handle of the item being compared
attribute String specifying the TreeView attribute to compare. Valid values
are:
• Data
• Label
target Any data type specifying the search target
respectcase Boolean indicating whether the search is case-sensitive
fullcompare Boolean indicating whether the specified attribute must match
target exactly (TRUE) or the attribute can simply contain target
(FALSE). This argument only applies when target is a string

Return value Boolean. Returns TRUE if a match is found and FALSE if no match is found.
Usage This event is called by the n_cst_tvsrv of_SearchChild function, which is
called by of_FindItem.
If your application requires a more complex comparison, override this event.

pfc_SetItemAttributes
Description Sets default properties for the TreeView item before insertion.
Syntax instancename.EVENT pfc_SetItemAttributes ( parent, data, row, tvitem )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item under which
the new item is inserted. This argument is accessed through the
al_parent argument
data N_ds containing the data for the item. This argument is accessed
through the ads_obj argument
row Long specifying the row from which to populate the item. This
argument is accessed through the al_row argument
tvitem TreeViewItem to be inserted. This argument is accessed through
the atvi_item argument (passed by reference)

347
u_tvs

Usage Optionally extend this event to change TreeView item properties before
insertion.

pfc_Undo
Description Cancels the last edit, insert, or delete to the TreeView, restoring the text to the
content before the last change.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The message router calls this event when a TreeView based on u_tvs has focus
and the user selects Edit>Undo.

pfc_Update
Description Calls the n_cst_luw of_Update function to update the specified controls.
Syntax instancename.EVENT pfc_Update ( controls, accepttext, resetflags )
Argument Description
instancename Instance name of u_tvs
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument
accepttext Boolean specifying whether n_cst_luw should automatically
perform an AcceptText before performing the Update (TRUE) or
not (FALSE)
resetflags Boolean specifying whether n_cst_luw should automatically reset
DataWindow update flags (TRUE) or not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The of_Update function calls this event.

pfc_UpdatePrep
Description Empty user event to which you can add code that prepares for update.
Syntax instancename.EVENT pfc_UpdatePrep ( controls )
Argument Description
instancename Instance name of u_tvs
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument

Return value Long. Return 1 if the update preparation succeeds and -1 to halt the update
process.

348
 Chapter 6 Standard Visual User Objects

Usage The of_UpdatePrep function calls this function.

pfc_UpdatesPending
Description Determines if there are pending updates for the TreeView data sources.
Syntax instancename.EVENT pfc_UpdatesPending ( controls, pending )
Argument Description
instancename Instance name of u_tvs
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument
pending PowerObject array into which the event places objects with
pending updates. This argument is accessed through the
apo_pending argument (passed by reference)

Return value Integer. Returns 1 if there are pending updates, 0 if there are no pending
updates, and -1 if an error occurs.
Usage This event is called by the of_GetUpdatesPending function.

pfc_Validation
Description Checks for required fields.
Syntax instancename.EVENT pfc_Validation ( controls )
Argument Description
instancename Instance name of u_tvs
controls PowerObject array containing the objects to validate. This
argument is accessed through the apo_control argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the of_Validation function.

RightClicked
Description Tracks the clicked item and displays the m_tvs popup menu.
Usage This event executes when the user presses the right mouse button.

Functions

349
u_tvs

U_tvs includes precoded object functions:

of_AcceptText of_Reset
of_AddItem of_Retrieve
of_CanUndo of_SetAlwaysValidate
of_GetInfo of_SetBase
of_GetNextLevel of_SetLevelSource
of_GetObjects of_SetLogicalUnitOfWork
of_GetParentWindow of_SetPrint
of_GetUpdateRequestor of_SetRMBMenu
of_InsertItem of_SetUpdateable
of_IsAlwaysValidate of_SetUpdateRequestor
of_IsRMBMenu of_Update
of_IsUpdateable of_UpdatePrep
of_MessageBox of_UpdatesPending
of_Populate of_Validation
of_PostUpdate

of_AcceptText
Description Performs an AcceptText function for each level’s data source.
Access Public
Syntax instancename.of_AcceptText ( focusonerror )
Argument Description
instancename Instance name of u_tvs
focusonerror Boolean indicating whether PFC sets focus to the first item in
error when an error occurs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize accept text processing,
extend the pfc_AcceptText event.

350
 Chapter 6 Standard Visual User Objects

Examples This example is from the n_cst_luw of_AcceptText function:

...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_AcceptText &
(ab_focusonerror)
If li_rc < 0 Then Return -1

...

of_AddItem
Description Adds a new item as the last item under the specified parent.
Access Public
Syntax instancename.of_AddItem ( parent, rowinfo )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item under which the
new item is inserted
rowinfo Any array containing data for the row

Return value Long. Returns the index of the added item if the function succeeds and -1 if an
error occurs.
Usage If the information in rowinfo is not already in the data source, this function adds
the new row to the data source. If you are using the TreeView level source
service, the data types of the elements in rowinfo must match those in the
DataWindow object specified in the n_cst_tvsrv_levelsource of_Register
function.
Examples This example is from the of_Refresh function:
Long ll_return
Long ll_handle
Any la_row[ ]
TreeViewItem ltvi_item

ll_handle = tv_1.FindItem(CurrentTreeItem! , 0)
tv_1.GetItem(ll_handle, ltvi_item)
IF ltvi_item.Level = 1 THEN
la_row[1] = 1100
la_row[2] = "Department of Defense"
ll_return = tv_1.of_AddItem(ll_handle, la_row)

351
u_tvs

tv_1.Event pfc_RefreshLevel(ltvi_item.Level)
END IF

of_CanUndo
Description Reports whether the TreeView can undo the last edit, insertion, or deletion,
returning the operation type.
Access Public
Syntax instancename.of_CanUndo ( undotype )
Argument Description
instancename Instance name of u_tvs
undotype String into which the function places the type of the last
operation (passed by reference):
• UNDO_EDIT or "Edit" Edit
• UNDO_INSERT or "Insert" Insertion
• UNDO_DELETE or "Delete" Deletion

Return value Boolean. Returns TRUE if the last operation can be undone and FALSE if it
cannot.
Examples This example calls the of_CanUndo function:
String ls_undotype

IF tv_1.of_CanUndo(ls_undotype) THEN
MessageBox("TreeView", "Can undo")
ELSE
MessageBox("TreeView", "Cannot undo")
END IF

of_GetInfo
Description Retrieves object information.
Access Public
Syntax instancename.of_GetInfo ( infoobject )
Argument Description
instancename Instance name of u_tvs
infoobject N_cst_infoattrib instance into which the function places
information (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.

352
 Chapter 6 Standard Visual User Objects

Examples This example calls the of_GetInfo function:

n_cst_infoattrib lnv_info

tv_1.of_GetInfo(lnv_info)
MessageBox("Info", &
"Description: " + lnv_info.is_description &
+ ". Name: " + lnv_info.is_name)

of_GetNextLevel
Description Determines the DataStore level below the passed parent.
Access Public
Syntax instancename.of_GetNextLevel ( parent )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item for which the
next lowest level is returned

Return value Long. Returns the number of the level below parent if the function succeeds
and -1 if an error occurs.
Examples This example is from the pfc_PreRetrieve event:
...
If isvalid(inv_levelsource) then
li_level = of_GetNextLevel(al_parent)
If li_level < 1 then Return
...

of_GetObjects
Description Retrieves the objects to be updated.
Access Protected
Syntax instancename.of_GetObjects ( objects )
Argument Description
instancename Instance name of u_tvs
objects PowerObject array into which the function places objects to be
updated (passed by reference)

Return value Integer. Returns the number of elements in the objects array if the function
succeeds and -1 if an error occurs.

353
u_tvs

Usage Internal.
Examples This example is from the of_AcceptText function:
...
Else
this.of_Getobjects(lpo_updatearray)
End If
...

of_GetParentWindow
Description Returns the parent of the current window.
Access Public
Syntax instancename.of_GetParentWindow ( parent )
Argument Description
instancename Instance name of u_tvs
parent Window variable into which the function places the parent of the
current window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the GetFocus event.
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_GetUpdateRequestor
Description Retrieves a reference to the object requesting an update.
Access Public
Syntax instancename.of_GetUpdateRequestor ( requestor )
Argument Description
instancename Instance name of u_tvs

354
 Chapter 6 Standard Visual User Objects

Argument Description
requestor PowerObject into which the function places a reference to the
object requesting the update (passed by reference)

Return value Integer. Returns 1 if the function succeeds, 0 if there is no update requestor and
-1 if an error occurs.
Usage Call this function if you are extending the pfc_Save process and need to access
the update requestor.

of_InsertItem
Inserts an item into the TreeView. There are two syntaxes:
To Use
Insert from a DataStore Syntax 1
Insert from an array Syntax 2

Syntax 1 Insert an item from a DataStore

Description Adds a new item to the TreeView using a row from a DataStore.
Access Public
Syntax instancename.of_InsertItem ( parent, datastore, row {, position, handle } )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item under which
the new item is inserted
datastore N_ds containing the data for the new item. This can be either the
DataStore maintained by n_cst_tvsrv_levelsource or another
DataStore. If this is another DataStore, the associated
DataWindow objects must be the same and the function also
adds the row to the DataStore maintained by
n_cst_tvsrv_levelsource (passed by reference)
row Long specifying the row from which to populate the new item
position String specifying the position under the current parent in which
(optional) to insert the new item Values are:
• First
• Last (default)
• Sort
• After

355
u_tvs

Argument Description
handle Long containing the handle of the TreeView item after which the
(optional) item is added. The function uses this argument if you specify
After for position

Return value Long. Returns the handle of the new item if the function succeeds and -1 if an
error occurs.
Examples This example calls the of_InsertItem function:
Long ll_row, ll_handle
TreeViewItem ltvi_item

ll_handle = tv_1.FindItem(CurrentTreeItem! , 0)
tv_1.GetItem(ll_handle, ltvi_item)
ll_row = ids_datastore.GetRow()
IF ltvi_item.Level = 1 THEN
ll_return = tv_1.of_InsertItem &
(ll_handle, ids_data, ll_row, "Sorted", 0)
END IF

Syntax 2 Insert an item from an array

Description Adds a new item to the TreeView using a value from an array.
Access Public
Syntax instancename.of_InsertItem ( parent, colvalues {, position, handle } )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item under which
the new item is inserted
colvalues Any array containing data for the TreeView
position String specifying the position under the current parent in which
(optional) to insert the new item Values are:
• First
• Last (default)
• Before
• After
handle Long containing the handle of the TreeView item after which the
(optional) item is added. The function uses this argument if you specify
After for position

356
 Chapter 6 Standard Visual User Objects

Return value Integer. Returns the index of the new item if the function succeeds and -1 if an
error occurs.
Usage If you are using the TreeView level source service, the data types of the
elements in colvalues must match those in the DataWindow object specified in
the n_cst_tvsrv_levelsource of_Register function.
Examples This example calls the of_InsertItem function:
Any la_row[ ]
Long ll_handle
TreeViewItem ltvi_item

ll_handle = tv_1.FindItem(CurrentTreeItem! , 0)
la_row[1] = 1200
la_row[2] = "Commerce"
tv_1.of_InsertItem(ll_handle, la_row, "First", 0)

of_IsAlwaysValidate
Description Reports whether the default save process always performs validation.
Access Public
Syntax instancename.of_IsAlwaysValidate ( )
Argument Description
instancename Instance name of u_tvs

Return value Boolean. Returns TRUE if the default save process always performs validation
and FALSE if it does not.
Examples This example calls the of_IsAlwaysValidate function:
IF tv_1.of_IsAlwaysValidate() = TRUE THEN
MessageBox("TV", "Always validate")
ELSE
MessageBox("TV", "Sometimes validate")
END IF

of_IsRMBMenu
Description Reports whether the popup menu is enabled.
Access Public
Syntax instancename.of_IsRMBMenu ( )

357
u_tvs

Argument Description
instancename Instance name of u_tvs

Return value Boolean. Returns TRUE if the m_tvs popup menu is enabled and FALSE if it
is not.
Examples This example calls the of_IsRmbMenu function:
IF tv_1.of_IsRMBMenu() = TRUE THEN
MessageBox("TV", "RMB enabled")
ELSE
MessageBox("TV", "RMB disabled")
END IF

of_IsUpdateable
Description Reports whether the TreeView’s data source is updatable.
Access Public
Syntax instancename.of_IsUpdateable ( )
Argument Description
instancename Instance name of u_tvs

Return value Boolean. Returns TRUE if the TreeView’s data source is updatable and FALSE
if it is not.
Usage The pfc_UpdatesPending event calls this function.
Examples This example is from the pfc_UpdatesPending event:
...
If Not of_IsUpdateable() Then Return NO_UPDATESPENDING
...

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_tvs
id String specifying an ID for the message
title String specifying the title of the MessageBox

358
 Chapter 6 Standard Visual User Objects

Argument Description
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in TreeViews.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’tv_error’,’Save’, &
as_error, StopSign!, Ok!, 1)

of_Populate
Description Populates a TreeView item with its child items.
Access Public
Syntax instancename.of_Populate ( parent )
Argument Description
instancename Instance name of u_tvs

359
u_tvs

Argument Description
parent Long specifying the handle of the handle of the TreeView item to
be populated

Return value Integer. Returns the number of items added if the function succeeds and -1 if
an error occurs.
Usage Internal.
Examples The example is from the pfc_Populate event:
IF (al_parent < 0) or IsNull(al_parent) then Return -1
Return of_populate(al_parent)

of_PostUpdate
Description Calls the pfc_PostUpdate event, which clears update flags and allows you to
code additional post-update processing.
Access Public
Syntax instancename.of_PostUpdate ( )
Argument Description
instancename Instance name of u_tvs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage To customize post update processing, extend the pfc_PostUpdate event.
N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize post-update processing,
extend the pfc_PostUpdate event.
Examples This example is from the n_cst_luw of_PostUpdate function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_PostUpdate()
...

of_Reset
Description Deletes all items from both the TreeView and the data source.
Access Public
Syntax instancename.of_Reset ( )

360
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_tvs

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Examples This example calls the of_Reset function:
tv_1.of_Reset()

of_Retrieve
Description Retrieves rows into a DataStore.
Syntax instancename.EVENT of_Retrieve ( parent, args, data )
Argument Description
instancename Instance name of u_tvs
parent Long specifying the handle of the TreeView item under which
new items are retrieved
args 20-element Any array specifying retrieval arguments
data N_ds into which the function places the retrieved rows (passed by
reference)

Return value Long. Returns the number of items retrieved if the function succeeds, 0 if no
action was taken, and -1 if an error occurs.
Examples This example (from a pfc_Retrieve event) calls the of_Retrieve function:
Any la_args[20]
Integer li_level

IF IsValid(inv_levelsource) THEN
li_level = this.of_GetNextLevel(al_parent)
this.inv_levelsource.of_GetArgs(al_parent, &
li_level, la_args)
END IF

Return this.of_Retrieve(al_parent, la_args, &

ads_data)

of_SetAlwaysValidate
Description Specifies whether the default save process always performs validation.
Access Public
Syntax instancename.of_SetAlwaysValidate ( boolean )

361
u_tvs

Argument Description
instancename Instance name of u_tvs
boolean Boolean specifying whether the default save process always
perform validation (TRUE) or only performs validation if a
control has pending updates (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetAlwaysValidate function:
tv_1.of_SetAlwaysValidate(TRUE)

of_SetBase
Description Enables or disables n_cst_tvsrv, which provides basic TreeView services.
Access Public
Syntax instancename.of_SetBase ( boolean )
Argument Description
instancename Instance name of u_tvs
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) basic TreeView services

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_tvsrv. This instance
is named inv_base.
Because all TreeView services are descendants of n_cst_tvsrv (and have
n_cst_tvsrv functions available to them), use this object when you require basic
TreeView services only.
Examples This example calls the of_SetBase function to enable basic TreeView services:
tv_1.of_SetBase(TRUE)

of_SetLevelSource
Description Enables or disables n_cst_tvsrv_levelsource, which provides data access for
TreeView levels.
Access Public
Syntax instancename.of_SetLevelSource ( boolean )

362
 Chapter 6 Standard Visual User Objects

Argument Description
instancename Instance name of u_tvs
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) n_cst_tvsrv_levelsource

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_tvsrv_levelsource.
This instance is named inv_levelsource.
Examples This example calls the of_SetLevelSource function:
tv_1.of_SetLevelSource(TRUE)

of_SetLogicalUnitOfWork
Description Enables or disables n_cst_luw, which provides the logical unit of work service.
Access Protected
Syntax instancename.of_SetLogicalUnitOfWork ( boolean )
Argument Description
instancename Instance name of u_tvs
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) n_cst_luw

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_luw. This instance is
named inv_luw. If you do not enable n_cst_luw, u_tvs enables it automatically.
Examples This example calls the of_SetLogicalUnitOfWork function:
tv_1.of_SetLogicalUnitOfWork(TRUE)

of_SetPrint
Description Enables or disables n_cst_tvsrv_print, which provides the TreeView print
service.
Access Public
Syntax instancename.of_SetPrint ( boolean )

363
u_tvs

Argument Description
instancename Instance name of u_tvs
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) the TreeView print service

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_tvsrv_print. This
instance is named inv_print.
Examples This example calls the of_SetPrint function:
tv_1.of_SetPrint(TRUE)

of_SetRMBMenu
Description Enables or disables right mouse button support for m_tvs, the TreeView popup
menu.
Access Public
Syntax instancename.of_SetRMBMenu ( boolean )
Argument Description
instancename Instance name of u_tvs
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) right mouse button support

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetRMBMenu function:
tv_1.of_SetRMBMenu(TRUE)

of_SetUpdateable
Description Specifies whether the TreeView is updatable and should be included in the
default save process.
Access Public
Syntax instancename.of_SetUpdateable ( boolean )
Argument Description
instancename Instance name of u_tvs

364
 Chapter 6 Standard Visual User Objects

Argument Description
boolean Boolean indicating whether the TreeView is updatable. All
updatable TreeViews are included in the default save processing

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to enable default save processing for TreeViews that are
updatable (by default, TreeViews are not updatable).
Examples This example calls the of_SetUpdateable function:
tv_1.of_SetUpdateable(FALSE)

of_SetUpdateRequestor
Description Creates a reference to the object requesting an update within a logical unit of
work.
Access Public
Syntax instancename.of_SetUpdateRequestor ( requestor )
Argument Description
instancename Instance name of u_tvs
requestor PowerObject containing the object requesting the update

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_Update function:
...
If IsValid(inv_luw) Then
inv_luw.of_SetUpdateRequestor(apo_requestor)
End If
...

of_Update
Description Saves all rows in the DataStores associated with the TreeView.
Access Public
Syntax instancename.of_Update ( accept, resetflag {, requestor } )
Argument Description
instancename Instance name of u_tvs

365
u_tvs

Argument Description
accept Boolean indicating whether the Update function performs an
AcceptText before saving rows to the database
resetflag Boolean indicating whether the Update function resets the update
flags
requestor PowerObject containing the requestor object

Return value Integer. Returns 1 if the update succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update processing, extend
the pfc_Update event.
Examples This example is from the n_cst_luw of_Update function:
...
If lb_defined Then
li_rc = lpo_tocheck.Function Dynamic of_Update &
(ab_accepttext, ab_resetflag, &
lpo_updaterequestor)
If li_rc < 0 Then Return -1
Continue
End If
...

of_UpdatePrep
Description Calls the pfc_UpdatePrep event, which allows you to code additional update
preparation logic.
Access Public
Syntax instancename.of_UpdatePrep ( )
Argument Description
instancename Instance name of u_tvs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update preparation
processing, extend the pfc_UpdatePrep event.
Examples This example is from the n_cst_luw of_UpdatePrep function:
...
If lb_defined Then
li_rc = &

366
 Chapter 6 Standard Visual User Objects

lpo_tocheck.Function Dynamic of_UpdatePrep ()

If li_rc < 0 Then Return -1
Continue
End If
...

of_UpdatesPending
Description Determines if there are updates pending in the DataStores associated with the
TreeView.
Access Public
Syntax instancename.of_UpdatesPending ( )
Argument Description
instancename Instance name of u_tvs

Return value Integer. Returns values as follows:

• 1 Updates are pending
• 0 No updates pending
• -1 An error occurred
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize pending updates
processing, extend the pfc_UpdatesPending event.
Examples This example calls the of_UpdatesPending function:
...
If lb_defined Then
la_rc = lpo_tocheck.Dynamic of_UpdatesPending ()
...

of_Validation
Description Performs validation on the TreeView data sources.
Access Public
Syntax instancename.of_Validation ( )
Argument Description
instancename Instance name of u_tvs

Return value Integer. Returns 1 if the function succeeds and -1 if a validation error occurs.

367
u_tvs

Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize validation processing,
extend the pfc_Validation event.
Examples This example calls the of_Validation function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_Validation()
...

368
 Chapter 6 Standard Visual User Objects

u_vpb
Description VerticalProgressBar visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
VerticalProgressBar control.
U_vpb event scripts provide integration with PFC menus.
See also u_hpb
u_progressbar

Events
U_vpb includes one precoded event script:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_vpb includes precoded object functions:
of_GetParentWindow
of_MessageBox

369
u_vpb

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_vpb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_vpb GetFocus event calls this function.
Examples This example is from the u_vpb GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_vpb
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

370
 Chapter 6 Standard Visual User Objects

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in VerticalProgressBar
controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’vpb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

371
u_vsb

u_vsb
Description VerticalScrollBar visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
VerticalScrollBar control.
U_vsb event scripts provide integration with PFC menus.
See also u_hsb

Events
U_vsb includes one precoded event script:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_vsb includes precoded object functions:
of_GetParentWindow
of_MessageBox

372
 Chapter 6 Standard Visual User Objects

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_vsb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_vsb GetFocus event calls this function.
Examples This example is from the u_vsb GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_vsb
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

373
u_vsb

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in VerticalScrollBar
controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’vsb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

374
 Chapter 6 Standard Visual User Objects

u_vtb
Description VerticalTrackBar visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships PFC visual user objects are designed to be used with windows that are
descendants of w_master.
Usage Use this visual object in windows instead of the standard PowerBuilder
VerticalTrackBar control.
U_vtb event scripts provide integration with PFC menus.
See also u_htb

Events
U_vtb includes one precoded event script:
GetFocus

GetFocus
Description Updates the parent window so it can set MicroHelp.
Usage This event calls the pfc_ControlGotFocus event in the parent.

Functions
U_vtb includes precoded object functions:
of_GetParentWindow
of_MessageBox

375
u_vtb

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_vtb
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
If no parent window is found, window returns NULL.
Usage The u_vtb GetFocus event calls this function.
Examples This example is from the u_vtb GetFocus event:
Window lw_parent

IF gnv_app.of_GetMicrohelp() THEN
of_GetParentWindow(lw_parent)
IF IsValid(lw_parent) THEN
lw_parent.Dynamic Event &
pfc_ControlGotFocus (this)
END IF
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of u_vtb
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

376
 Chapter 6 Standard Visual User Objects

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in VerticalTrackBar
controls.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’vtb_error’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

377
u_vtb

378
CH A PTE R 7 Custom Visual User Objects

About this chapter This chapter describes the custom visual user objects in PFC.
Contents The custom visual user objects are listed in alphabetical order. Each
object’s discussion includes an alphabetical listing of instance variables,
events, and object functions.

379
u_base

u_base
Description Base object for custom visual user objects (such as u_calculator and
u_calendar).
U_base is a self-updating object.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships n_cst_infoattrib
n_cst_luw
n_cst_resize
Usage Use this object as the base object for custom visual user objects. U_base
contains all the events and functions necessary for a PFC self updating object.
For more on self updating objects see n_cst_luw on page 1051.
To use u_base:
1 Use the User Object painter to create a descendant of u_base.
2 Add controls, events, and functions as necessary.
Descendants u_calculator
u_calendar
u_progressbar
u_tabpg
See also n_base

380
 Chapter 7 Custom Visual User Objects

Instance variables
U_base includes instance variables:
Instance variable Description Data type Access Usage
CONTINUE_ACTION Constant set to 1 Integer Public Internal
FAILURE Constant set to -1 Integer Public Internal
ib_alwaysvalidate Controls whether the Boolean Protected Set with
save process includes of_SetAlwaysValidate
all objects in the (default is FALSE)
validation process
ib_isupdateable Indicates whether the Boolean Protected Set with of_SetUpdateable
object can be updated (default is FALSE)
inv_luw Reference variable for n_cst_luw Protected Set with
logical unit of work of_SetLogicalUnitOfWork
service
inv_resize Reference variable for n_cst_resize Public Set with of_SetResize
resize service
ipo_pendingupdates[ ] Default list of objects PowerObject Protected Internal
to be updated
ipo_updateobjects[ ] Customized list of PowerObject Protected Internal
objects to be updated
ipo_tempupdateobjects[ ] One-time list of objects PowerObject Protected Internal
to be updated
ipo_updaterequestor Owner of the save PowerObject Protected Internal
process
NO_ACTION Constant set to 0 Integer Public Internal
PREVENT_ACTION Constant set to 0 Integer Public Internal
SUCCESS Constant set to 1 Integer Public Internal

Events
U_base includes precoded events:
Destructor pfc_UpdatePrep
pfc_AcceptText pfc_UpdatesPending
pfc_PostUpdate pfc_Validation
pfc_Update Resize

381
u_base

Destructor
Description Destroys all enabled service objects.
Usage This event executes when the control is destroyed or the window closes.

pfc_AcceptText
Description Calls the n_cst_luw of_AcceptText function, which in turn calls the
of_AcceptText function for all controls that implement it.
Syntax instancename.EVENT pfc_AcceptText ( controlarray, focusonerror )
Argument Description
instancename Instance name of the u_base descendant
controlarray PowerObject array containing the controls for which to accept
text. From within the pfc_AcceptText event, access this value
through the apo_control argument
focusonerror Boolean specifying whether to set focus on a DataWindow
column with errors. From within the pfc_AcceptText event,
access this value through the ab_focusonerror argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The of_AcceptText function calls this event.

pfc_PostUpdate
Description Calls the n_cst_luw of_PostUpdate function, which in turn calls the
of_PostUpdate function for all controls that implement it.
Syntax instancename.EVENT pfc_PostUpdate ( controlarray )
Argument Description
instancename Instance name of the u_base descendant
controlarray PowerObject array containing the controls for which to perform
post update processing. From within the pfc_AcceptText event,
access this value through the apo_control argument

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The of_PostUpdate function calls this event.
You can extend this event to perform additional post-update processing.

382
 Chapter 7 Custom Visual User Objects

pfc_Update
Description Calls the n_cst_luw of_Update function, which in turn calls the of_Update
function for all controls that implement it.
Syntax instancename.EVENT pfc_Update ( controlarray )
Argument Description
instancename Instance name of the u_base descendant
controlarray PowerObject array containing the controls to be updated. From
within the pfc_Update event, access this value through the
apo_control argument

Return value Integer. Returns 1 if the event succeeds and -1 if one or more update errors
occur.
Usage The of_Update function calls this event.

pfc_UpdatePrep
Description Empty user event to which you can add code that prepares for update.
Syntax instancename.EVENT pfc_UpdatePrep ( controls )
Argument Description
instancename Instance name of the u_base descendant
controls PowerObject array containing the objects to update. This
argument is accessed through the apo_control argument

Return value Long. Return 1 if the update preparation succeeds and -1 to halt the update
process.
Usage The of_UpdatePrep function calls this event.

pfc_UpdatesPending
Description Calls the n_cst_luw of_UpdatesPending function, which in turn calls the
of_UpdatesPending function for all controls that implement it.
Syntax instancename.EVENT pfc_UpdatesPending ( controlarray )
Argument Description
instancename Instance name of the u_base descendant
controlarray PowerObject array containing controls to be tested for pending
updates

383
u_base

Return value Integer. Returns values as follows:

1 Pending updates were found
0 No pending updates
-1 AcceptText failed
Usage The of_UpdatesPending function calls this event.

pfc_Validation
Description Calls the n_cst_luw of_Validation function, which in turn calls the
of_Validation function for all controls that implement it.
Syntax instancename.EVENT pfc_Validation ( controlarray )
Argument Description
instancename Instance name of the u_base descendant
controlarray PowerObject control array containing controls to be validate

Return value Integer. Returns 1 if there are no validation errors and -1 if a validation error
occurs.
Usage The of_Validation function calls this event.

Resize
Description Triggers resize processing, if enabled for the object.
Usage This event executes when the user resizes the window and the custom visual
user object instance has been registered with the window or tab on which it is
placed.
To enable resize processing, you must enabled the resize service for the u_base
descendant instance and for the window or tab containing the instance.

Functions
U_base contains precoded object functions:
of_AcceptText of_SetLogicalUnitOfWork
of_GetInfo of_SetResize
of_GetParentWindow of_SetUpdateable
of_GetUpdateObjects of_SetUpdateObjects
of_IsAlwaysValidate of_SetUpdateRequestor

384
 Chapter 7 Custom Visual User Objects

of_IsUpdateable of_Update
of_MessageBox of_UpdatePrep
of_PostUpdate of_UpdatesPending
of_SetAlwaysValidate of_Validation

of_AcceptText
Description Calls the pfc_AcceptText event.
Access Public
Syntax instancename.of_AcceptText ( focusonerror )
Argument Description
instancename Instance name of the u_base descendant
focusonerror Boolean indicating whether PFC sets focus to the first item in
error when an error occurs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize accept text processing,
extend the pfc_AcceptText event.
Examples This example is from the n_cst_luw of_AcceptText function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_AcceptText &
(ab_focusonerror)
If li_rc < 0 Then Return -1

...

of_GetInfo
Description Retrieves object information.
Access Public
Syntax instancename.of_GetInfo ( infoobject )
Argument Description
instancename Instance name of the u_base descendant
infoobject N_cst_infoattrib instance into which the function places
information (passed by reference)

385
u_base

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_GetInfo function:
n_cst_infoattrib lnv_info

w_emplist.of_GetInfo(lnv_info)
MessageBox("Info", &
"Description: " + lnv_info.is_description &
+ ". Name: " + lnv_info.is_name)

of_GetParentWindow
Description Retrieves a reference to the parent window.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of u_base
window Window variable into which the function places a reference to
the parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds, -1 if there is no parent window, and
NULL if no parent window is found.
Examples This example calls the of_GetParentWindow function:
Integer li_return
Window lw_window
...
li_return = uo_calc.of_GetParentWindow(lw_window)
...

of_GetUpdateObjects
Description Retrieves the current default array of objects affected by the update process.
Access Protected
Syntax instancename.of_GetUpdateObjects ( objects )
Argument Description
instancename Instance name of the u_base descendant
objects PowerObject array into which the function places objects to be
updated (passed by reference)

386
 Chapter 7 Custom Visual User Objects

Return value Integer. Returns the number of elements in the objects array if the function
succeeds and -1 if an error occurs.
Examples This example calls the of_GetUpdateObjects function:
PowerObject lpo_objs[ ]
Integer li_return, li_count

li_return = this.of_GetUpdateObjects(lpo_objs)
FOR li_count = 1 to li_return
IF lpo_objs[li_count] = ids_data THEN
Return 1
END IF
NEXT
li_return++
lpo_objs[li_return] = ids_data
Return this.of_SetUpdateObjects(lpo_objs)

of_IsAlwaysValidate
Description Reports whether the default save process always performs validation.
Access Protected
Syntax instancename.of_IsAlwaysValidate ( )
Argument Description
instancename Instance name of the u_base descendant

Return value Boolean. Returns TRUE if the default save process always performs validation
and FALSE if it does not.
Examples This example calls the of_IsAlwaysValidate function:
IF this.of_IsAlwaysValidate() = TRUE THEN
MessageBox("Base", "Always validate")
ELSE
MessageBox("Base", "Sometimes validate")
END IF

of_IsUpdateable
Description Reports whether the object is updatable.
Access Protected
Syntax instancename.of_IsUpdateable ( )

387
u_base

Argument Description
instancename Instance name of the u_base descendant

Return value Boolean. Returns TRUE if the window is updatable and FALSE if it is not.
Usage Internal.
Examples This example is from the pfc_UpdatesPendingRef event:
...
If Not of_IsUpdateable() Then Return NO_UPDATESPENDING
...

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of the u_base descendant
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!

388
 Chapter 7 Custom Visual User Objects

Argument Description
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in custom visual user
objects.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’cvuo_error’,’Save’, &
as_error, StopSign!, Ok!, 1)

of_PostUpdate
Description Calls the pfc_PostUpdate event.
Access Public
Syntax instancename.of_PostUpdate ( )
Argument Description
instancename Instance name of the u_base descendant

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize post-update processing,
extend the pfc_PostUpdate event.
Examples This example is from the n_cst_luw of_PostUpdate function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_PostUpdate()
...

of_SetAlwaysValidate
Description Specifies whether the default save process always performs validation.
Access Protected
Syntax instancename.of_SetAlwaysValidate ( boolean )

389
u_base

Argument Description
instancename Instance name of the u_base descendant
boolean Boolean specifying whether the default save process always
performs validation (TRUE) or only performs validation if a
control has pending updates (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetAlwaysValidate function:
this.of_SetAlwaysValidate(TRUE)

of_SetLogicalUnitOfWork
Description Enables or disables n_cst_luw, which provides the logical unit of work service.
Access Public
Syntax instancename.of_SetLogicalUnitOfWork ( boolean )
Argument Description
instancename Instance name of the u_base descendant
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) n_cst_luw

Return value Integer. Returns 1 if the function succeeds, 0 if the service is already enabled,
and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_luw. This instance is
named inv_luw. If you do not enable n_cst_luw, u_base enables it
automatically.
Examples This example calls the of_SetLogicalUnitOfWork function:
this.of_SetLogicalUnitOfWork(TRUE)

of_SetResize
Description Enables or disables n_cst_resize (the resize service).
Access Public
Syntax instancename.of_SetResize ( boolean )
Argument Description
instancename Instance name of u_base

390
 Chapter 7 Custom Visual User Objects

Argument Description
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) an instance of n_cst_resize

Return value Integer. Returns 1 if the function succeeds, 0 if the resize service is already
enabled, and -1 if an error occurs.
Usage After calling this function, apply n_cst_resize functions as necessary to the
controls contained in the u_base descendant.
Examples This example calls the of_SetResize function:
this.of_SetResize(TRUE)

of_SetUpdateable
Description Specifies whether the object is updatable.
Access Protected
Syntax instancename.of_SetUpdateable ( boolean )
Argument Description
instancename Instance name of the u_base descendant
boolean Boolean indicating whether the window is updatable

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to enable default save processing. By default, u_base is not
updatable.
Examples This example calls the of_SetUpdateable function:
this.of_SetUpdateable(TRUE)

of_SetUpdateObjects
Description Sets a new default array containing objects for which updates are attempted.
Access Protected
Syntax instancename.of_SetUpdateObjects ( requestor )
Argument Description
instancename Instance name of u_dw
requestor PowerObject array containing the object to be updated

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.

391
u_base

Usage Call this function to customize the objects updated by the save process. You
can even add other windows to the save process.
Examples This example calls the of_SetUpdateObjects function:
PowerObject lpo_objs[ ]
Integer li_count

lpo_objs = this.control
li_count = UpperBound(lpo_objs)
li_count++
// Update w_other as well as this object
lpo_objs[li_count] = w_other
Return this.of_SetUpdateObjects(lpo_objs)

of_SetUpdateRequestor
Description Creates a reference to the object requesting an update within a logical unit of
work.
Access Protected
Syntax instancename.of_SetUpdateRequestor ( requestor )
Argument Description
instancename Instance name of the u_base descendant
requestor PowerObject containing the object requesting the update

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.

of_Update
Description Calls the pfc_Update event.
Access Public
Syntax instancename.of_Update ( accept, resetflag {, requestor} )
Argument Description
instancename Instance name of the u_base descendant
accept Boolean indicating whether the Update function performs an
AcceptText before saving rows to the database
resetflag Boolean indicating whether the Update function resets the update
flags

392
 Chapter 7 Custom Visual User Objects

Argument Description
requestor PowerObject containing the requestor object
(optional)

Return value Integer. Returns 1 if the update succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update processing, extend
the pfc_Update event.
Examples This example is from the n_cst_luw of_Update function:
...
If lb_defined Then
li_rc = lpo_tocheck.Function Dynamic of_Update &
(ab_accepttext, ab_resetflag, &
lpo_updaterequestor)
If li_rc < 0 Then Return -1
Continue
End If
...

of_UpdatePrep
Description Calls the pfc_UpdatePrep event, which allows you to code additional update
preparation logic.
Access Public
Syntax instancename.of_UpdatePrep ( )
Argument Description
instancename Instance name of the u_base descendant

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update preparation
processing, extend the pfc_UpdatePrep event.
Examples This example is from the n_cst_luw of_UpdatePrep function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_UpdatePrep()
If li_rc < 0 Then Return -1
Continue

393
u_base

End If
...

of_UpdatesPending
Description Calls the pfc_UpdatesPending event.
Access Public
Syntax instancename.of_UpdatesPending ( )
Argument Description
instancename Instance name of the u_base descendant

Return value Integer. Returns values as follows:

• 1 Updates are pending
• 0 No updates pending
• -1 An error occurred
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize pending updates
processing, extend the pfc_UpdatesPending event.
Examples This example calls the of_UpdatesPending function:
...
If lb_defined Then
la_rc = lpo_tocheck.Dynamic of_UpdatesPending()
...

of_Validation
Description Calls the pfc_Validation event.
Access Public
Syntax instancename.of_Validation ( )
Argument Description
instancename Instance name of the u_base descendant

Return value Integer. Returns 1 if the function succeeds and -1 if a validation error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize validation processing,
extend the pfc_Validation event.

394
 Chapter 7 Custom Visual User Objects

Examples This example calls the of_Validation function:

...
If lb_defined Then li_rc = &
lpo_tocheck.Function Dynamic of_Validation()
...

395
u_calculator

u_calculator
Description Calculator object for use with numeric values in DataWindow and EditMask
controls. Users use the calculator to enter values and calculations, which the
object displays in the associated DataWindow column or EditMask control.
You typically use the calculator object as a dropdown object, displaying when
a DataWindow column gets focus or when the user clicks the dropdown arrow.
However, you can also place the calculator object directly onto a window.
Ancestry

Library PFCAPSRV.PBL
PFEAPSRV.PBL
Object relationships n_cst_dropdown
n_cst_calculatorattrib
n_cst_infoattrib
n_cst_propertyattrib
u_dw
u_em

396
 Chapter 7 Custom Visual User Objects

Usage Use this object with EditMask controls that display numeric or decimal values
or with DataWindow columns that display numeric values. For automatic
calculator display, DataWindow columns must use the DropDownListBox edit
style. For manual calculator display, DataWindow columns can use the
DropDownListBox, Edit, or EditMask edit style.
To use this object for DataWindow columns:
1 Determine which columns in your DataWindow object are appropriate for
a dropdown calculator. Use the DataWindow painter to assign the
DropDownListBox, Edit, or EditMask edit style to these columns.
2 In the Window painter, define a DataWindow control based on u_dw.
3 Enable the dropdown calculator for the DataWindow by calling the
of_SetDropDownCalculator function. This example is from the
DataWindow control’s Constructor event:
this.of_SetDropDownCalculator(TRUE)
4 Register one or more columns by calling the of_Register function:
this.iuo_calculator.of_Register("salary", &
this.iuo_calculator.DDLB_WITHARROW))
5 Specify whether the dropdown closes on a single-click by calling the
of_SetCloseOnClick function:
this.iuo_calculator.of_SetCloseOnClick(TRUE)
For information on using u_calculator with EditMask controls, see the PFC
User’s Guide.
See also n_cst_dropdown
u_calendar
u_dw
u_em

Instance variables
U_calculator includes instance variables:
Instance variable Description Data type Access Usage
DDLB Constant set to 2 Integer Public Use with of_ Register
DDLB_WITHARROW Constant set to 3 Integer Public Use with of_ Register
EMPTY Constant set to String Protected Internal
empty string

397
u_calculator

Instance variable Description Data type Access Usage

ib_closeonclick Controls close on Boolean Protected Set with
click of_SetCloseOnClick
ib_initialvalue Controls whether Boolean Protected Set with
blank fields are of_SetInitialValue
initialized
ib_validresetvalue Reports whether Boolean Protected Internal
associated field
contains a
number
idbl_repeatvalue Repeat value Double Protected Internal
idbl_value Running total Double Protected Internal
idrg_requestor Generic reference DragObject Protected Internal
idw_requestor Associated DataWindow Protected Internal
DataWindow
control
iem_requestor Associated EditMask Protected Internal
EditMask control
ii_dwcolumnstyle[] Edit styles of Integer Protected Set with of_Register
registered
columns
inv_calculatorattrib Calculator n_cst_calculatorattrib Protected Internal
information
inv_dropdown Reference to n_cst_dropdown Public Internal
dropdown service
is_curroperator Current operator String Protected Internal
is_currvalue Current value String Protected Internal
is_dwcolumns[ ] Registered String Protected Set with of_Register
columns
is_dwcolumnsexp[ ] Original String Protected Set by of_Register
properties for
registered
columns
is_prevkeystroke Previous key String Protected Internal
is_repeatoperator Repeat operator String Protected Internal
NONE Constant set to 1 Integer Public Use with of_Register

398
 Chapter 7 Custom Visual User Objects

Events
U_calculator includes precoded events:
ButtonClicked Key
Constructor LoseFocus
Destructor pfc_DropDown
GetFocus

ButtonClicked
Description Calls the of_ButtonClicked function.
Applies to Dw_calculator
Usage This event executes when the user clicks a command button, types a number,
types an operator, or types a period.

Constructor
Description Initializes object settings.
Applies to Dw_calculator and u_calculator
Usage This event executes when the object is created.

Destructor
Description Destroys the inv_dropdown instance variable.
Applies to U_calculator
Usage This event executes when the u_calculator instance is destroyed.

GetFocus
Description Calls the of_RedirectFocus function.
Applies to Dw_calculator
Usage This event executes when a control receives focus, typically by clicking.

Key
Description Determines which key was pressed and calls the of_ButtonClicked function.
Applies to Dw_calculator

399
u_calculator

Usage This event executes when the user presses a key.

LoseFocus
Description Hides the calculator.
Applies to Dw_calculator
Usage This event executes when the calculator loses focus.

pfc_DropDown
Description Calls the of_DropDown function.
Applies to U_calculator
Return value Integer. Returns 1 if the event succeeds, 0 if the DataWindow column has not
been registered, and -1 if an error occurs.
Usage This event is called by the u_dw pfc_DDCalculator event.

Functions
U_calculator contains precoded object functions:
of_ButtonClicked of_PerformMath
of_DropDown of_RedirectFocus
of_GetInfo of_Register
of_GetPropertyInfo of_Reset
of_GetRegisterable of_SetCloseOnClick
of_GetRegistered of_SetDropDown
of_GetRegisteredStyle of_SetFocusOnRequestor
of_IsCloseOnClick of_SetInitialValue
of_IsDropDown of_SetRequestor
of_IsInitialValue of_SetValue
of_IsNumericType of_SetValueOnRequestor
of_IsOperator of_UnRegister
of_IsRegistered

of_ButtonClicked
Description Processes button clicks.

400
 Chapter 7 Custom Visual User Objects

Access Protected
Syntax dwcontrol.instancename.of_ButtonClicked ( key )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)
key String specifying the text of the clicked button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from a the u_calculator dw_employee ButtonClicked event:
...
If Len(ls_buttontext) > 0 Then
of_ButtonClicked(ls_buttontext)
End If
...

of_DropDown
Description Displays the dropdown calculator in the appropriate location.
Access Public
Syntax dwcontrol.instancename.of_DropDown ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)

Return value Integer. Returns 1 if the function succeeds, 0 if the current DataWindow
column has not been registered, and -1 if an error occurs.
Usage The pfc_DropDown event calls this function. If the current DataWindow
column is not registered, this function returns 0 and does not display the
calculator.
Examples This example is from the pfc_DropDown event:
Return of_DropDown()

401
u_calculator

of_GetInfo
Description Retrieves object information.
Access Public
Syntax dwcontrol.instancename.of_GetInfo ( infoobject )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for
this value is iuo_calculator)
infoobject N_cst_infoattrib instance into which the function places
information (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The DataWindow Properties window calls this function to access service
information.
Examples This example calls the of_GetInfo function:
n_cst_infoattrib lnv_info

dw_1.iuo_calculator.of_GetInfo(lnv_info)
MessageBox("Info", &
"Description: " + lnv_info.is_description &
+ ". Name: " + lnv_info.is_name)

of_GetPropertyInfo
Description Retrieves information about the service’s properties.
Access Public
Syntax dwcontrol.instancename.of_GetPropertyInfo ( propertyobject )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calculator (the u_dw and u_em default for
this value is iuo_calculator)
propertyobject N_cst_propertyattrib instance into which the function places
property information (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The DataWindow Properties window calls this function to access service
information.

402
 Chapter 7 Custom Visual User Objects

Examples This example calls the of_GetPropertyInfo function:

n_cst_propertyattrib lnv_prop

dw_1.iuo_calculator.of_GetPropertyInfo(lnv_prop)
MessageBox("Info", &
"Description: " + lnv_prop.is_description &
+ ". Name: " + lnv_prop.is_name &
+ ". Property tab text: " + &
lnv_prop.is_propertytabtext)

of_GetRegisterable
Description Retrieves an array of registerable DataWindow columns. Registerable
DataWindow columns are numeric and use the DropDownListBox, Edit, or
EditMask edit style.
Access Public
Syntax dwcontrol.instancename.of_GetRegisterable ( columns )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calculator (the u_dw default for this value is
iuo_calculator)
columns Unbounded string array into which the function places the names of
columns that have been registered with this instance of the
dropdown calculator (passed by reference)

Return value Integer. Returns the number of entries in the columns array if the function
succeeds and -1 if an error occurs.
Examples This example calls the of_GetRegisterable function:
...
li_rc = &
idw_requestor.iuo_calculator.of_GetRegisterable &
(ls_allcols)
...

of_GetRegistered
Description Retrieves an array of registered DataWindow columns.
Access Public
Syntax dwcontrol.instancename.of_GetRegistered ( columns {, colstyle } )

403
u_calculator

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calculator (the u_dw default for this value is
iuo_calculator)
columns Unbounded string array into which the function places the names
of columns that have been registered with this instance of the
dropdown calculator (passed by reference)
colstyle Unbounded Integer array into which the function places the styles
(optional) of columns that have been registered with this instance of the
dropdown calculator (passed by reference)

Return value Integer. Returns the number of entries in the columns array if the function
succeeds and -1 if an error occurs.
Examples This example calls the of_GetRegistered function:
String ls_columns[ ], ls_display
Integer li_return, li_count

li_return = &
dw_1.iuo_calculator. of_GetRegistered &
(ls_columns)
FOR li_count = 1 to li_return
ls_display += ls_columns[li_count] + "~r~n"
NEXT
MessageBox("Columns", ls_display)

of_GetRegisteredStyle
Description Retrieves the display style for a specified column.
Access Public
Syntax dwcontrol.instancename.of_GetRegisteredStyle ( column )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calculator (the u_dw default for this value is
iuo_calculator)
column String containing the DataWindow column for which the function
returns the display style

Return value Integer. Returns the column style if the function succeeds, 0 if the column is
not registered, and -1 if an error occurs.

404
 Chapter 7 Custom Visual User Objects

Examples This example calls the of_GetRegisteredStyle function:

Integer li_return

li_return = &
dw_1.iuo_calculator.of_GetRegisteredStyle &
("start_date")
MessageBox("Display Style", &
"Display style is " + String(li_return))

of_IsCloseOnClick
Description Reports whether the u_calculator instance closes when the user clicks the equal
sign.
Access Public
Syntax dwcontrol.instancename.of_IsCloseOnClick ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)

Return value Boolean. Returns TRUE if the u_calculator instance closes when the user
clicks the equal sign and FALSE if it does not.
Examples This example calls the of_IsCloseOnClick function:
Boolean lb_close
n_cst_conversion lnv_conversion

lb_close = &
dw_1.iuo_calculator.of_IsCloseOnClick()
MessageBox("Calculator", "Close on click is " &
+ lnv_conversion.of_String(lb_close))

of_IsDropDown
Description Reports whether the u_calculator instance has enabled n_cst_dropdown.
Access Public
Syntax dwcontrol.instancename.of_IsDropDown ( )

405
u_calculator

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)

Return value Boolean. Returns TRUE if the u_calculator instance has enabled
n_cst_dropdown and FALSE if it has not.
Usage The dropdown service is referenced by the inv_dropdown instance variable.
Examples This example calls the of_IsDropDown function:
Boolean lb_dropdown
n_cst_conversion lnv_conversion

lb_dropdown = &
dw_1.iuo_calculator.of_IsDropDown()
MessageBox("Calculator", &
"DropDown behavior is " &
+ lnv_conversion.of_String(lb_dropdown))

of_IsInitialValue
Description Reports whether the u_calculator instance initializes blank fields with zero
when the calculator displays.
Access Public
Syntax dwcontrol.instancename.of_IsInitialValue ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)

Return value Boolean. Returns TRUE if the calculator initializes blank fields with a zero and
FALSE if it does not.
Examples This example calls the of_IsInitialValue function:
Boolean lb_init
n_cst_conversion lnv_conversion

lb_init = &
dw_1.iuo_calculator.of_IsInitialValue()

406
 Chapter 7 Custom Visual User Objects

MessageBox("Calculator", "Initialize is " &

+ lnv_conversion.of_String(lb_init))

of_IsNumericType
Description Reports whether a specified DataWindow column data type is numeric
(decimal, long, or number).
Access Protected
Syntax dwcontrol.instancename.of_IsNumericType ( datatype )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)
datatype String specifying the data type

Return value Boolean. Returns TRUE if datatype is numeric and FALSE if it is not.
Usage Internal.
Examples This example is from the of_DropDown function:
...
IF IsValid(idw_requestor) THEN
ls_colname = idw_requestor.GetColumnName()
IF NOT of_IsRegistered(ls_colname) THEN
Return 0
END IF
ls_coltype = &
idw_requestor.Describe(ls_colname+".coltype")
IF NOT of_IsNumericType(ls_coltype) THEN
Return -1
END IF
END IF
...

of_IsOperator
Description Reports whether a passed value is an arithmetic operator (/, *, +, or -).
Access Protected
Syntax dwcontrol.instancename.of_IsOperator ( operator )

407
u_calculator

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)
operator String containing the value to be tested

Return value Boolean. Returns TRUE if operator is /, *, +, or - and FALSE if it is not.

Usage Internal.
Examples This example is from the of_ButtonClicked function:
...
CASE ’/’, ’*’, ’+’, ’-’, ’=’
IF of_IsOperator(as_key) AND &
of_IsOperator(is_prevkeystroke) THEN
is_prevkeystroke = as_key
is_curroperator = as_key
Return 1
END IF
...

of_IsRegistered
Description Reports whether a specified DataWindow column has been registered.
Access Public
Syntax dwcontrol.instancename.of_IsRegistered ( column )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calculator (the u_dw default for this value is
iuo_calculator)
column String specifying the column to search for

Return value Boolean. Returns TRUE if column has been registered and FALSE if it has not.
Examples This example calls the of_IsRegistered function:
...
IF NOT this.iuo_calculator.of_IsRegistered &
("salary") THEN
this.iuo_calculator.of_Register("salary")
END IF
...

408
 Chapter 7 Custom Visual User Objects

of_PerformMath
Description Updates the running total, using the specified operand and operator.
Access Protected
Syntax dwcontrol.instancename.of_PerformMath ( value, operator, operand )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)
value Double into which the function places the running total (passed by
reference)
operator String specifying the operator
operand Double containing the number to be used in the calculation

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_ButtonClicked function:
...
IF of_PerformMath(ldbl_value, &
is_curroperator, ldbl_currvalue) < 0 THEN
Return -1
END IF
...

of_RedirectFocus
Description Prevents the u_calculator instance from getting focus while it is hidden.
Access Protected
Syntax dwcontrol.instancename.of_RedirectFocus ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.

409
u_calculator

Examples This example is from the dw_employee GetFocus event:

Post of_RedirectFocus()

of_Register
Registers columns that use the dropdown calculator. There are two syntaxes:
To register Use
One or all eligible columns, optionally specifying a display style Syntax 1
All eligible columns using a specified display style Syntax 2

Syntax 1 Register columns with an optional display style

Description Registers one or all eligible columns in a DataWindow. Eligible columns use a
numeric data type and have the Edit, EditMask, or DropDownListBox edit
style.
Access Public
Syntax dwcontrol.instancename.of_Register ( { column {, style } } )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calculator (the u_dw default for this is
iuo_calculator)
column (Optional) String specifying the column to be registered. This
column must have a numeric data type. If you omit this argument,
the function registers all numeric columns
style (Optional) Integer or u_calculator constant specifying the display
style of registered DataWindow columns:
• 1 or NONE (default) For columns that use the
DropDownListBox edit style, the calculator displays
automatically when the column gets focus. For columns that use
the Edit and EditMask edit styles, the calculator does not display
automatically; instead, you display the calculator by coding a
call to the u_dw pfc_DDCalculator event
• 2 or DDLB The function converts registered columns to the
DropDownListBox edit style. Users display the calculator by
clicking the down arrow, which disappears when the calculator
displays
• 3 or DDLB_WITHARROW The function converts registered
columns to the DropDownListBox edit style. Users display the
calculator by clicking the down arrow, which remains when the
calculator displays

410
 Chapter 7 Custom Visual User Objects

Return value Integer. Returns the number of columns registered if the function succeeds, 0
if the column was already registered, and -1 if an error occurs. The number of
columns registered includes hidden columns.
Usage Register all appropriate DataWindow columns. You typically call this function
in the DataWindow Constructor event.
To register all eligible columns in a DataWindow using a specified display
style, see Syntax 2.
Examples This example from a DataWindow Constructor event calls the of_Register
function:
this.of_SetTransObject(SQLCA)
this.of_SetDropDownCalculator(TRUE)
this.iuo_calculator.of_Register ("salary", &
this.iuo_calculator.NONE)
this.Event pfc_Retrieve()

Syntax 2 Register columns with a display style

Description Registers all eligible columns in a DataWindow using the specified display
style. Eligible columns use a numeric data type and have the Edit, EditMask,
or DropDownListBox edit style.
Access Public
Syntax dwcontrol.instancename.of_Register (style )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calculator (the u_dw and u_em default for
this is iuo_calculator)

411
u_calculator

Argument Description
style Integer or u_calculator constant specifying the display style of
registered DataWindow columns:
• 1 or NONE For columns that use the DropDownListBox
edit style, the calculator displays automatically when the
column gets focus. For columns that use the Edit and
EditMask edit styles, the calculator does not display
automatically; instead, you display the calculator by coding a
call to the u_dw pfc_DDCalculator event
• 2 or DDLB The function converts registered columns to the
DropDownListBox edit style. Users display the calculator by
clicking the down arrow, which disappears when the
calculator displays
• 3 or DDLB_WITHARROW The function converts registered
columns to the DropDownListBox edit style. Users display
the calculator by clicking the down arrow, which remains
when the calculator displays

Return value Integer. Returns the number of columns registered if the function succeeds and
-1 if an error occurs. The number of columns registered includes hidden
columns.
Usage Register all appropriate DataWindow columns. You typically call this function
in the DataWindow Constructor event.
To register one or all eligible columns in a DataWindow, optionally specifying
a display style, see Syntax 1.
Examples This example from a DataWindow Constructor event calls the of_Register
function:
this.of_SetTransObject(SQLCA)
this.of_SetDropDownCalculator(TRUE)
this.iuo_calculator. of_Register &
(this.iuo_calculator.NONE)
this.Event pfc_Retrieve()

of_Reset
Description Resets the u_calculator running total to that displayed in the DataWindow
column or EditMask control (or to today’s date if the date displayed is not
valid).
Access Public
Syntax dwcontrol.instancename.of_Reset ( )

412
 Chapter 7 Custom Visual User Objects

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for
this value is iuo_calculator)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_DropDown function:
...
of_Reset()
...

of_SetCloseOnClick
Description Specifies whether to hide the u_calculator instance when the user clicks the
equal sign.
Access Public
Syntax dwcontrol.instancename.of_SetCloseOnClick ( boolean )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for
this value is iuo_calculator)
boolean Boolean specifying whether to hide the dropdown calculator
when the user clicks the equal sign (TRUE) or leave it displayed
(FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetCloseOnClick function:
this.of_SetTransObject(SQLCA)
this.of_SetDropDownCalculator(TRUE)
this.iuo_calculator.of_Register()
this.iuo_calculator.of_SetCloseOnClick(FALSE)

of_SetDropDown
Description Enables or disables the dropdown service (n_cst_dropdown).

413
u_calculator

Access Public
Syntax dwcontrol.instancename.of_SetDropDown ( boolean )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for
this value is iuo_calculator)
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) the dropdown service

Return value Integer. Returns 1 if the function succeeds, -0 if the dropdown service already
exists, and -1 if an error occurs.
Examples This example is from the u_calculator Constructor event:
...
IF inv_calculatorattrib.ib_dropdown THEN
this.Visible = FALSE
of_SetDropDown(TRUE)
END IF
...

of_SetFocusOnRequestor
Description Retrieves focus to the associated DataWindow column or EditMask control.
Access Protected
Syntax dwcontrol.instancename.of_SetFocusOnRequestor ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for
this value is iuo_calculator)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_RedirectFocus function:
If this.Visible = False Then
Return of_SetFocusOnRequestor()
End If
Return 1

414
 Chapter 7 Custom Visual User Objects

of_SetInitialValue
Description Specifies whether the u_calculator instance initializes blank fields with zero
when the calculator displays.
Access Public
Syntax dwcontrol.instancename.of_SetInitialValue ( boolean )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)
boolean Boolean indicating whether the calculator initializes blank fields
with zero (TRUE) or not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage For DataWindows that disable this option, if a user displays the dropdown
calculator and moves directly to another column, the original column retains a
status of NotModified!.
Examples This example calls the of_SetInitialValue function:
this.of_SetTransObject(SQLCA)
this.of_SetDropDownCalculator(TRUE)
this.iuo_calculator.of_Register()
this.iuo_calculator.of_SetInitialValue(TRUE)

of_SetRequestor
Description Associates an instance of u_calculator with a DataWindow or EditMask
control.
Access Public
Syntax dwcontrol.instancename.of_SetRequestor ( requestor )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)
requestor DragObject referencing the DataWindow or EditMask control to
associate with this instance of u_calculator

415
u_calculator

Return value Integer. Returns values as follows:

1 Success
-1 An error occurred
-2 The u_calculator instance has not enabled the dropdown service
-3 The EditMask mask type is not numeric or decimal
Usage EditMask controls must have a mask type of numeric or decimal.
If you are not using the u_calculator object as a dropdown object (displaying it
permanently on a window, user object, or tab), call this function to associate
the u_calculator instance with the EditMask control that displays the results.
Examples This example is from the u_em of_SetDropDownCalculator function:
...
IF ab_switch THEN
IF NOT IsValid (iuo_calculator) THEN
lw_parent.OpenUserObject(iuo_calculator)
iuo_calculator.of_SetRequestor(this)
Return 1
END IF
ELSE
IF IsValid (iuo_calculator) THEN
lw_parent.CloseUserObject(iuo_calculator)
Return 1
END IF
END IF
...

of_SetValue
Description Updates the running total with the specified value.
Access Protected
Syntax dwcontrol.instancename.of_SetValue ( value, sendtorequestor )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for
this value is iuo_calculator)
value Double containing the new value
sendtorequestor Boolean indicating whether to copy value to the requestor object
(TRUE) or not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.

416
 Chapter 7 Custom Visual User Objects

Usage Internal.
Examples This example is from the of_ButtonClicked function:
...
CHOOSE CASE as_key
CASE ’c’
// Clear the current variables.
is_curroperator = EMPTY
is_currvalue = EMPTY
// Clear the repeat variables.
is_repeatoperator = EMPTY
idbl_repeatvalue = 0
// Clear the Running value.
of_SetValue(0, True)
...

of_SetValueOnRequestor
Description Copies the running total to the current DataWindow column or associated
EditMask control.
Access Protected
Syntax dwcontrol.instancename.of_SetValueOnRequestor ( value )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calculator (the u_dw and u_em default for this
value is iuo_calculator)
value String containing the value to set on the requestor object

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_Value function:
...
IF ab_setrequestor THEN
of_SetValueOnRequestor(is_value)
END IF
...

of_UnRegister
Description Removes one or all columns from the list of registered columns.

417
u_calculator

Access Public
Syntax dwcontrol.instancename.of_Register ( { column } )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calculator (the u_dw default for this is
iuo_calculator)
column String specifying the column to be unregistered. If you omit this
(optional) argument, the function unregisters all columns

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_UnRegister function:
...
dw_emp.iuo_calculator.of_UnRegister("salary")
...

418
 Chapter 7 Custom Visual User Objects

u_calendar
Description Calendar object. Users enter dates by clicking on the dropdown calendar,
automatically entering the selected date in the associated field. They change
months by clicking the >> and << buttons and can also navigate the calendar
with keyboard arrow keys.
U_calendar provides support for highlighting:
• Saturdays
• Sundays
• Holidays
• Marked days (any other special days that might apply to your application)
Ancestry

Library PFCAPSRV.PBL
PFEAPSRV.PBL

419
u_calendar

Object relationships n_cst_dropdown

u_cb
u_dw
Usage Use this object to provide a dropdown calendar for date values in either of the
following:
U_dw-based DataWindow control
U_em-based EditMask control
Standalone calendar, for use with or without an EditMask
To use this service with DataWindow columns:
1 Place a u_dw-based DataWindow control on the window or user object.
2 Enable the dropdown calendar by calling the u_dw
of_SetDropDownCalendar function (this example is from a DataWindow
Constructor event):
this.of_SetDropDownCalendar(TRUE)
3 Register columns one by one or all at once by calling the of_Register
function. Of_Register includes an argument specifying the dropdown
style:
this.iuo_calendar.of_Register("hire_date", &
this.iuo_calendar.DDLB)
4 (Optional) Establish the font style and color for weekend days:
n_cst_color lnv_color

this.iuo_calendar.of_SetSaturdayBold(TRUE)
this.iuo_calendar.of_SetSaturdayColor &
(lnv_color.GREEN)
this.iuo_calendar.of_SetSundayBold(TRUE)
this.iuo_calendar.of_SetSundayColor &
(lnv_color.GREEN)
5 (Optional) Establish a list of holidays with their font style and color (this
example shows holidays for one year only):
Date ld_holidays[11]

ld_holidays[1] = 1997-01-01
ld_holidays[2] = 1997-02-17
ld_holidays[3] = 1997-04-21
ld_holidays[4] = 1997-05-26
ld_holidays[5] = 1997-07-04
ld_holidays[6] = 1997-09-01

420
 Chapter 7 Custom Visual User Objects

ld_holidays[7] = 1997-10-13
ld_holidays[8] = 1997-11-27
ld_holidays[9] = 1997-11-28
ld_holidays[10] = 1997-12-25
ld_holidays[11] = 1997-12-26
...
this.iuo_calendar.of_SetHoliday(ld_holidays)
this.iuo_calendar.of_SetHolidayBold(TRUE)
this.iuo_calendar.of_SetHolidayColor &
(lnv_color.GREEN)
6 (Optional) Establish a list of marked days with their font style and color:
Date ld_marked_days[12]

ld_marked_days[1] = 1996-06-13
ld_marked_days[2] = 1996-03-16
ld_marked_days[3] = 1996-09-23
ld_marked_days[4] = 1996-09-14
ld_marked_days[5] = 1997-06-13
ld_marked_days[6] = 1997-03-16
ld_marked_days[7] = 1997-09-23
ld_marked_days[8] = 1997-09-14
ld_marked_days[9] = 1998-06-13
ld_marked_days[10] = 1998-03-16
ld_marked_days[11] = 1998-09-23
ld_marked_days[12] = 1998-09-14
...
this.iuo_calendar.of_SetMarkedDay(ld_marked_days)
this.iuo_calendar.of_SetMarkedDayBold(TRUE)
this.iuo_calendar.of_SetMarkedDayColor &
(lnv_color.RED)
7 (Optional) Call additional functions as necessary to customize calendar
behavior:
this.iuo_calendar.of_SetCloseOnClick(FALSE)
this.iuo_calendar.of_SetCloseOnDClick(TRUE)
this.iuo_calendar.of_SetInitialValue(TRUE)
For information on using u_calendar with EditMask controls and as a
standalone calendar, see the PFC User’s Guide.
See also u_calculator
u_dw
u_em

421
u_calendar

Instance variables
U_calendar includes instance variables.
Instance variable Description Data type Access Usage
DDLB Constant set to 2 Integer Public Use with of_Register
DDLB_WITHARROW Constant set to 3 Integer Public Use with of_Register
ib_alwaysredraw Controls redraw Boolean Protected Internal
ib_closeonclick Controls close on Boolean Protected Set with
click of_SetCloseOnClick
ib_closeondclick Controls close on Boolean Protected Set with
double-click of_SetCloseOnDClick
ib_holidaybold Controls whether Boolean Protected Set with
holidays are bold of_SetHolidayBold
ib_initialvalue Controls whether Boolean Protected Set with of_SetInitialValue
blank fields are
initialized
ib_markeddaybold Controls whether Boolean Protected Set with
marked days are of_SetMarkedDayBold
bold
ib_saturdaybold Controls whether Boolean Protected Set with
Saturdays are bold of_SetSaturdayBold
ib_sundaybold Controls whether Boolean Protected Set with
Sundays are bold of_SetSundayBold
id_date Current date Date Protected Internal
id_holiday[ ] List of holidays Date Protected Set with of_SetHoliday
id_markedday[ ] List of marked Date Protected Set with
days of_SetMarkedDay
id_prevdate Previous date Date Protected Internal
id_resetdate Date to use if Date Protected Internal
invalid date is
entered
idrg_requestor Generic reference DragObject Protected Internal
idw_requestor Associated DataWindow Protected Internal
DataWindow
control
iem_requestor Associated EditMask Protected Internal
EditMask control
ii_boldfontweight Bold font weight Integer Protected Internal (default is 700)
ii_dwcolumnstyle[ ] Edit styles of Integer Protected Set with of_Register
registered
columns

422
 Chapter 7 Custom Visual User Objects

Instance variable Description Data type Access Usage

ii_normalfontweight Normal font Integer Protected Internal (default is 400)
weight
il_fontcolor Font color for Long Protected Internal
normal days
il_holidaycolor Font color for Long Protected Set with
holidays of_SetHolidayColor
il_markeddaycolor Font color for Long Protected Set with
marked days of_SetMarkedDayColor
il_saturdaycolor Font color for Long Protected Set with
Saturdays of_SetSaturdayColor
il_sundaycolor Font color for Long Protected Set with
Sundays of_SetSundayColor
inv_calendarattrib Calendar n_cst_calendarattrib Public Internal
attributes
inv_datetime Reference to n_cst_datetime Public Internal
date/time service
inv_dropdown Reference to n_cst_dropdown Public Internal
dropdown service
is_dateformat Date format String Protected Set with
of_SetDateFormat
is_dwcolumns[ ] Registered String Protected Set with of_Register
columns
is_dwcolumnsexp[ ] Original String Protected Set with of_Register
properties for
registered
columns
is_prevcell Previous cell String Protected Internal
NONE Constant set to 1 Integer Public Use with of_Register

Events
U_calendar includes precoded events:
ButtonClicked pfc_DropDown
Clicked pfc_NextDay
Constructor pfc_NextMonth
Destructor pfc_NextWeek
DoubleClicked pfc_PrevDay
GetFocus pfc_PrevMonth

423
u_calendar

Key pfc_PrevWeek
LoseFocus

ButtonClicked
Description Changes the month.
Applies to Dw_cal
Usage This event executes when the user clicks the next or previous month buttons.

Clicked
Description Changes the month or day.
Applies to Dw_cal
Usage This event executes when the user clicks a date.

Constructor
Description Initializes object settings.
Applies to Dw_cal and u_calendar
Usage This event executes when the object is created.

Destructor
Description Destroys the inv_dropdown instance variable.
Applies to U_calendar
Usage This event executes when the u_calendar instance is destroyed.

DoubleClicked
Description Hides the dropdown calendar if close on double-click has been set with the
of_SetCloseOnDClick function.
Applies to Dw_cal
Usage This event executes when the user double-clicks on the dw_cal DataWindow
control.

424
 Chapter 7 Custom Visual User Objects

GetFocus
Description Calls the of_RedirectFocus function.
Applies to Dw_cal
Usage This event executes when a control receives focus, typically by clicking.

Key
Description Provides keyboard support.
Applies to Dw_cal
Usage This event executes when the user presses one of the following keys:
ESC
TAB
ENTER
LEFT, RIGHT, UP, or DOWN ARROW
PAGE UP or PAGE DOWN

LoseFocus
Description Hides the calendar.
Applies to Dw_cal
Usage This event executes when the calendar loses focus.

pfc_DropDown
Description Calls the of_DropDown function.
Applies to U_calendar
Return value Integer. Returns 1 if the event succeeds, 0 if the DataWindow column has not
been registered, and -1 if an error occurs.
Usage This event, which calls the of_DropDown function, is called by the u_dw
pfc_DDCalendar event.

pfc_NextDay
Description Advances the current date by one day.
Applies to Dw_cal
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.

425
u_calendar

Usage This event is called by the Key event when the user presses the RIGHT ARROW
key.

pfc_NextMonth
Description Advances the current date by one month.
Applies to Dw_cal
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the Key event when the user presses the PAGE DOWN
key.

pfc_NextWeek
Description Advances the current date by one week.
Applies to Dw_cal
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the Key event when the user presses the DOWN ARROW
key.

pfc_PrevDay
Description Sets the current date back by one day.
Applies to Dw_cal
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the Key event when the user presses the LEFT ARROW
key.

pfc_PrevMonth
Description Sets the current date back by one month.
Applies to Dw_cal
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the Key event when the user presses the PAGE DOWN
key.

426
 Chapter 7 Custom Visual User Objects

pfc_PrevWeek
Description Sets the current date back by one week.
Applies to Dw_cal
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the Key event when the user presses the UP ARROW key.

Functions
U_calendar contains precoded object functions:
of_DrawMonth of_RedirectFocus
of_DropDown of_Register
of_GetHoliday of_Reset
of_GetHolidayColor of_SetAlwaysRedraw
of_GetInfo of_SetCloseOnClick
of_GetMarkedDay of_SetCloseOnDClick
of_GetMarkedDayColor of_SetDate
of_GetPropertyInfo of_SetDateFormat
of_GetRegisterable of_SetDropDown
of_GetRegistered of_SetFocusOnRequestor
of_GetRegisteredStyle of_SetHoliday
of_GetSaturdayColor of_SetHolidayBold
of_GetSundayColor of_SetHolidayColor
of_IsAlwaysRedraw of_SetInitialValue
of_IsCloseOnClick of_SetMarkedDay
of_IsCloseOnDClick of_SetMarkedDayBold
of_IsDateType of_SetMarkedDayColor
of_IsHolidayBold of_SetRequestor
of_IsInitialValue of_SetSaturdayBold
of_IsMarkedDayBold of_SetSaturdayColor
of_IsRegistered of_SetSundayBold
of_IsSaturdayBold of_SetSundayColor
of_IsSundayBold of_UnRegister

of_DrawMonth
Description Draws the specified month.

427
u_calendar

Access Protected
Syntax dwcontrol.instancename.of_DrawMonth ( date )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
date Date specifying the month to draw

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example calls the of_DrawMonth function:
...
IF Year(ad_date) <> Year(id_prevdate) OR &
Month(ad_date) <> Month(id_prevdate) THEN
of_DrawMonth(ad_date)
END IF
...

of_DropDown
Description Displays the dropdown calendar in the appropriate location.
Access Public
Syntax dwcontrol.instancename.of_DropDown ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Integer. Returns 1 if the function succeeds, 0 if the current DataWindow
column has not been registered, and -1 if an error occurs.
Usage The u_dw and u_em pfc_DDCalendar event calls this function.
Examples This example is from the u_em pfc_DDCalendar event:
IF IsValid(iuo_calendar) THEN
Return iuo_calendar.of_DropDown()
END IF

428
 Chapter 7 Custom Visual User Objects

of_GetHoliday
Description Retrieves an array containing all specified holidays.
Access Public
Syntax dwcontrol.instancename.of_GetHoliday ( holidays )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
holidays Unbounded Date array into which the function places all specified
holidays (passed by reference)

Return value Integer. Returns the number of entries in the holidays array.
Examples This example calls the of_GetHoliday function:
String ls_display
Date ldt_holidays[ ]
Integer li_return, li_count

li_return = &
dw_caltest.iuo_calendar.of_GetHoliday &
(ldt_holidays)
FOR li_count = 1 to li_return
ls_display += String(ldt_holidays[li_count])
ls_display += "~r~n"
NEXT
MessageBox("Holidays", ls_display)

of_GetHolidayColor
Description Retrieves the display color for holidays.
Access Public
Syntax dwcontrol.instancename.of_GetHolidayColor ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Long. Returns the color for holidays.

429
u_calendar

Examples This example calls the of_GetHolidayColor function:

MessageBox("Holidays", "Holiday color is " + String &
(dw_caltest.iuo_calendar.of_GetHolidayColor()))

of_GetInfo
Description Retrieves object information.
Access Public
Syntax dwcontrol.instancename.of_GetInfo ( infoobject )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
infoobject N_cst_infoattrib instance into which the function places
information (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The DataWindow Properties window calls this function to access service
information.
Examples This example calls the of_GetInfo function:
n_cst_infoattrib lnv_info

dw_1.iuo_calendar.of_GetInfo(lnv_info)
MessageBox("Info", &
"Description: " + lnv_info.is_description &
+ ". Name: " + lnv_info.is_name)

of_GetMarkedDay
Description Retrieves an array containing all marked days.
Access Public
Syntax dwcontrol.instancename.of_GetMarkedDay ( markeddays )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

430
 Chapter 7 Custom Visual User Objects

Argument Description
markeddays Unbounded Date array into which the function places all specified
marked days (passed by reference)

Return value Integer. Returns the number of entries in the markeddays array.
Examples This example calls the of_GetMarkedDay function:
String ls_display
Date ldt_marked_days[ ]
Integer li_return, li_count

li_return = &
dw_caltest.iuo_calendar.of_GetMarkedDay &
(ldt_marked_days)
FOR li_count = 1 to li_return
ls_display += String(ldt_marked_days[li_count])
ls_display += "~r~n"
NEXT
MessageBox("Marked Days", ls_display)

of_GetMarkedDayColor
Description Retrieves the display color for marked days.
Access Public
Syntax dwcontrol.instancename.of_GetMarkedDayColor ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Long. Returns the color for marked days.

Examples This example calls the of_GetMarkedDayColor function:
MessageBox("Marked Days", &
"Marked day color is " + String &
(dw_1.iuo_calendar.of_GetMarkedDayColor()))

of_GetPropertyInfo
Description Retrieves information about the service’s properties.
Access Public

431
u_calendar

Syntax dwcontrol.instancename.of_GetPropertyInfo ( propertyobject )

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
propertyobject N_cst_propertyattrib instance into which the function places
property information (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The DataWindow Properties window calls this function to access service
information.
Examples This example calls the of_GetPropertyInfo function:
n_cst_propertyattrib lnv_prop

dw_1.iuo_calendar.of_GetPropertyInfo(lnv_prop)
MessageBox("Info", &
"Description: " + lnv_prop.is_description &
+ ". Name: " + lnv_prop.is_name &
+ ". Property tab text: " + &
lnv_prop.is_propertytabtext)

of_GetRegisterable
Description Retrieves an array of registerable DataWindow columns. Registerable
DataWindow columns have the date data type and use the DropDownListBox,
Edit, or EditMask edit style.
Access Public
Syntax dwcontrol.instancename.of_GetRegisterable ( columns )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calendar (the u_dw default for this value is
iuo_calendar)
columns Unbounded string array into which the function places the names
of columns that have been registered with this instance of the
dropdown calendar (passed by reference)

Return value Integer. Returns the number of entries in the columns array if the function
succeeds and -1 if an error occurs.

432
 Chapter 7 Custom Visual User Objects

Usage Call this function to determine which DataWindow columns could be

registered with this instance of u_calendar.
Examples This example calls the of_GetRegisterable function:
...
li_rc = &
idw_requestor.iuo_calendar. of_GetRegisterable &
(ls_allcols)
...

of_GetRegistered
Description Retrieves an array of registered DataWindow columns.
Access Public
Syntax dwcontrol.instancename.of_GetRegistered ( columns )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calendar (the u_dw default for this value is
iuo_calendar)
columns Unbounded string array into which the function places the names of
columns that have been registered with this instance of the
dropdown calendar (passed by reference)

Return value Integer. Returns the number of entries in the columns array if the function
succeeds and -1 if an error occurs.
Examples This example calls the of_GetRegistered function:
String ls_columns[], ls_display
Integer li_return, li_count

li_return = &
dw_1.iuo_calendar.of_GetRegistered(ls_columns)
FOR li_count = 1 to li_return
ls_display += ls_columns[li_count] + "~r~n"
NEXT
MessageBox("Columns", ls_display)

of_GetRegisteredStyle
Description Retrieves the display style for a registered column.
Access Public

433
u_calendar

Syntax dwcontrol.instancename.of_GetRegisteredStyle ( column )

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calendar (the u_dw default for this value is
iuo_calendar)
column String containing the DataWindow column for which the function
returns the display style

Return value Integer. Returns 1 if the function succeeds, 0 if the column is not registered, and
-1 if an error occurs.
Examples This example calls the of_GetRegisteredStyle function:
Integer li_return

li_return = &
dw_1.iuo_calendar.of_GetRegisteredStyle &
("start_date")
MessageBox("Display Style", &
"Display style is " + String(li_return))

of_GetSaturdayColor
Description Retrieves the display color for Saturdays.
Access Public
Syntax dwcontrol.instancename.of_GetSaturdayColor ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not required
when using u_calendar with an EditMask control)
instancena Instance name of u_calendar (the u_dw and u_em default for this value
me is iuo_calendar)

Return value Long. Returns the color for Saturdays.

Examples This example calls the of_GetSaturdayColor function:
MessageBox("Saturdays", "Saturday color is " + &
String &
(dw_caltest.iuo_calendar.of_GetSaturdayColor()))

of_GetSundayColor
Description Retrieves the display color for Sundays.

434
 Chapter 7 Custom Visual User Objects

Access Public
Syntax dwcontrol.instancename.of_GetSundayColor ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Long. Returns the color for Sundays.

Examples This example calls the of_GetSundayColor function:
MessageBox("Sundays", "Sunday color is " + &
String &
(dw_caltest.iuo_calendar.of_GetSundayColor()))

of_IsAlwaysRedraw
Description Reports whether the u_calendar instance forces calendar redraw when display
properties change.
Access Public
Syntax dwcontrol.instancename.of_IsAlwaysRedraw ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Boolean. Returns TRUE if the u_calendar instance forces redraw and FALSE
if it does not.
Examples This example calls the of_IsAlwaysRedraw function:
Boolean lb_redraw
n_cst_conversion lnv_conversion

lb_redraw = &
dw_1.iuo_calendar.of_IsAlwaysRedraw()
MessageBox("Calendar", "Redraw is " &
+ lnv_conversion.of_String(lb_redraw))

435
u_calendar

of_IsCloseOnClick
Description Reports whether the u_calendar instance closes when the user clicks a date.
Access Public
Syntax dwcontrol.instancename.of_IsCloseOnClick ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Boolean. Returns TRUE if the u_calendar instance closes when the user clicks
a date and FALSE if it does not.
Examples This example calls the of_IsCloseOnClick function:
Boolean lb_close
n_cst_conversion lnv_conversion

lb_close = &
dw_1.iuo_calendar.of_IsCloseOnClick()
MessageBox("Calendar", "Close on click is " &
+ lnv_conversion.of_String(lb_close))

of_IsCloseOnDClick
Description Reports whether the u_calendar instance closes when the user double-clicks a
date.
Access Public
Syntax dwcontrol.instancename.of_IsCloseOnDClick ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Boolean. Returns TRUE if the u_calendar instance closes when the user
double-clicks a date and FALSE if it does not.
Examples This example calls the of_IsCloseOnDClick function:
Boolean lb_close
n_cst_conversion lnv_conversion

436
 Chapter 7 Custom Visual User Objects

lb_close = &
dw_1.iuo_calendar.of_IsCloseOnDClick()
MessageBox("Calendar", &
"Close on double-click is " &
+ lnv_conversion.of_String(lb_close))

of_IsDateType
Description Reports whether a specified DataWindow column uses the date data type.
Access Protected
Syntax dwcontrol.instancename.of_IsDateType ( datatype )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
datatype String specifying the data type

Return value Boolean. Returns TRUE if datatype is date and FALSE if it is not.
Usage Internal.
Examples This example is from the of_DropDown function:
...
IF NOT of_IsDateType(idw_requestor.Describe &
(ls_colname+".coltype")) THEN
Return -1
END IF
...

of_IsHolidayBold
Description Reports whether holidays are bold.
Access Public
Syntax dwcontrol.instancename.of_IsHolidayBold ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

437
u_calendar

Return value Boolean. Returns TRUE if holidays are bold and FALSE if they are not.
Examples This example calls the of_IsHolidayBold function:
IF dw_caltest.iuo_calendar.of_IsHolidayBold() THEN
MessageBox("Holidays", "Holidays are bold")
ELSE
MessageBox("Holidays", "Holidays are not bold")
END IF

of_IsInitialValue
Description Reports whether the u_calendar instance initializes blank fields with the
current date when the calendar displays.
Access Public
Syntax dwcontrol.instancename.of_IsInitialValue ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Boolean. Returns TRUE if the calendar initializes blank fields with the current
date and FALSE if it does not.
Examples This example calls the of_IsInitialValue function:
Boolean lb_today
n_cst_conversion lnv_conversion

lb_today = &
dw_caltest.iuo_calendar.of_IsInitialValue()
MessageBox("Calendar", &
"Use today’s date value is " &
+ lnv_conversion.of_String(lb_today))

of_IsMarkedDayBold
Description Reports whether marked days are bold.
Access Public
Syntax dwcontrol.instancename.of_IsMarkedDayBold ( )

438
 Chapter 7 Custom Visual User Objects

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Boolean. Returns TRUE if marked days are bold and FALSE if they are not.
Examples This example calls the of_IsMarkedDayBold function:
IF dw_1.iuo_calendar.of_IsMarkedDayBold() THEN
MessageBox("Marked Days", "Marked days are bold")
ELSE
MessageBox("Marked Days", &
"Marked days are not bold")
END IF

of_IsRegistered
Description Reports whether a specified DataWindow column has been registered with this
instance of u_calendar.
Access Public
Syntax dwcontrol.instancename.of_IsRegistered ( column )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calendar (the u_dw default for this value is
iuo_calendar)
column String specifying the column to search for

Return value Boolean. Returns TRUE if column has been registered and FALSE if it has not.
Examples This example calls the of_IsRegistered function:
...
IF NOT this.iuo_calendar.of_IsRegistered &
("birth_date") THEN
this.iuo_calendar.of_Register("birth_date")
END IF
...

of_IsSaturdayBold
Description Reports whether Saturdays are bold.

439
u_calendar

Access Public
Syntax dwcontrol.instancename.of_IsSaturdayBold ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Boolean. Returns TRUE if Saturdays are bold and FALSE if they are not.
Examples This example calls the of_IsSaturdayBold function:
IF dw_caltest.iuo_calendar. of_IsSaturdayBold () THEN
MessageBox("Saturdays", "Saturdays are bold")
ELSE
MessageBox("Saturdays", "Saturdays are not bold")
END IF

of_IsSundayBold
Description Reports whether Sundays are bold.
Access Public
Syntax dwcontrol.instancename.of_IsSundayBold ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Boolean. Returns TRUE if Sundays are bold and FALSE if they are not.
Examples This example calls the of_IsSundayBold function:
IF dw_caltest.iuo_calendar. of_IsSundayBold () THEN
MessageBox("Sundays", "Sundays are bold")
ELSE
MessageBox("Sundays", "Sundays are not bold")
END IF

of_RedirectFocus
Description Prevents the u_calendar instance from getting focus while it is hidden.
Access Protected

440
 Chapter 7 Custom Visual User Objects

Syntax dwcontrol.instancename.of_RedirectFocus ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the dw_cal GetFocus event:
Post of_RedirectFocus()

of_Register
Registers columns that use the dropdown calendar. There are two syntaxes:
To register Use
One or all eligible columns, optionally specifying a display style Syntax 1
All eligible columns using a specified display style Syntax 2

Syntax 1 Register columns with an optional display style

Description Registers one or all eligible columns in a DataWindow. Eligible columns use
the date data type and have the Edit, EditMask, or DropDownListBox edit
style.
Access Public
Syntax dwcontrol.instancename.of_Register ( { column {, style } } )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calendar (the u_dw default for this value is
iuo_calendar)
column (Optional) String specifying the column to be registered. This
column must have a date data type. If you omit this argument, the
function registers all columns that use the date data type

441
u_calendar

Argument Description
style (Optional) Integer or u_calendar constant specifying the display
style of registered DataWindow columns:
• 1 or NONE (default) For columns that use the
DropDownListBox edit style, the calendar displays
automatically when the column gets focus. For columns that use
the Edit and EditMask edit styles, the calendar does not display
automatically; instead, you display the calendar by coding a call
to the u_dw pfc_DDCalendar event
• 2 or DDLB The function converts registered columns to the
DropDownListBox edit style. Users display the calendar by
clicking the down arrow, which disappears when the calendar
displays
• 3 or DDLB_WITHARROW The function converts registered
columns to the DropDownListBox edit style. Users display the
calendar by clicking the down arrow, which remains when the
calendar displays

Return value Integer. Returns the number of columns registered if the function succeeds, 0
if the column was already registered, and -1 if an error occurs. The number of
columns registered includes hidden columns.
Usage Call this function to register one or all date columns in a DataWindow.
To register all eligible columns in a DataWindow using a specified display
style, use Syntax 2.
Examples This example calls the of_Register function:
this.of_SetTransObject(SQLCA)
this.of_SetDropDownCalendar(TRUE)
this.iuo_calendar.of_Register("start_date", &
this.iuo_calendar.DDLB)
this.iuo_calendar.of_Register("termination_date", &
this.iuo_calendar.NONE)
this.iuo_calendar.of_Register("birth_date", &
this.iuo_calendar.DDLB)
this.of_Retrieve()

Syntax 2 Register columns with a display style

Description Registers all eligible columns in a DataWindow using the specified display
style. Eligible columns use the date data type and have the Edit, EditMask, or
DropDownListBox edit style.
Access Public

442
 Chapter 7 Custom Visual User Objects

Syntax dwcontrol.instancename.of_Register (style )

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control
instancename Instance name of u_calendar. The u_dw and u_em default for this is
iuo_calendar
style Integer or u_calendar constant specifying the display style of
registered DataWindow columns:
• 1 or NONE For columns that use the DropDownListBox edit
style, the calendar displays automatically when the column gets
focus. For columns that use the Edit and EditMask edit styles, the
calendar does not display automatically; instead, you display the
calendar by coding a call to the u_dw pfc_DDCalendar event
• 2 or DDLB The function converts registered columns to the
DropDownListBox edit style. Users display the calendar by
clicking the down arrow, which disappears when the calendar
displays
• 3 or DDLB_WITHARROW The function converts registered
columns to the DropDownListBox edit style. Users display the
calendar by clicking the down arrow, which remains when the
calendar displays

Return value Integer. Returns the number of columns registered if the function succeeds and
-1 if an error occurs. The number of columns registered includes hidden
columns.
Usage Call this function to register all Date columns in a DataWindow, using a
specified display style.
To register one or all eligible columns in a DataWindow, optionally specifying
a display style, use Syntax 1.
Examples This example calls the of_Register function:
this.of_SetTransObject(SQLCA)
this.of_SetDropDownCalendar(TRUE)
this.iuo_calendar.of_Register &
(this.iuo_calendar.NONE)
this.of_Retrieve()

of_Reset
Description Resets the u_calendar date to that displayed in the DataWindow column or
EditMask control.
Access Protected

443
u_calendar

Syntax dwcontrol.instancename.of_Reset ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_DropDown function:
...
li_rc = inv_dropdown.of_Position &
(idrg_requestor, FALSE)
IF li_rc < 0 THEN Return -1
of_Reset ()
This.Visible = TRUE
Return 1
...

of_SetAlwaysRedraw
Description Specifies whether the u_calendar instance forces calendar redraw when display
properties change.
Access Public
Syntax dwcontrol.instancename.of_SetAlwaysRedraw ( boolean )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
boolean Boolean indicating whether the u_calendar instance forces a
redraw when display properties change (TRUE) or not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage You should enable automatic redraw if your application programmatically
changes a calendar’s holidays, special days, or other display properties.
Examples This example calls the of_SetAlwaysRedraw function:
dw_1.iuo_calendar.of_SetAlwaysRedraw(TRUE)

444
 Chapter 7 Custom Visual User Objects

of_SetCloseOnClick
Description Specifies whether to hide the u_calendar instance when the user clicks a date.
Access Public
Syntax dwcontrol.instancename.of_SetCloseOnClick ( boolean )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
boolean Boolean specifying whether to hide the dropdown calendar when
the user clicks a date (TRUE) or leave it displayed (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetCloseOnClick function:
this.of_SetTransObject(SQLCA)
this.of_SetDropDownCalendar(TRUE)
this.iuo_calendar.of_Register("start_date", &
this.iuo_calendar.DDLB)
this.iuo_calendar.of_Register("termination_date")
this.iuo_calendar.of_Register("birth_date", &
this.iuo_calendar.DDLB)
this.iuo_calendar.of_SetCloseOnClick(FALSE)
this.iuo_calendar.of_SetInitialValue(TRUE)

of_SetCloseOnDClick
Description Specifies whether to hide the u_calendar instance when the user double-clicks
a date.
Access Public
Syntax dwcontrol.instancename.of_SetCloseOnDClick ( boolean )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
boolean Boolean specifying whether to hide the dropdown calendar when
the user double-clicks a date (TRUE) or leave it displayed (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.

445
u_calendar

Examples This example calls the of_SetCloseOnDClick function:

this.of_SetTransObject(SQLCA)
this.of_SetDropDownCalendar(TRUE)
this.iuo_calendar.of_Register("start_date")
this.iuo_calendar.of_Register("termination_date")
this.iuo_calendar.of_Register("birth_date")
this.iuo_calendar.of_SetCloseOnDClick(TRUE)

of_SetDate
Description Sets the current date, optionally updating the date in the associated
DataWindow column or EditMask control.
Access Protected
Syntax dwcontrol.instancename.of_SetDate ( date, sendtorequestor )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
date Date variable containing the new date
sendtorequestor Boolean indicating whether to copy date to the requestor object
(TRUE) or not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_Reset function:
...
id_resetdate = date(ls_date)
IF of_IsValid(id_resetdate) THEN
of_SetDate(id_resetdate, FALSE)
ELSE
of_SetDate(Today(), ib_InitialValue)
END IF
Return 1

of_SetDateFormat
Description Sets the format for dates converted to strings.
Access Public

446
 Chapter 7 Custom Visual User Objects

Syntax dwcontrol.instancename.of_SetDateFormat ( format )

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
format String specifying the format for dates converted to strings. Sample
date formats include mm/dd/yy; m-d-yy; and mmm dd, yyyy

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage When using a calendar with an EditMask control, this format must match the
date mask.
When you use this function for a DataWindow column, it overrides the
DataWindow edit mask, if one was specified. Also, when applied to a
DataWindow column, the format argument must be compatible with the client
system default date format.
Examples This example calls the of_SetDateFormat function:
...
this.iuo_calendar.of_SetInitialValue(TRUE)
this.iuo_calendar.of_SetDateFormat("dd/mm/yy")

of_SetDropDown
Description Enables or disables the dropdown service (n_cst_dropdown).
Access Public
Syntax dwcontrol.instancename.of_SetDropDown ( boolean )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
boolean Boolean specifying whether to enable (TRUE) or disable (TRUE)
the dropdown service

Return value Integer. Returns 1 if the function succeeds, 0 if the dropdown service already
exists, and -1 if an error occurs.

447
u_calendar

Examples This example is from the u_calendar Constructor event:

...
this.Visible = FALSE
of_SetDropDown(TRUE)
...

of_SetFocusOnRequestor
Description Returns focus to the associated DataWindow column or EditMask control.
Access Protected
Syntax dwcontrol.instancename.of_SetFocusOnRequestor ( )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the dw_cal DoubleClicked event:
...
IF IsValid(inv_dropdown) THEN
IF ib_closeondclick THEN
of_SetFocusOnRequestor()
END IF
END IF

of_SetHoliday
Description Specifies the holidays displayed on the calendar.
Access Public
Syntax dwcontrol.instancename.of_SetHoliday ( holidays )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
holidays Date array containing holidays

448
 Chapter 7 Custom Visual User Objects

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetHoliday function:
Date ld_holidays[11]

ld_holidays[1] = 1997-01-01
ld_holidays[2] = 1997-02-17
ld_holidays[3] = 1997-04-21
ld_holidays[4] = 1997-05-26
ld_holidays[5] = 1997-07-04
ld_holidays[6] = 1997-09-01
ld_holidays[7] = 1997-10-13
ld_holidays[8] = 1997-11-27
ld_holidays[9] = 1997-11-28
ld_holidays[10] = 1997-12-25
ld_holidays[11] = 1997-12-26
this.iuo_calendar.of_SetHoliday(ld_holidays)

of_SetHolidayBold
Description Sets the Bold property for holidays.
Access Public
Syntax dwcontrol.instancename.of_SetHolidayBold ( boolean )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
boolean Boolean indicating whether holidays are bold (TRUE) or not
(FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetHolidayBold function:
...
this.iuo_calendar.of_SetHoliday(ld_holidays)
this.iuo_calendar.of_SetHolidayBold (TRUE)
this.iuo_calendar.of_SetHolidayColor(RGB(0,255,0))

of_SetHolidayColor
Description Sets the display color for holidays.

449
u_calendar

Access Public
Syntax dwcontrol.instancename.of_SetHolidayColor ( color )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
color Long specifying the color for holidays

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetHolidayColor function:
...
this.iuo_calendar.of_SetHoliday(ld_holidays)
this.iuo_calendar.of_SetHolidayBold(TRUE)
this.iuo_calendar.of_SetHolidayColor(RGB(0,255,0))

of_SetInitialValue
Description Specifies whether the u_calendar instance initializes blank fields with the
current date when the calendar displays.
Access Public
Syntax dwcontrol.instancename.of_SetInitialValue ( boolean )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
boolean Boolean indicating whether the calendar initializes the blank fields
with the current date when the calendar displays (TRUE) or not
(FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetInitialValue function:
...
this.iuo_calendar.of_SetInitialValue(TRUE)
...

450
 Chapter 7 Custom Visual User Objects

of_SetMarkedDay
Description Specifies a set of marked days. Marked days are not holidays but still require
special display on the calendar.
Access Public
Syntax dwcontrol.instancename.of_SetMarkedDay ( markeddays )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
markeddays Date array containing marked days

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetMarkedDay function:
Date ld_marked_days[12]

ld_marked_days[1] = 1996-06-13
ld_marked_days[2] = 1996-03-16
ld_marked_days[3] = 1996-09-23
ld_marked_days[4] = 1996-09-14
ld_marked_days[5] = 1997-06-13
ld_marked_days[6] = 1997-03-16
ld_marked_days[7] = 1997-09-23
ld_marked_days[8] = 1997-09-14
ld_marked_days[9] = 1998-06-13
ld_marked_days[10] = 1998-03-16
ld_marked_days[11] = 1998-09-23
ld_marked_days[12] = 1998-09-14

this.iuo_calendar.of_SetMarkedDay(ld_marked_days)

of_SetMarkedDayBold
Description Sets the Bold property for marked days.
Access Public
Syntax dwcontrol.instancename.of_SetMarkedDayBold ( boolean )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)

451
u_calendar

Argument Description
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
boolean Boolean indicating whether marked days are bold (TRUE) or not
(FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetMarkedDayBold function:
...
this.iuo_calendar.of_SetMarkedDayBold(TRUE)
this.iuo_calendar.of_SetMarkedDayColor &
(RGB(255, 0, 0))

of_SetMarkedDayColor
Description Sets the display color for marked days.
Access Public
Syntax dwcontrol.instancename.of_SetMarkedDayColor ( color )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
color Long specifying the color for marked days

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetMarkedDayColor function:
...
this.iuo_calendar.of_SetMarkedDayBold(TRUE)
this.iuo_calendar.of_SetMarkedDayColor &
(RGB(255, 0, 0))

of_SetRequestor
Description Associates an instance of u_calendar with a DataWindow or EditMask control.
Access Public
Syntax dwcontrol.instancename.of_SetRequestor ( requestor )

452
 Chapter 7 Custom Visual User Objects

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calculator with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
requestor DragObject referencing the DataWindow or EditMask control to
associate with this instance of u_calendar

Return value Integer. Returns values as follows:

• 1 Success
• -1 An error occurred
• -2 The u_calendar instance has not enabled n_cst_dropdown
• -3 The EditMask mask type is not date
Usage EditMask controls must have a mask type of date.
If you are not using the u_calendar object as a dropdown object (that is,
displaying it permanently on a window, user object, or tab), call this function
to associate the u_calendar instance with the EditMask control that displays the
results.
Examples This example is from the u_em of_SetDropDownCalendar function:
...
IF ab_switch THEN
IF NOT IsValid (iuo_calendar) THEN
lw_parent.OpenUserObject(iuo_calendar)
iuo_calendar.of_SetRequestor(this)
Return 1
END IF
ELSE
IF IsValid (iuo_calendar) THEN
lw_parent.CloseUserObject(iuo_calendar)
Return 1
END IF
END IF
...

of_SetSaturdayBold
Description Sets the Bold property for Saturdays.
Access Public

453
u_calendar

Syntax dwcontrol.instancename.of_SetSaturdayBold ( boolean )

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
boolean Boolean indicating whether Saturdays are bold (TRUE) or not
(FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetSaturdayBold function:
this.iuo_calendar.of_SetSaturdayBold TRUE)
this.iuo_calendar.of_SetSaturdayColor &
(RGB(0, 255, 0))

of_SetSaturdayColor
Description Sets the display color for Saturdays.
Access Public
Syntax dwcontrol.instancename.of_SetSaturdayColor ( color )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
color Long specifying the color for Saturdays

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetSaturdayColor function:
this.iuo_calendar.of_SetSaturdayBold(TRUE)
this.iuo_calendar.of_SetSaturdayColor &
(RGB(0, 255, 0))

of_SetSundayBold
Description Sets the Bold property for Sundays.
Access Public
Syntax dwcontrol.instancename.of_SetSundayBold ( boolean )

454
 Chapter 7 Custom Visual User Objects

Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
boolean Boolean indicating whether Sundays are bold (TRUE) or not
(FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetSundayBold function:
this.iuo_calendar.of_SetSundayBold(TRUE)
this.iuo_calendar.of_SetSundayColor(RGB(0, 255, 0))

of_SetSundayColor
Description Sets the display color for Sundays.
Access Public
Syntax dwcontrol.instancename.of_SetSundayColor ( color )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control (not
required when using u_calendar with an EditMask control)
instancename Instance name of u_calendar (the u_dw and u_em default for this
value is iuo_calendar)
color Long specifying the color for Sundays

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetSundayColor function:
this.iuo_calendar.of_SetSundayBold(TRUE)
this.iuo_calendar.of_SetSundayColor(RGB(0, 255, 0))

of_UnRegister
Description Removes one or all columns from the list of registered columns.
Access Public
Syntax dwcontrol.instancename.of_Register ( { column } )
Argument Description
dwcontrol Instance name of the u_dw-based DataWindow control

455
u_calendar

Argument Description
instancename Instance name of u_calendar (the u_dw default for this is
iuo_calendar)
column (Optional) String specifying the column to be unregistered. If you
omit this argument, the function unregisters all columns

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_UnRegister function:
...
dw_emp.iuo_calendar.of_UnRegister("start_date")
...

456
 Chapter 7 Custom Visual User Objects

u_progressbar
Description Progress bar control. Use u_progressbar to provide users with a visual
representation of percentage complete for long-running operations.
U_progressbar can be vertical or horizontal and can display either percent
complete or programmatically specified text.
Ancestry

Library PFCAPSRV.PBL
PFEAPSRV.PBL
Usage Use this control to display a progress bar for long-running operations.
To use u_progressbar:
1 Place an instance of the u_progressbar object on a window or user object.
2 Size the object to create an appropriately sized vertical or horizontal
progress bar.
3 Define defaults for the progress bar instance. This example defines
defaults in the Constructor event:
of_SetFillStyle(LEFTRIGHT)
of_SetDisplayStyle(PCTCOMPLETE)

457
u_progressbar

of_SetFillColor(RGB(128, 128, 128))

of_SetFontSize(10)
of_SetAutoReset(FALSE)
4 In the process to be tracked, set the initial progress bar position, set the
maximum, and call the of_Increment function at regular intervals to
update the progress bar:
Integer li_count

uo_progress.of_SetMaximum(100)
uo_progress.of_SetPosition(0)
FOR li_count = 1 TO &
uo_progress.of_GetMaximum() STEP 1
uo_progress.of_Increment(1)
// Additional code here to perform your process
NEXT
See also n_cst_winsrv_statusbar
u_hpb
u_vpb

Instance variables
U_progressbar includes instance variables:
Instance variable Description Data type Access Usage
BAR Constant set to 0 Integer Public Use with
of_SetDisplayStyle
BOTTOMTOP Constant set to 3 Integer Public Use with
of_SetFillStyle
ib_autoreset Controls autoreset Boolean Protected Set with
of_SetAutoReset.
Default is TRUE
ii_displaystyle Controls test displayed on Integer Protected Set with
progress bar of_DisplayStyle.
Default is BAR
ii_fillstyle Controls the direction in Integer Protected Set with
which the progress bar of_SetFillStyle. Default
fills is LEFTRIGHT
ii_maximum Value at which the Integer Protected Set with
incrementation process of_SetMaximum.
ends Default is 100

458
 Chapter 7 Custom Visual User Objects

Instance variable Description Data type Access Usage

ii_minimum Value at which the Integer Protected Set with
incrementation process of_SetMinimum.
starts Default is 0
ii_msgtextcount Number of items in Integer Protected Internal
os_msgtext[] array
ii_percentcomplete Current percent complete Integer Protected Access with
of_GetPctComplete
ii_position Current increment Integer Protected Set with of_SetPosition.
position Updated internally
ii_step Default increment value Integer Protected Set with of_SetStep.
Default is 10
il_backcolor Background color Long Protected Set with
of_SetBackColor.
Default is 78682240
il_fillcolor Fill color Long Protected Set with
of_SetFillColor.
Default is 16668075
il_textcolor Text color Long Protected Set with
of_SetTextColor.
Default is 0
is_msgtext[ ] Array of text to display on String Protected Set with
progress bar of_SetMessageText
LEFTRIGHT Constant set to 0 Integer Public Use with
of_SetFillStyle
MSGTEXT Constant set to 3 Integer Public Use with
of_SetDisplayStyle
PCTCOMPLETE Constant set to 1 Integer Public Use with
of_SetDisplayStyle
POSITION Constant set to 2 Integer Public Use with
of_SetDisplayStyle
RIGHTLEFT Constant set to 1 Integer Public Use with
of_SetFillStyle
TOPDOWN Constant set to 2 Integer Public Use with
of_SetFillStyle

459
u_progressbar

Events
U_progressbar includes precoded events:
Constructor
RButtonDown

Constructor
Description Initializes progress bar settings.
Applies to U_progressbar
Usage This event executes when the progress bar object is created.

RButtonDown
Description Calls the parent’s RButtonDown event.
Applies to Dw_progress
Usage This event executes when the user right-clicks over the progress bar.

Functions
U_progressbar contains precoded object functions:
of_GetBackColor of_SetFillColor
of_GetCurrentText of_SetFillStyle
of_GetDisplayStyle of_SetFont
of_GetFillColor of_SetFontBold
of_GetFillStyle of_SetFontCharSet
of_GetInfo of_SetFontFace
of_GetMaximum of_SetFontFamily
of_GetMessageText of_SetFontItalic
of_GetMinimum of_SetFontPitch
of_GetPctComplete of_SetFontSize
of_GetPosition of_SetFontUnderline
of_GetStep of_SetMaximum
of_GetTextColor of_SetMessageText
of_Increment of_SetMinimum
of_IsAutoReset of_SetPosition

460
 Chapter 7 Custom Visual User Objects

of_Reset of_SetStep
of_SetAutoReset of_SetTextColor
of_SetBackColor of_UpdateVisuals
of_SetDisplayStyle

of_GetBackColor
Description Retrieves the progress bar background color.
Access Public
Syntax instancename.of_GetBackColor ( )
Argument Description
instancename Instance name of u_progressbar

Return value Long. Returns the background color.

Examples This example calls the of_GetBackColor function:
Long ll_backcolor

ll_backcolor = uo_progress.of_GetBackColor()
MessageBox("Progress Bar", &
"Background color property is " &
+ String(ll_backcolor))

of_GetCurrentText
Description Retrieves the text currently displayed on the progress bar. This function
retrieves any text displayed on the progress bar, not just the display text
specified by the of_SetMessageText function.
Access Public
Syntax instancename.of_GetCurrentText ( )
Argument Description
instancename Instance name of u_progressbar

Return value String. Returns the current progress bar text.

Examples This example calls the of_GetCurrentText function:
String ls_text

ls_text = uo_progress.of_GetCurrentText()

461
u_progressbar

MessageBox("Progress Bar", &

"Current text is " + ls_text)

of_GetDisplayStyle
Description Retrieves the progress bar display style. The display style controls the
information that displays within the bar while tracking progress.
Access Public
Syntax instancename.of_GetDisplayStyle ( )
Argument Description
instancename Instance name of u_progressbar

Return value Integer. Returns values as follows:

• 0 (BAR) Progress bar only
• 1 (PCTCOMPLETE) Progress bar and percent complete, including the
percent sign
• 2 (POSITION) Current increment value
• 3 (MSGTEXT) Progress bar and text as specified by the
of_SetMessageText function
Examples This example calls the of_GetDisplayStyle function:
Integer li_displaystyle

li_displaystyle = uo_progress.of_GetDisplayStyle()
MessageBox("Progress Bar", &
"DisplayStyle property is " &
+ String(li_displaystyle))

of_GetFillColor
Description Retrieves the progress bar fill color.
Access Public
Syntax instancename.of_GetFillColor ( )
Argument Description
instancename Instance name of u_progressbar

Return value Long. Returns the fill color.

462
 Chapter 7 Custom Visual User Objects

Examples This example calls the of_GetFillColor function:

Long ll_fillcolor

ll_fillcolor = uo_progress.of_GetFillColor()
MessageBox("Progress Bar", &
"Fill color property is " &
+ String(ll_fillcolor))

of_GetFillStyle
Description Retrieves the progress bar fill style.
Access Public
Syntax instancename.of_GetFillStyle ( )
Argument Description
instancename Instance name of u_progressbar

Return value Integer. Returns values as follows:

• 0 (LEFTRIGHT) The progress bar fills from left to right
• 1 (RIGHTLEFT) The progress bar fills from right to left
• 2 (TOPDOWN) The progress bar fills from top to bottom
• 3 (BOTTOMUP) The progress bar fills from bottom to top
Examples This example calls the of_GetFillStyle function:
Integer li_fillstyle

li_fillstyle = uo_progress.of_GetFillStyle()
MessageBox("Progress Bar", &
"Fill style is " + String(li_fillstyle))

of_GetInfo
Description Retrieves object information.
Access Public
Syntax dwcontrol.instancename.of_GetInfo ( infoobject )
Argument Description
instancename Instance name of u_progressbar
infoobject N_cst_infoattrib instance into which the function places
information (passed by reference)

463
u_progressbar

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The DataWindow Properties window calls this function to access service
information:
Examples This example calls the of_GetInfo function:
n_cst_infoattrib lnv_info

uo_progress.of_GetInfo(lnv_info)
MessageBox("Info", &
"Description: " + lnv_info.is_description &
+ ". Name: " + lnv_info.is_name)

of_GetMaximum
Description Retrieves the maximum value used by the progress bar incrementation process.
Access Public
Syntax instancename.of_GetMaximum ( )
Argument Description
instancename Instance name of u_progressbar

Return value Integer. Returns the maximum increment value for the progress bar.
Examples This example calls the of_GetMaximum function:
uo_progress.of_SetPosition(0)
FOR li_count = 1 TO &
uo_progress.of_GetMaximum() STEP 1
uo_progress.of_Increment(1)
// Additional code here to perform your process
NEXT

of_GetMessageText
Description Retrieves the progress messages specified in the of_SetMessageText function.
Access Public
Syntax instancename.of_GetMessageText ( text )

Argument Description
instancename Instance name of u_progressbar
text String array into which the function places the progress
messages (passed by reference)

464
 Chapter 7 Custom Visual User Objects

Return value Integer. Returns the number of elements in the text array.
Examples This example calls the of_GetMessageText function:
String ls_text[], ls_all
Integer li_size, li_count

li_size = uo_progress.of_GetMessageText(ls_text)

FOR li_count = 1 to li_size STEP 1

ls_all += ls_text[li_count] + "~r~n"
NEXT
MessageBox("Progress Bar", &
"Progress messages are: " + ls_all)

of_GetMinimum
Description Retrieves the minimum value used by the incrementation process. This value
is the baseline from which the incrementation process begins.
Access Public
Syntax instancename.of_GetMinimum ( )
Argument Description
instancename Instance name of u_progressbar

Return value Integer. Returns the minimum value for the incrementation process.
Examples This example calls the of_GetMinimum function:
Integer li_min

li_min = uo_progress.of_GetMinimum )
MessageBox("Progress Bar", &
"Minimum value is " &
+ String(li_min))

of_GetPctComplete
Description Retrieves the progress bar’s current percent complete.
Access Public
Syntax instancename.of_GetPctComplete ( )
Argument Description
instancename Instance name of u_progressbar

465
u_progressbar

Return value Integer. Returns the current percent complete for the progress bar.
Examples This example calls the of_GetPctComplete function:
Integer li_count

FOR li_count = 1 TO &

uo_progress.of_GetMaximum() STEP 1
uo_progress.of_Increment(1)
gnv_app.of_GetFrame().SetMicroHelp &
("Count is: " + String(li_count) + &
" Pct Complete is: " + &
String(uo_progress.of_GetPctComplete()))
// Additional code here to perform your process
NEXT

of_GetPosition
Description Retrieves the progress bar’s current increment value.
Access Public
Syntax instancename.of_GetPosition ( )
Argument Description
instancename Instance name of u_progressbar

Return value Integer. Returns the current increment value for the progress bar.
Examples This example calls the of_GetPosition function:
Integer li_count

FOR li_count = 1 TO &

uo_progress.of_GetMaximum() STEP 1
uo_progress.of_Increment(1)
gnv_app.of_GetFrame().SetMicroHelp &
("Count is: " + &
String(uo_progress.of_GetPosition()) + &
" Pct Complete is: " + &
String(uo_progress.of_GetPctComplete()))
// Additional code here to perform your process
NEXT

of_GetStep
Description Retrieves the step value the progress bar uses during a default increment
process.

466
 Chapter 7 Custom Visual User Objects

Access Public
Syntax instancename.of_GetStep ( )
Argument Description
instancename Instance name of u_progressbar

Return value Integer. Returns the step value.

Examples This example calls the of_GetStep function:
Integer li_step

li_step = uo_progress.of_GetStep()
MessageBox("Progress Bar", &
"Step value is " + String(li_step))

of_GetTextColor
Description Retrieves the text color for the progress bar.
Access Public
Syntax instancename.of_GetTextColor ( )
Argument Description
instancename Instance name of u_progressbar

Return value Long. Returns the progress bar text color.

Examples This example calls the of_GetTextColor function:
Long ll_color

ll_color = uo_progress.of_GetTextColor()
MessageBox("Progress Bar", &
"Current text color is " + String(ll_color))

of_Increment
Description Increments progress by either the default increment value or by a specified
value.
Access Public
Syntax instancename.of_Increment ( { incrementvalue } )
Argument Description
instancename Instance name of u_progressbar

467
u_progressbar

Argument Description
incrementvalue Integer specifying the increment value. The default increment
(optional) value is 10, which you can modify by calling the of_SetStep
function

Return value Integer. Returns the new increment value.

Examples This example calls the of_Increment function:
Integer li_count

uo_progress.of_SetPosition(0)
FOR li_count = 1 TO &
uo_progress.of_GetMaximum() STEP 1
uo_progress.of_Increment(1)
// Additional code here to perform your process
NEXT

of_IsAutoReset
Description Reports whether the progress bar returns to zero after it reaches 100%.
Access Public
Syntax instancename.of_IsAutoReset ( )
Argument Description
instancename Instance name of u_progressbar

Return value Boolean. Returns TRUE if u_progressbar clears the progress bar when it
reaches 100% and FALSE if it does not.
Examples This example calls the of_IsAutoReset function:
n_cst_conversion lnv_conversion
Boolean lb_autoreset

lb_autoreset = uo_progress.of_IsAutoReset()
MessageBox("Progress Bar", &
"Autoreset property is " &
+ lnv_conversion.of_String(lb_autoreset))

of_Reset
Description Clears the progress bar, setting the position to the minimum and percent
complete to zero.
Access Public

468
 Chapter 7 Custom Visual User Objects

Syntax instancename.of_Reset ( )
Argument Description
instancename Instance name of u_progressbar

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example is from the of_SetPosition function:
...
IF ldc_completion >= 1 and ib_autoreset THEN
this.Post Function of_Reset()
END IF
...

of_SetAutoReset
Description Specifies whether to clear the progress bar when it reaches 100%. The progress
bar reaches 100% when the incrementation process reaches the maximum
value.
Access Public
Syntax instancename.of_SetAutoReset ( boolean )
Argument Description
instancename Instance name of u_progressbar
boolean Boolean indicating whether to clear the status bar when it
reaches 100% (TRUE) or leave it visible (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetAutoReset function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetAutoReset(FALSE)

of_SetBackColor
Description Sets the background color of the progress bar.
Access Public
Syntax instancename.of_SetBackColor ( color )
Argument Description
instancename Instance name of u_progressbar

469
u_progressbar

Argument Description
color Long specifying the progress bar fill color. The default is
78682240 (light gray)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example from the Constructor event of a u_progressbar instance calls the
of_SetBackColor function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetBackColor (RGB(255, 0, 0)) // Red
of_SetAutoReset(FALSE)

of_SetDisplayStyle
Description Sets a display style for the progress bar. The display style controls the
information that displays within the bar while tracking progress.
Access Public
Syntax instancename.of_SetDisplayStyle ( displaystyle )
Argument Description
instancename Instance name of u_progressbar
displaystyle Integer or u_progressbar constant specifying the progress bar
display style:
• 0 or BAR (default) Bar only, no text
• 1 or PCTCOMPLETE Bar displays percent complete,
including the percent sign
• 2 or POSITION Bar displays the current increment value
• 3 or MSGTEXT Bar displays text, as specified by the
of_SetMessageText function

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage If you use MSGTEXT, you must also call the of_SetMessageText function to
specify the text displayed in the status bar.
Examples This example from the Constructor event of a u_progressbar instance calls the
of_SetDisplayStyle function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)

470
 Chapter 7 Custom Visual User Objects

of_SetFillColor
Description Sets the fill color of the progress bar.
Access Public
Syntax instancename.of_SetFillColor ( color )
Argument Description
instancename Instance name of u_progressbar
color Long specifying the progress bar fill color. The default is
16668075 (blue)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example from the Constructor event of a u_progressbar instance calls the
of_SetFillColor function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetFillColor (RGB(128, 128, 128))

of_SetFillStyle
Description Sets a fill style for the progress bar.
Access Public
Syntax instancename.of_SetFillStyle ( style )
Argument Description
instancename Instance name of u_progressbar
style Integer or u_progressbar constant specifying the fill style:
• 0 or TOPDOWN The bar fills from top to bottom
• 1 or BOTTOMUP The bar fills from bottom to top
• 2 or LEFTRIGHT (default) The bar fills from left to right
• 3 or RIGHTLEFT The bar fills from right to left

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetFillStyle function:
of_SetFillStyle (BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetFillColor(RGB(128, 128, 128))

471
u_progressbar

of_SetFont
Description Changes the font displayed in the progress bar.
Access Protected
Syntax instancename.of_SetFont ( fontface, fontsize, fontcharset, fontfamily,
fontpitch, bold, italic, underline )

Argument Description
instancename Instance name of u_progressbar
fontface String specifying the new font. If you pass a NULL, the function
does not change the font
fontsize Integer specifying the point size of the new font. If you pass a
NULL, the function does not change the font size
fontcharset Integer specifying the character set:
• 0–ANSI
• 1–The default character set for the specified font
• 2–Symbol
• 3–Shift JIS
• 4–OEM
If you pass a NULL, the function does not change the font
character set
fontfamily FontFamily enumerated data type specifying the font family:
• AnyFont!
• Roman!
• Swiss!
• Modern!
• Script!
• Decorative!
If you pass a NULL, the function does not change the font family
fontpitch FontPitch enumerated data type specifying the pitch of the new
font:
• Default!
• Fixed!
• Variable!
If you pass a NULL, the function does not change the pitch

472
 Chapter 7 Custom Visual User Objects

Argument Description
bold Boolean specifying whether text is bold:
• TRUE—Bold
• FALSE—Not bold (default)
If you pass a NULL, the function does not change the Bold
property
italic Boolean specifying whether text is italic:
• TRUE—Italic
• FALSE—Not italic (default)
If you pass a NULL, the function does not change the italic
property
underline Boolean specifying whether text is underlined:
• TRUE—Underlined
• FALSE—Not underlined (default)
If you pass a NULL, the function does not change the underline
property

Return value String. Returns the result of the Modify PowerScript function that changes the
font; an empty string indicates success.
Usage Internal.
Examples This example is from the of_SetFontBold function:
String ls_fontface
Long ll_fontsize
FontFamilylff_fontfamily
FontPitchlfp_fontpitch
Boolean lb_bold, lb_italic, lb_underline

SetNull(ls_fontface)
SetNull(ll_fontsize)
SetNull(lff_fontfamily)
SetNull(lfp_fontpitch)
SetNull(lb_bold)
SetNull(lb_italic)
SetNull(lb_underline)

// ab_bold is the argument to of_SetBold

Return of_SetFont(ls_fontface, ll_fontsize, &
lff_fontfamily, lfp_fontpitch, ab_bold, &
lb_italic, lb_underline)

473
u_progressbar

of_SetFontBold
Description Sets the Bold property for progress bar text.
Access Public
Syntax instancename.of_SetFontBold ( boolean )
Argument Description
instancename Instance name of u_progressbar
boolean Boolean specifying whether progress bar text is bold (TRUE)
or not (FALSE)

Return value String. Returns the result of the Modify PowerScript function that changes the
Bold property; an empty string indicates success.
Examples This example calls the of_SetFontBold function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetFillColor(RGB(128, 128, 128))
of_SetFontBold(TRUE)

of_SetFontCharSet
Description Sets the CharSet property for progress bar text.
Access Public
Syntax instancename.of_SetFontCharSet ( fontcharset )
Argument Description
instancename Instance name of u_progressbar
fontcharset Integer specifying the character set:
• 0–ANSI
• 1–The default character set for the specified font
• 2–Symbol
• 3–Shift JIS
• 4–OEM

Return value String. Returns the result of the Modify PowerScript function that changes the
font face; an empty string indicates success.
Examples This example calls the of_SetFontCharSet function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetFillColor(RGB(128, 128, 128))

474
 Chapter 7 Custom Visual User Objects

of_SetFontCharSet(1)
of_SetFontFamily(Script!)
of_SetFontSize(12)

of_SetFontFace
Description Sets the Face (typeface) property for progress bar text.
Access Public
Syntax instancename.of_SetFontFace ( fontface )
Argument Description
instancename Instance name of u_progressbar
fontface String specifying the font face (such as Arial)

Return value String. Returns the result of the Modify PowerScript function that changes the
font face; an empty string indicates success.
Examples This example from the Constructor event of a u_progressbar instance calls the
of_SetFontFace function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetFillColor(RGB(128, 128, 128))
of_SetFontFace("Monotype Corsiva")
of_SetFontFamily(Script!)

of_SetFontFamily
Description Sets the font Family property (such as Roman) for progress bar text.
Access Public
Syntax instancename.of_SetFontFamily ( fontfamily )
Argument Description
instancename Instance name of u_progressbar
fontfamily FontFamily enumerated data type specifying the font family:
• AnyFont!
• Roman!
• Swiss!
• Modern!
• Script!
• Decorative!

475
u_progressbar

Return value String. Returns the result of the Modify PowerScript function that changes the
font family; an empty string indicates success.
Examples This example calls the of_SetFontFamily function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetFillColor(RGB(128, 128, 128))
of_SetFontFace("Monotype Corsiva")
of_SetFontFamily(Script!)

of_SetFontItalic
Description Sets the Italic property for progress bar text.
Access Public
Syntax instancename.of_SetFontItalic ( boolean )
Argument Description
instancename Instance name of u_progressbar
boolean Boolean specifying whether progress bar text is italic (TRUE)
or not (FALSE)

Return value String. Returns the result of the Modify PowerScript function that changes the
Italic property; an empty string indicates success.
Examples This example calls the of_SetFontItalic function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetFillColor(RGB(128, 128, 128))
of_SetFontItalic (TRUE)

of_SetFontPitch
Description Sets the Pitch property for progress bar text.
Access Public
Syntax instancename.of_SetFontPitch ( fontpitch )
Argument Description
instancename Instance name of u_progressbar

476
 Chapter 7 Custom Visual User Objects

Argument Description
fontpitch FontPitch enumerated data type specifying the font pitch:
• Default!
• Fixed!
• Variable!

Return value String. Returns the result of the Modify PowerScript function that changes the
font pitch; an empty string indicates success.
Examples This example calls the of_SetFontPitch function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetFillColor(RGB(128, 128, 128))
of_SetFontPitch(Variable!)

of_SetFontSize
Description Sets the Size property for progress bar text.
Access Public
Syntax instancename.of_SetFontSize ( fontsize )
Argument Description
instancename Instance name of u_progressbar
fontsize Long specifying the font size, in points, for the progress bar
text. Do not specify a negative number for this value

Return value String. Returns the result of the Modify PowerScript function that changes the
font size; an empty string indicates success.
Examples This example calls the of_SetFontSize function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetFontSize(10)

of_SetFontUnderline
Description Sets the Underline property for progress bar text.
Access Public
Syntax instancename.of_SetFontUnderline ( boolean )

477
u_progressbar

Argument Description
instancename Instance name of u_progressbar
boolean Boolean specifying whether progress bar text is underlined
(TRUE) or not (FALSE)

Return value String. Returns the result of the Modify PowerScript function that changes the
underline property; an empty string indicates success.
Examples This example calls the of_SetFontUnderline function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetFontUnderline (TRUE)

of_SetMaximum
Description Sets the maximum increment value for the progress bar (also used as the basis
for the progress bar’s percent complete calculation).
Access Public
Syntax instancename.of_SetMaximum ( maximum )
Argument Description
instancename Instance name of u_progressbar
maximum Integer specifying the maximum increment value.

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The default for this value is 100. The of_SetPosition function uses this value as
the dividend in its percent complete calculation (percent complete = current
position/maximum * 100).
Examples This example calls the of_SetMaximum function:
SELECT COUNT(emp_id)
INTO :il_max
FROM Employee
USING SQLCA ;
IF il_max > 0 THEN
uo_progress.of_SetMaximum(il_max)
ELSE
MessageBox("SQL error", &
"SELECT COUNT failed~r~n" + SQLCA.SQLERRTEXT)
END IF

478
 Chapter 7 Custom Visual User Objects

of_SetMessageText
Description Sets the text strings that display at regular intervals when the progress bar uses
the message text display style.
Access Public
Syntax instancename.of_SetMessageText ( text )
Argument Description
instancename Instance name of u_progressbar
text String array whose elements contain the values to display on
the progress bar

Return value Integer. Returns the number of elements in text if the function succeeds and -1
if an error occurs.
Usage You typically call this function after calling of_SetDisplayStyle(MSGTEXT).
Examples This example calls the of_SetMessageText function:
String ls_msgtext[ ] = {"Ten", "Twenty", &
"Thirty", "Forty", "Fifty", "Sixty", &
"Seventy", "Eighty", "Ninety", "One Hundred"}

of_SetDisplayStyle(MSGTEXT)
of_SetMessageText(ls_msgtext)

of_SetMinimum
Description Sets the initial increment value for the progress bar.
Access Public
Syntax instancename.of_SetMinimum ( minimum )
Argument Description
instancename Instance name of u_progressbar
minimum Integer specifying the initial increment value for the progress bar

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The of_SetPosition and of_Reset functions use the minimum to determine the
initial position value.
Examples This example calls the of_SetMinimum function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetMinimum(0)

479
u_progressbar

of_SetPosition
Description Sets the progress bar’s current position and updates percent complete.
Access Public
Syntax instancename.of_SetPosition ( position )
Argument Description
instancename Instance name of u_progressbar
position Integer specifying the progress bar’s position

Return value Integer. Returns the current increment value if the function succeeds and -1 if
an error occurs.
Usage Call this function to establish an initial position for the progress bar before
beginning an incrementation process.
If position is less than the minimum (the default minimum is 0), this function
sets the position to the minimum. If position is greater than the maximum (the
default maximum is 100), this function sets the position to the maximum. You
modify the default minimum and maximum by calling the of_SetMinimum and
of_SetMaximum functions.
The of_Increment function calls this function to update the current position and
percent complete.
Examples This example calls the of_SetPosition function:
Integer li_count

uo_progress.of_SetPosition(0)
For li_count = 1 to 100 STEP 1
uo_progress.of_Increment(1)
NEXT

of_SetStep
Description Sets the step value the progress bar uses during a default increment process.
Access Public
Syntax instancename.of_SetStep ( stepvalue )
Argument Description
instancename Instance name of u_progressbar
stepvalue Integer specifying the default increment value

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.

480
 Chapter 7 Custom Visual User Objects

Usage The progress bar uses this value as the default when you call of_Increment with
no arguments.
Examples This example calls the of_SetStep function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetStep(5)

of_SetTextColor
Description Sets the color of text in the progress bar.
Access Public
Syntax instancename.of_SetTextColor ( color )
Argument Description
instancename Instance name of u_progressbar
color Long specifying the progress bar text color. The default is 0
(black)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example from the Constructor event of a u_progressbar instance calls the
of_SetTextColor function:
of_SetFillStyle(BOTTOMUP)
of_SetDisplayStyle(PCTCOMPLETE)
of_SetTextColor(RGB(255, 255, 255))

of_UpdateVisuals
Description Resizes the progress bar and updates the display text.
Access Protected
Syntax instancename.of_UpdateVisuals ( completionvalue )
Argument Description
instancename Instance name of u_progressbar
completionvalue Decimal specifying the completion value of the progress bar

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.

481
u_progressbar

Examples This example is from the of_SetPosition function:

...
li_rc = of_UpdateVisuals (ldc_completion)
dw_progress.SetRedraw(true)
...

482
 Chapter 7 Custom Visual User Objects

u_st_splitbar
Description Splitbar service. Use this control to add splitbar functionality to two or more
controls in a window.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this object to add a splitbar to a window. To use this object:
1 Place the object on a window between two or more controls.
2 (Optional) If you are using the window resize service, register the splitbar:
this.of_SetResize(TRUE)
this.inv_resize.of_Register &
(tv_deptemp, 0, 0, 0, 100)
this.inv_resize.of_Register &
(st_splitbar, 0, 0, 0, 100)
this.inv_resize.of_Register &
(lv_empdetail, 0, 0, 0, 100)
3 Move and resize the splitbar object and the surrounding objects until they
relate appropriately. For example, a vertical splitbar between two objects
should have the same height as the surrounding objects.
4 Add code to the splitbar control’s Constructor event to register the controls
that resize when the user moves the splitbar:
this.of_Register(tv_1, LEFT
this.of_Register(lv_1, RIGHT)
this.of_SetBarColor(RGB(192, 192, 192))
See also n_cst_resize

483
u_st_splitbar

Instance variables
U_st_splitbar has instance variables:
Name Description Data type Access Usage
ABOVE Constant set to 3 Integer Public Use with
of_Register
BELOW Constant set to 4 Integer Public Use with
of_Register
BOTTOMMOST Constant set to 4 Integer Protected Internal
HORIZONTAL Constant set to 2 Integer Public Internal
ib_performredraw Controls redraw Boolean Protected Internal
idrg_lefttop[ ] Upper-left coordinate for all DragObject Protected Internal
registered controls
idwg_rightbottom[ ] Lower-right coordinate for all DragObject Protected Internal
registered controls
ii_barwidth Thickness of splitbar Integer Protected Internal
ii_lefttopbound Upper-left coordinate Integer Protected Internal
ii_minobjectsize Minimum object size Integer Protected Set with
of_SetMinObject
Size
ii_prevpositionx Previous x coordinate Integer Protected Internal
ii_prevpositiony Previous y coordinate Integer Protected Internal
ii_bottomrightbound Bottom right coordinate Integer Protected Internal
ii_rounding Rounding factor Integer Protected Internal
ii_style Splitbar style (horizontal or Integer Protected Set with
vertical) of_SetStyle
il_barcolor Splitbar color Long Protected Set with
of_SetBarColor
il_barmovecolor Splitbar color when it is being Long Protected Set with
moved of_SetBarMove
Color
ir_lefttopheight[ ] Left top height for all registered Real Protected Internal
controls
ir_lefttopwidth[ ] Left top width for all registered Real Protected Internal
controls
ir_lefttopx[ ] Top left x coordinate for all Real Protected Internal
registered controls
ir_lefttopy[ ] Top left y coordinate for all Real Protected Internal
registered controls

484
 Chapter 7 Custom Visual User Objects

Name Description Data type Access Usage

ir_rightbottomheight[ ] Bottom right height for all Real Protected Internal
registered controls
ir_rightbottomwidth[ ] Bottom right width for all Real Protected Internal
registered controls
ir_rightbottomx[ ] Bottom right x coordinate for all Real Protected Internal
registered controls
ir_rightbottomy[ ] Bottom right y coordinate for all Real Protected Internal
registered controls
is_horizontalpointer Icon name for the pointer that String Protected Set with
displays when over a horizontal of_SetHorizontal
splitbar Pointer (default is
SizeNS!)
is_verticalpointer Icon name for the pointer that String Protected Set with
displays when over a vertical of_SetHorizontal
splitbar Pointer (default is
SizeWE!)
itab_parent References the Tab control that Tab Protected Internal
contains the splitbar
iuo_parent References the custom standard UserObject Protected Internal
user object that contains the
splitbar
iw_parent References the window that Window Protected Internal
contains the splitbar
LEFT Constant set to 1 Integer Public Use with
of_Register
LEFTMOST Constant set to 1 Integer Protected Internal
RIGHT Constant set to 2 Integer Public Use with
of_Register
RIGHTMOST Constant set to 2 Integer Protected Internal
TOPMOST Constant set to 3 Integer Protected Internal
VERTICAL Constant set to 1 Integer Public Vertical

Events
U_st_splitbar includes precoded events:
Constructor MouseMove
LButtonUp

485
u_st_splitbar

Constructor
Description Automatically calculates the bar orientation (vertical or horizontal) and
initializes other status-bar settings.
Usage Add code to this event to register the controls that resize when the user moves
the splitbar.
Examples This example shows code you might add to the Constructor event:
this.of_Register(tv_1, LEFT)
this.of_Register(lv_1, RIGHT)
this.of_SetBarColor(RGB(192, 192, 192))

LButtonUp
Description Calls the of_LButtonUp function.
Usage PFC uses this event to resize objects when the user moves the splitbar.

MouseMove
Description Calls the of_MouseMove function.
Usage If the user presses the left mouse button, PFC uses this event to move the
splitbar, refresh the location, and redraw if necessary.

Functions
U_st_splitbar contains precoded object functions:
of_GetBarColor of_Redraw
of_GetBarMoveColor of_Register
of_GetExtremePoint of_SetBarColor
of_GetHorizontalPointer of_SetBarMoveColor
of_GetInfo of_SetHorizontalPointer
of_GetMinObjectSize of_SetMinObjectSize
of_GetVerticalPointer of_SetVerticalPointer
of_LButtonUp of_UpdateObjectData
of_MouseMove

486
 Chapter 7 Custom Visual User Objects

of_GetBarColor
Description Retrieves the splitbar color.
Access Public
Syntax instancename.of_GetBarColor ( )
Argument Description
instancename Instance name of u_st_splitbar

Return value Long. Returns the splitbar color.

Examples This example calls the of_GetBarColor function:
Long ll_colorll_color = st_splitbar.of_GetBarColor()

of_GetBarMoveColor
Description Retrieves the color that displays when the splitbar is being moved.
Access Public
Syntax instancename.of_GetBarMoveColor ( )
Argument Description
instancename Instance name of u_st_splitbar

Return value Long. Returns the splitbar move color.

Examples This example calls the of_GetBarMoveColor function:
Long ll_colorll_color =
st_splitbar.of_GetBarMoveColor()

of_GetExtremePoint
Description Retrieves the specified extreme point coordinate.
Access Public
Syntax instancename.of_GetExtremePoint ( extremetype )
Argument Description
instancename Instance name of u_st_splitbar

487
u_st_splitbar

Argument Description
extremetype Integer or u_st_splitbar constant that specifies the extreme point
to be returned:
• 1 or LEFTMOST The extreme point to the left
• 2 or RIGHTMOST The extreme point to the right
• 3 or TOPMOST The extreme point at the top
• 4 or BOTTOMMOST The extreme point at the bottom

Return value Integer. Returns the coordinate of the specified extreme point.
Usage Internal.
Examples This example is from the of_LButtonUp function:
...
IF ii_style = HORIZONTAL THEN
li_miny = of_GetExtremePoint(TOPMOST)
li_maxy = of_GetExtremePoint(BOTTOMMOST)
...

of_GetHorizontalPointer
Description Retrieves the name of the pointer that displays when the cursor is over a
horizontal splitbar.
Access Public
Syntax instancename.of_GetHorizontalPointer ( )
Argument Description
instancename Instance name of u_st_splitbar

Return value String. Returns the name of the pointer that displays when the cursor is over a
horizontal splitbar.
Examples This example calls the of_GetHorizontalPointer function:
String ls_pointer

ls_pointer = st_1.of_GetHorizontalPointer()
MessageBox("Splitbar", &
"Horizontal pointer is " + ls_pointer)

of_GetInfo
Description Retrieves object information.

488
 Chapter 7 Custom Visual User Objects

Access Public
Syntax dwcontrol.instancename.of_GetInfo ( infoobject )
Argument Description
instancename Instance name of u_st_splitbar
infoobject N_cst_infoattrib instance into which the function places
information (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The DataWindow Properties window calls this function to access service
information:
Examples This example calls the of_GetInfo function:
n_cst_infoattrib lnv_info

uo_splitbar.of_GetInfo(lnv_info)
MessageBox("Info", &
"Description: " + lnv_info.is_description &
+ ". Name: " + lnv_info.is_name)

of_GetMinObjectSize
Description Retrieves the minimum size (in PBUs) for registered objects.
Access Public
Syntax instancename.of_GetMinObjectSize ( )
Argument Description
instancename Instance name of u_st_splitbar

Return value Integer. Returns the minimum size for registered objects.
Examples This example calls the of_GetMinObjectSize function:
Integer li_minsize

li_minsize = st_1.of_GetMinObjectSize()
MessageBox("Splitbar", &
"Minimum size is " + String(li_minsize))

of_GetVerticalPointer
Description Retrieves the name of the pointer that displays when the cursor is over a
vertical splitbar.

489
u_st_splitbar

Access Public
Syntax instancename.of_GetVerticalPointer ( )
Argument Description
instancename Instance name of u_st_splitbar

Return value String. Returns the name of the pointer that displays when the cursor is over a
vertical splitbar.
Examples This example calls the of_GetVerticalPointer function:
String ls_pointer

ls_pointer = st_1.of_GetVerticalPointer()
MessageBox("Splitbar", &
"Vertical pointer is " + ls_pointer)

of_LButtonUp
Description Resizes registered objects when the user releases the left mouse button.
Access Protected
Syntax instancename.of_LButtonUp ( flags, x, y )
Argument Description
instancename Instance name of u_st_splitbar
flags UnsignedLong indicating the modifier keys and mouse buttons
that were pressed
x Integer indicating the x position of the mouse click
y Integer indicating the y position of the mouse click

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the LButtonUp event:
of_LButtonUp(flags, xpos, ypos)

of_MouseMove
Description Refreshes the screen as the user moves the splitbar.
Access Protected
Syntax instancename.of_MouseMove ( flags, x, y )

490
 Chapter 7 Custom Visual User Objects

Argument Description
instancename Instance name of u_st_splitbar
flags UnsignedLong indicating the modifier keys and mouse buttons
that are currently pressed
x Integer indicating the x position of the mouse
y Integer indicating the y position of the mouse

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the MouseMove event:
IF NOT KeyDown(keyLeftButton!) THEN
Return
END IF
of_MouseMove(flags, xpos, ypos)

of_Redraw
Description Redraws objects adjacent to the splitbar.
Access Protected
Syntax instancename.of_Redraw ( x, width, y, height )
Argument Description
instancename Instance name of u_st_splitbar
x Integer specifying the splitbar’s previous x coordinate
width Integer specifying the splitbar’s previous width
y Integer specifying the splitbar’s previous y coordinate
height Integer specifying the splitbar’s previous height

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_MouseMove function:
...
IF ii_style = HORIZONTAL THEN
this.Y = li_pointery
this.Height = ii_barwidth
IF ib_performredraw THEN
IF (li_prevy <> this.Y) THEN
of_Redraw(li_prevx, li_prevwidth, &
li_prevy, li_prevheight)

491
u_st_splitbar

END IF
END IF
...

of_Register
Description Registers the controls to be moved and resized when the user moves the
splitbar.
Access Public
Syntax instancename.of_Register ( control, relativeposition )
Argument Description
instancename Instance name of u_st_splitbar
control DragObject containing the control to be registered
relativeposition Integer or u_st_splitbar constant specified how the service
positions control relative to the splitbar:
• 1 or LEFT Position control to the left of the splitbar
• 2 or RIGHT Position control to the right of the splitbar
• 3 or ABOVE Position control above the splitbar
• 4 or BELOW Position control below the splitbar

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function in the splitbar’s Constructor event to specify the controls
affected by the splitbar.
Examples This example calls the of_Register function:
this.of_Register (tv_1, LEFT)
this.of_Register (lv_1, RIGHT)
this.of_SetBarColor(RGB(192, 192, 192))

of_SetBarColor
Description Specifies the splitbar color.
Access Public
Syntax instancename.of_SetBarColor ( color )
Argument Description
instancename Instance name of u_st_splitbar
color Long specifying the splitbar color. The default bar color is
maintained in the il_barcolor instance variable

492
 Chapter 7 Custom Visual User Objects

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function in the splitbar’s Constructor event.
Examples This example calls the of_SetBarColor function:
this.of_SetBarColor(RGB(192, 192, 192))

of_SetBarMoveColor
Description Specifies the color that displays when the splitbar is being moved.
Access Public
Syntax instancename.of_SetBarMoveColor ( color )
Argument Description
instancename Instance name of u_st_splitbar
color Long specifying the splitbar color when the user moves it. The
default bar move color is maintained in the il_barmovecolor
instance variable

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function in the splitbar’s Constructor event.
Examples This example calls the of_SetBarMoveColor function:
this.of_Register(tv_1, LEFT)
this.of_Register(lv_1, RIGHT)
this.of_SetBarColor(RGB(192, 192, 192))
this.of_SetBarMoveColor(RGB(0, 0, 0))

of_SetHorizontalPointer
Description Specifies the name of the pointer that displays when the cursor is over a
horizontal splitbar.
Access Public
Syntax instancename.of_SetHorizontalPointer ( pointername )
Argument Description
instancename Instance name of u_st_splitbar

493
u_st_splitbar

Argument Description
pointername String specifying the pointer that displays when the cursor is
over a horizontal splitbar. This can be one of the following:
• Arrow!
• Beam!
• Cross!
• Hourglass!
• SizeNESW!
• SizeNS! (default)
• SizeNWSE!
• SizeWE!
• Uparrow!
• Name of a customized cursor file (CUR extension). This file
must be accessible at execution time

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function in the splitbar’s Constructor event.
Examples This example calls the of_SetHorizontalPointer function:
this.of_Register(tv_1, LEFT)
this.of_Register(lv_1, RIGHT)
this.of_SetHorizontalPointer ("SizeNS!")

of_SetMinObjectSize
Description Specifies the minimum size (in PBUs) for registered objects.
Access Public
Syntax instancename.of_SetMinObjectSize ( minimumsize )
Argument Description
instancename Instance name of u_st_splitbar
minimumsize Integer specifying the minimum size (in PBUs) for registered
objects

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function in the splitbar’s Constructor event.
Examples This example calls the of_SetMinObjectSize function:
this.of_Register(tv_1, LEFT)
this.of_Register(lv_1, RIGHT)

494
 Chapter 7 Custom Visual User Objects

this.of_SetBarColor(RGB(192,192,192))
this.of_SetBarMoveColor(RGB(128, 128, 128))
this.of_SetMinObjectSize(100)

of_SetVerticalPointer
Description Specifies the name of the pointer that displays when the cursor is over a vertical
splitbar.
Access Public
Syntax instancename.of_SetVerticalPointer ( pointername )
Argument Description
instancename Instance name of u_st_splitbar
pointername String specifying the pointer that displays when the cursor is
over a vertical splitbar. This can be one of the following:
• Arrow!
• Beam!
• Cross!
• Hourglass!
• SizeNESW!
• SizeNS! (default)
• SizeNWSE!
• SizeWE!
• Uparrow!
• Filename of a customized cursor file (CUR extension). This
file must be accessible at execution time

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function in the splitbar’s Constructor event.
Examples This example calls the of_SetVerticalPointer function:
this.of_Register(tv_1, LEFT)
this.of_Register(lv_1, RIGHT)
this.of_SetBarColor(RGB(192,192,192))
this.of_SetVerticalPointer("SizeWE!")

of_UpdateObjectData
Description Updates the instance variables that maintain object coordinates.
Access Protected

495
u_st_splitbar

Syntax instancename.of_UpdateObjectData ( )
Argument Description
instancename Instance name of u_st_splitbar

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.
Examples This example is from the of_LButtonUp function:
...
li_deltax = li_pointerx - ii_prevpositionx
li_deltay = li_pointery - ii_prevpositiony
of_UpdateObjectData()
...

496
 Chapter 7 Custom Visual User Objects

u_tabpg
Description Tab page visual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this visual object in the User Object painter as the ancestor for all tab
pages. After defining the tab page’s appearance and functionality, you then
place these tab pages on tab user objects in the User Object painter. To insert a
tab page object, click the right mouse button on a tab control, select Insert
UserObject, and double-click on a u_tabpg descendant.
See also u_tab

497
u_tabpg

498
CH A PTE R 8 Standard Class User Objects

About this chapter This chapter describes the standard class user objects in PFC.
Contents The standard class user objects are listed in alphabetical order. Each
object’s discussion includes an alphabetical listing of instance variables,
events, and object functions.

499
n_cn

n_cn
Description Connection object for use with all distributed PFC applications. You can either
use this object as is or create descendants that include customized or extended
functionality.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use n_cn whenever you would normally create a Connection object. By calling
the of_Init function, you can easily initialize the Connection object.
To use n_cn:
1 Declare a variable of type n_cn (this example declares an instance
variable):
n_cn icn_connection
2 Create the Connection object:
icn_connection = CREATE n_cn
3 Call the of_Init function to initialize Connection object fields:
icn_connection.of_Init &
(gnv_app.of_GetAppINIFile(),"Connect")
4 Continue the distributed application as appropriate.
See also n_trp

Functions
N_cn includes precoded object functions:
of_Init
of_MessageBox

500
 Chapter 8 Standard Class User Objects

of_Init
Description Initializes a Connection object’s properties using values from an INI file
section or registry key.
Access Public
Syntax instancename.of_Init ( fileorkey, section )
Argument Description
instancename Instance name of n_cn
fileorkey String specifying either the INI file or the registry key containing
connection information. If you specify the INI file, you must also
specify section
section String specifying the INI file section containing connection
information. If fileorkey specifies an INI file, you must specify
this value; if fileorkey specifies a registry key, you cannot specify
this value

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage The INI file section or registry key must contain the following keywords:
Application
ConnectString
Driver
Location
Options
Password
Trace
UserID
If the INI file section or registry key doesn’t have a value, the function defaults
the value to an empty string.
For complete information on distributed computing, see Application
Techniques.
Examples This example calls the of_Init function (assuming an icn_connection instance
variable):
Integer li_return

icn_connection = CREATE n_cn

li_return = icn_connection.of_Init &
("c:\HKEY_CURRENT_USER\Software\" &
+ "Powersoft\EISUSER\Connect")
IF li_return = -1 THEN
MessageBox("Connect", &

501
n_cn

"Remote connection error")

ELSE
gnv_app.of_GetFrame().SetMicroHelp &
("Connection succeeded")
END IF

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of n_cn
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in Connection objects.

502
 Chapter 8 Standard Class User Objects

The id argument is not used in the default implementation.

Examples This example calls the of_MessageBox function:
of_Messagebox(’pfc_cn_dberror’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

503
n_cxinfo

n_cxinfo
Description ContextInformation nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder
ContextInformation object.
See also n_cxk
n_inet
n_ir
n_srv

504
 Chapter 8 Standard Class User Objects

n_cxk
Description ContextKeyword nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder
ContextKeyword object.
See also n_cxinfo
n_inet
n_ir
n_srv

505
n_dda

n_dda
Description DynamicDescriptionArea nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder
DynamicDescriptionArea object.
See also n_dsa
n_err
n_msg
n_tr

506
 Chapter 8 Standard Class User Objects

n_ds
Description DataStore object for use with all PFC applications. This user object includes:
• Functions to enable and disable DataStore services
• Events and functions that call DataStore services
• Events and functions that are called by the logical unit of work service
You can either use this object asis or create descendants that include
customized or extended functionality.
N_ds is a self-updating object.
Ancestry

Library PFCMAIN.PBL
PFEAPSRV.PBL
Object relationships n_cst_conversion
n_cst_dssrv
n_cst_dssrv_multitable
n_cst_dssrv_printpreview
n_cst_dssrv_report
n_cst_platform
n_tr
s_pagesetupattrib

507
n_ds

s_printdlgattrib
w_master
Usage Use n_ds whenever you would normally create a DataStore. N_ds has the same
relationship to n_cst_dssrv as u_dw has to n_cst_dwsrv.
To use n_ds:
1 Declare a variable of type n_ds (this example declares an instance
variable):
n_ds ids_datastore
2 Create the DataStore:
ids_datastore = CREATE n_ds
3 Associate a DataWindow object with the DataStore:
ids_datastore.DataObject = "d_emplist"
4 Set the Transaction object by calling the of_SetTransObject function:
ids_datastore.of_SetTransObject(SQLCA)
5 (Optional) Enable DataStore services:
inv_datastore.of_SetPrintPreview(TRUE)
inv_datastore.of_SetReport(TRUE)
6 Add code to the pfc_Retrieve event to retrieve rows:
Return this.Retrieve()
7 Access data and perform other DataStore functions as needed. This
example retrieves data:
inv_datastore.of_Retrieve()
See also n_cst_dwsrv
u_dw

508
 Chapter 8 Standard Class User Objects

Instance variables
N_ds contains instance variables.
Instance variable Description Data type Access Usage
ib_append Indicates whether Boolean Protected Set with of_SetAppend
the Retrieve
function appends
ib_isupdateable Indicates whether Boolean Protected Set with
the DataStore is of_SetUpdateable
updatable
inv_base Reference variable n_cst_dssrv Public Use in dot notation to
for basic DataStore access n_cst_dssrv
service functions and events
inv_multitable Reference variable n_cst_dssrv_multitable Public Use in dot notation to
for multitable access
update service n_cst_dssrv_multitable
functions and events
inv_printpreview Reference variable n_cst_dssrv_printpreview Public Use in dot notation to
for print preview access
service n_cst_dssrv_printpreview
functions and events
inv_report Reference variable n_cst_dssrv_report Public Use in dot notation to
for report service access n_cst_dssrv_report
functions and events
ipo_updaterequestor Update requestor PowerObject Protected Set with
of_SetUpdateRequestor
is_updatesallowed Specifies allowable String Protected Internal
updates
itr_object Transaction object n_tr Public Set with
used by the of_SetTransObject
DataStore

Events
N_ds includes precoded event scripts:
DBError pfc_ResetUpdate
Destructor pfc_Retrieve
pfc_PageSetup pfc_Ruler
pfc_PageSetupDlg pfc_Update
pfc_PostUpdate pfc_UpdatePrep

509
n_ds

pfc_PrePageSetupDlg pfc_UpdatesPending
pfc_PrePrintDlg pfc_Validation
pfc_Print pfc_Zoom
pfc_PrintDlg RetrieveStart
pfc_PrintImmediate SQLPreview
pfc_PrintPreview

DBError
Description Displays a message box informing the user that a database error occurred.
Usage This event is called when there is a database error.
Because DBError calls the of_GetParentWindow function, a parent window is
required. To let the DataStore know its parent window, you can call the
of_SetParentWindow function after the DataStore creation.

Destructor
Description Destroys all existing DataStore service objects.
Usage This event executes when the DataStore is destroyed.

pfc_PageSetup
Description Calls the pfc_PageSetupDlg event to display the Page Setup dialog box.
Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.

pfc_PageSetupDlg
Description Displays the Page Setup dialog box by calling the n_cst_platform
of_PageSetupDlg function, passing the DataWindow’s page display properties.
Syntax instancename.Event pfc_PageSetupDlg ( attributes )
Argument Description
instancename Instance name of n_ds
attributes S_pagesetupattrib variable into which the event places page setup
information. This argument is accessed through the astr_pagesetup
argument (passed by reference)

510
 Chapter 8 Standard Class User Objects

Return value Integer. Returns 1 if the event succeeds, 0 if the user cancels out of the dialog
box, and -1 if an error occurs.
Usage This event is called by the pfc_PageSetup event.

pfc_PostUpdate
Description Clears the DataStore update flags.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage You can extend this event to code additional post update processing.
Examples This example is from the of_PostUpdate function:
Return this.Event pfc_PostUpdate()

pfc_PrePageSetupDlg
Description Empty user event allowing you to modify the properties passed to the
n_cst_platform of_PageSetupDlg function.
Syntax instancename.Event pfc_PrePageSetupDlg ( attributes )
Argument Description
instancename Instance name of n_ds
attributes S_pagesetupattrib variable into which the event places additional
page setup information. This argument is accessed through the
astr_pagesetup argument (passed by reference)

Usage This event is called by the pfc_PageSetupDlg event before calling the
n_cst_platform of_PageSetupDlg function.
You can use this event to modify or extend the information passed in the
s_pagesettupattrib structure.
Examples This example contains code you might add to the pfc_PrePageSetupDlg event:
// Sets page setup to portrait
astr_pagesetup.b_portraitorientation = TRUE

pfc_PrePrintDlg
Description Empty user event allowing you to modify the properties passed to the
n_cst_platform of_PrintDlg function.
Syntax instancename.Event pfc_PrePrintDlg ( attributes )

511
n_ds

Argument Description
instancename Instance name of n_ds
attributes S_printdlgattrib variable into which the event places additional
printing information. This argument is accessed through the
astr_printdlg argument (passed by reference)

Return value None

Usage Use this event to modify or extend the information passed in the
s_printdlgattrib structure.
Examples This example contains code you might add to the pfc_PrePrintDlg event:
// Default copies to 1
astr_printdlg.l_copies = 1

pfc_Print
Description Calls the pfc_PrintDlg function and prints the DataStore, as specified in the
Print dialog box.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.

pfc_PrintDlg
Description Initializes the s_printdlgattrib structure with the DataStore’s current settings,
displays the Print dialog box by calling the n_cst_platform of_PrintDlg
function, and resets the DataWindow’s settings as specified by the user.
Syntax instancename.Event pfc_PrintDlg ( attributes )
Argument Description
instancename Instance name of n_ds
attributes S_printdlgattrib variable into which the event places printing
information. This argument is accessed through the astr_printdlg
argument (passed by reference)

Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage This event is called by the pfc_Print event.

pfc_PrintImmediate
Description Prints the current DataStore without displaying the Print dialog box.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.

512
 Chapter 8 Standard Class User Objects

pfc_PrintPreview
Description Toggles the DataStore between preview and edit modes.
Return value Boolean. Returns TRUE if the DataStore is placed in preview mode and
FALSE if it is placed in edit mode.
Usage To use this event, you must enable the print preview service by calling the
of_SetPrintPreview function.

pfc_ResetUpdate
Description Clears the DataStore’s update flags.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage The pfc_PostUpdate event calls this event.

pfc_Retrieve
Description Empty user event to contain all database retrieval logic.
Return value Long. Returns the result of the Retrieve function.
Usage You typically call the of_Retrieve function, which calls this event.
Examples This example calls the pfc_Retrieve event:
ids_data = CREATE n_ds
ids_data.DataObject = "d_empall"
ids_data.of_SetTransObject(SQLCA)
IF ids_data.Event pfc_Retrieve() = -1 THEN
SQLCA.of_Rollback()
ELSE
SQLCA.of_Commit( )
END IF
This example shows the code you add to the pfc_Retrieve event to retrieve
rows:
Return this.Retrieve( )

pfc_Ruler
Description Toggles the DataStore between displaying and hiding rulers in print preview
mode.
Return value Boolean. Returns TRUE if print preview rulers are displayed and FALSE if
they are hidden.

513
n_ds

Usage To use this event, you must enable the print preview service by calling the
of_SetPrintPreview function.

pfc_Update
Description Updates the DataStore. If the multitable update service is enabled, this event
updates all specified tables.
Syntax instancename.Event pfc_Update ( accepttext, resetflags )
Argument Description
instancename Instance name of n_ds
accepttext Boolean specifying whether the DataStore control should
automatically perform an AcceptText before performing the
Update (TRUE) or not (FALSE)
resetflags Boolean specifying whether the DataStore control should
automatically reset the update flags (TRUE) or not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this event to update a DataStore.

pfc_UpdatePrep
Description Empty user event to which you can add code that prepares for update.
Return value Long. Return 1 if the update preparation succeeds and -1 to halt the update
process.
Usage The of_UpdatePrep function calls this function.

pfc_UpdatesPending
Description Determines if there are pending updates for the DataStore.
Return value Integer. Returns 1 if there are pending updates for the DataStore and 0 if there
are no pending updates.
Usage This event is called by the of_UpdatesPending function.

pfc_Validation
Description Validates the DataStore, including checks for required fields.
Return value Integer. Returns 1 if the event succeeds and -1 if an error occurs.
Usage Extend this event to perform DataStore-specific validation.

514
 Chapter 8 Standard Class User Objects

pfc_Zoom
Description Displays the w_zoom dialog box, allowing the user to control DataStore
display while in print preview mode.
Return value Integer. Returns the zoom level chosen by the user if the event succeeds, 0 if
the user cancels out of the w_zoom dialog box, and -1 if an error occurs.
Usage To use this event, you must enable the print preview service by calling the
of_SetPrintPreview function.

RetrieveStart
Description Determines whether PowerBuilder should append data to the end of the
DataStore when retrieving.
Usage This event executes just before the actual database retrieval. You can control
whether PowerBuilder appends to the end of the DataStore when retrieving
using the of_SetAppend function.

SQLPreview
Description Invokes the SQL Spy service, if enabled and controls which SQL statements
are sent to the database.
Usage This event executes just before any database access.

Functions
N_ds includes precoded object functions:
of_AcceptText of_SetParentWindow
of_CheckRequired of_SetPrintPreview
of_GetAppend of_SetReport
of_GetParentWindow of_SetTransObject
of_IsUpdateable of_SetUpdateable
of_MessageBox of_SetUpdateRequestor
of_PostUpdate of_Update
of_Retrieve of_UpdatePrep
of_SetAppend of_UpdatesPending
of_SetBase of_Validation
of_SetMultiTable

515
n_ds

of_AcceptText
Description Performs an AcceptText function for the DataStore.
Access Public
Syntax instancename.of_AcceptText ( focusonerror )
Argument Description
instancename Instance name of n_ds
focusonerror Boolean indicating whether PFC sets focus to the DataStore when
an error occurs

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize accept text processing,
extend the pfc_AcceptText event.
Examples This example is from the n_cst_luw of_AcceptText function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_AcceptText &
(ab_focusonerror)
If li_rc < 0 Then Return -1

...

of_CheckRequired
Description Determines if any of required columns contain NULL values.
Access Public
Syntax instancename.of_CheckRequired ( buffer, row, column, colname,
updateonly )
Argument Description
instancename Instance name of n_ds
buffer DWBuffer enumerated data type specifying the DataStore buffer
to check
row Long specifying the first row to check and into which the function
places the number of the row in error (passed by reference)
column Integer specifying the first column to check and into which the
function places the number of the column in error (passed by
reference)

516
 Chapter 8 Standard Class User Objects

Argument Description
colname String specifying the first column to check and into which the
function places the name of the column in error (passed by
reference)
updateonly Boolean indicating whether to validate only those rows and
columns that have changed (TRUE) or validate all rows and
columns

Return value Integer. Returns values as follows:

• 1 The required fields check was successful but errors were found; check
the arguments for missing required fields
• 0 The required fields check was successful and no errors were found
• -1 An error occurred
Usage The pfc_Validation event calls this function.
Examples This example is from the n_ds pfc_Validation event:
...
li_rc = of_CheckRequired (primary!, ll_checkrow, &
li_checkcolumn, ls_checkcolname, ib_updateonly)
if (li_rc < 0) or (ll_checkrow > 0) then return -1
...

of_GetAppend
Description Reports whether DataStore retrieves append to the end of the DataStore.
Access Public
Syntax instancename.of_GetAppend ( )
Argument Description
instancename Instance name of n_ds

Return value Boolean. Returns TRUE if retrieves append to the end of the DataStore and
FALSE if retrieves reset the DataStore before the retrieve.
Examples This example calls the of_GetAppend function:
Boolean lb_append

lb_append = ids_datasource.of_GetAppend()
...

517
n_ds

of_GetParentWindow
Description Retrieves a reference to the window containing this instance of n_ds.
Access Public
Syntax instancename.of_GetParentWindow ( window )
Argument Description
instancename Instance name of n_ds
window Window variable into which the function places a reference to the
parent window (passed by reference)

Return value Integer. Returns 1 if the function succeeds and -1 if there is no parent window.
Usage Internal.
Examples This example is from the pfc_PrintDlg event:
...
f_setplatform (lnv_platform, true)
this.of_GetParentWindow(lw_parent)
ll_rc = lnv_platform.of_PrintDlg(astr_printdlg, &
lw_parent)
...

of_IsUpdateable
Description Reports whether the DataStore is updatable.
Access Public
Syntax instancename.of_IsUpdateable ( )
Argument Description
instancename Instance name of n_ds

Return value Boolean. Returns TRUE if the DataStore is updatable and FALSE if it is not.
Examples This example is from the pfc_UpdatesPending event:
...
if not of_IsUpdateable() then
return 0
end if
...

of_MessageBox
Description Displays a MessageBox.

518
 Chapter 8 Standard Class User Objects

Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of n_ds
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of CommandButtons
you want to display at the bottom of the message box. The buttons
are numbered in the order listed in the enumerated data type. Values
are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in DataStore objects.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’ds_dberror’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

519
n_ds

of_PostUpdate
Description Calls the pfc_PostUpdate event, which clears update flags and allows you to
code additional post-update processing.
Access Public
Syntax instancename.of_PostUpdate ( )
Argument Description
instancename Instance name of n_ds

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize post-update processing,
extend the pfc_PostUpdate event.
Examples This example is from the n_cst_luw of_PostUpdate function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_PostUpdate()
...

of_Retrieve
Description Calls the pfc_Retrieve event.
Access Public
Syntax instancename.of_Retrieve ( )
Argument Description
instancename Instance name of n_ds

Return value Integer. Returns the number of rows retrieved if the function succeeds and -1 if
an error occurs.
Usage Call this function to perform DataStore retrieves. You must also code retrieve
logic in the pfc_Retrieve event.
Examples This example calls the of_Retrieve function:
ids_data.of_Retrieve()

of_SetAppend
Description Specifies whether DataStore retrieves append to the end of the DataStore.

520
 Chapter 8 Standard Class User Objects

Access Public
Syntax instancename.of_SetAppend ( boolean )
Argument Description
instancename Instance name of n_ds
boolean Boolean specifying whether DataStore retrieves append to the end
of existing rows (TRUE) or reset the DataStore before the retrieve
(FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetAppend function:
Integer li_return

li_return = ids_datasource.of_SetAppend(FALSE)

of_SetBase
Description Enables or disables n_cst_dssrv, which provides basic DataStore services.
Access Public
Syntax instancename.of_SetBase ( boolean )
Argument Description
instancename Instance name of n_ds
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
an instance of the n_cst_dssrv object

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to create or destroy an instance of n_cst_dssrv.
Examples This example calls the of_SetBase function:
Integer li_return

li_return = ids_datastore.of_SetBase(TRUE)
IF li_return = -1 THEN
MessageBox("DataStore", "Error with of_SetBase")
END IF

of_SetMultiTable
Description Enables or disables n_cst_dssrv_multitable, which provides multitable update
services.

521
n_ds

Access Public
Syntax instancename.of_SetMultiTable ( boolean )
Argument Description
instancename Instance name of n_ds
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the multitable update service

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dssrv_multitable.
Examples This example calls the of_SetMultiTable function:
ids_data.of_SetMultiTable(TRUE)

of_SetParentWindow
Description Sets a reference to the parent window.
Access Public
Syntax instancename.of_SetParentWindow ( window )
Argument Description
instancename Instance name of n_ds
window Window variable containing the parent window

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Some n_ds print functionality requires a reference to a parent window.
Examples This example calls the of_SetParentWindow function in a window Open event:
ids_data = CREATE n_ds
ids_data.DataObject = "d_empall"
ids_data.of_SetTransObject(SQLCA)
ids_data.of_SetParentWindow(this)
...

of_SetPrintPreview
Description Enables or disables n_cst_dwsrv_printpreview, which provides the print
preview service.
Access Public
Syntax instancename.of_SetPrintPreview ( boolean )

522
 Chapter 8 Standard Class User Objects

Argument Description
instancename Instance name of n_ds
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the print preview service

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_printpreview.
Examples This example calls the of_SetPrintPreview function:
ids_data.of_SetPrintPreview(TRUE)

of_SetReport
Description Enables or disables n_cst_dwsrv_report, which provides the reporting service.
Access Public
Syntax instancename.of_SetReport ( boolean )
Argument Description
instancename Instance name of n_ds
boolean Boolean specifying whether to enable (TRUE) or disable (FALSE)
the reporting service

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Use this function to create or destroy an instance of n_cst_dwsrv_report.
Examples This example calls the of_SetReport function:
ids_data.of_SetReport(TRUE)

of_SetTransObject
Description Sets the Transaction object for the DataStore.
Access Public
Syntax instancename.of_SetTransObject ( transaction )
Argument Description
instancename Instance name of n_ds
transaction N_tr variable specifying the Transaction object to use for the
DataStore

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.

523
n_ds

Examples This example calls the of_SetTransObject function (it assumes you have
associated n_tr with SQLCA in the Application painter):
Integer li_return

li_return = ids_datastore.of_SetTransObject(SQLCA)
IF li_return = -1 THEN
MessageBox("DataStore", &
"Error with of_SetTransObject")
END IF

of_SetUpdateable
Description Specifies whether the DataStore is updatable.
Access Public
Syntax instancename.of_SetUpdateable ( boolean )
Argument Description
instancename Instance name of n_ds
boolean Boolean indicating whether the DataStore is updatable (TRUE) or
not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to disable default save processing for DataStores that are not
updatable.
Examples This example calls the of_SetUpdateable function:
ids_data.of_SetUpdateable(FALSE)

of_SetUpdateRequestor
Description Creates a reference to the object requesting an update within a logical unit of
work.
Access Public
Syntax instancename.of_SetUpdateRequestor ( requestor )
Argument Description
instancename Instance name of n_ds
requestor PowerObject containing the object requesting the update

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.

524
 Chapter 8 Standard Class User Objects

Examples This example is from the of_Update function:

...
If this.of_SetUpdateRequestor(apo_requestor) <0 Then
Return -1
END IF
li_rc = this.of_Update(ab_accepttext, ab_resetflag)
this.of_SetUpdateRequestor(lpo_notvalid)
...

of_Update
Updates the DataStore. There are two syntaxes:
To Use
Update data, optionally controlling update type Syntax 1
Update data passing the requestor object Syntax 2

Syntax 1 Update data, optionally controlling update type

Description Updates rows in the DataStore. With this syntax, you can optionally control the
update types:
Insert
Update
Delete
Access Public
Syntax instancename.of_Update ( accepttext, resetflags {, insert, update, delete } )
Argument Description
instancename Instance name of n_ds
accepttext Boolean indicating whether the DataStore should automatically
perform an AcceptText before performing the update:
TRUE—Perform AcceptText (default)
FALSE—Do not perform AcceptText
resetflags Boolean indicating whether instancename should automatically
reset the update flags:
TRUE—Reset the flags (default)
FALSE—Do not reset the flags
insert Boolean indicating whether to insert rows:
(optional) TRUE—Insert rows (default)
FALSE—Do not insert rows

525
n_ds

Argument Description
update Boolean indicating whether to modify changed rows:
(optional) TRUE—Modify rows (default)
FALSE—Do not modify rows
delete Boolean indicating whether to delete rows:
(optional) TRUE—Delete rows (default)
FALSE—Do not delete rows

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update processing, extend
the pfc_Update event.
For more information on update flags, see the Update function in the
PowerScript Reference.
Examples This example calls the of_Update function:
Integer li_return

li_return = ids_data.of_Update(TRUE, TRUE)

Syntax 2 Update data passing the requestor object

Description Updates rows in the DataStore, passing a reference to the requestor object.
Access Public
Syntax instancename.of_Update ( accepttext, resetflags, requestor )
Argument Description
instancename Instance name of n_ds
accepttext Boolean indicating whether the DataStore should automatically
perform an AcceptText before performing the update:
TRUE—Perform AcceptText (default)
FALSE—Do not perform AcceptText
resetflags Boolean indicating whether instancename should automatically
reset the update flags:
TRUE—Reset the flags (default)
FALSE—Do not reset the flags
requestor PowerObject containing the requestor object

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Internal.

526
 Chapter 8 Standard Class User Objects

Examples This example is from the n_cst_luw of_Update function:

...
If lb_defined Then
li_rc = lpo_tocheck.Function Dynamic of_Update &
(ab_accepttext, ab_resetflag, &
lpo_updaterequestor)
If li_rc < 0 Then Return -1
Continue
End If
...

of_UpdatePrep
Description Calls the pfc_UpdatePrep event, which allows you to code additional update
preparation logic.
Access Public
Syntax instancename.of_UpdatePrep ( )
Argument Description
instancename Instance name of n_ds

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize update preparation
processing, extend the pfc_UpdatePrep event.
Examples This example is from the n_cst_luw of_UpdatePrep function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_UpdatePrep ()
If li_rc < 0 Then Return -1
Continue
End If
...

of_UpdatesPending
Description Determines if there are updates pending in the DataStore.
Access Public
Syntax instancename.of_UpdatesPending ( )

527
n_ds

Argument Description
instancename Instance name of n_ds

Return value Integer. Returns values as follows:

• 1 Updates are pending
• 0 No updates pending
• -1 An error occurred
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize pending updates
processing, extend the pfc_UpdatesPending event.
Examples This example calls the of_UpdatesPending function:
...
If lb_defined Then
la_rc = lpo_tocheck.Dynamic of_UpdatesPending ()
...

of_Validation
Description Performs validation on the DataStore.
Access Public
Syntax instancename.of_Validation ( )
Argument Description
instancename Instance name of n_ds

Return value Integer. Returns 1 if the function succeeds and -1 if a validation error occurs.
Usage N_cst_luw calls this function as part of the default save process. This function
is part of the self-updating object API. To customize validation processing,
extend the pfc_Validation event.
Examples This example calls the of_Validation function:
...
If lb_defined Then
li_rc = &
lpo_tocheck.Function Dynamic of_Validation()
...

528
 Chapter 8 Standard Class User Objects

n_dsa
Description DynamicStagingArea nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder
DynamicStagingArea object.
See also n_dda
n_err
n_msg
n_tr

529
n_err

n_err
Description Error nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEAPSRV.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder error object.
See also n_dda
n_dsa
n_msg
n_tr

Functions
N_err contains one precoded function:
of_MessageBox

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of n_err
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

530
 Chapter 8 Standard Class User Objects

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in Error objects.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’err_dberror’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

531
n_inet

n_inet
Description Inet nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder Inet object.
See also n_cxinfo
n_cxk
n_ir
n_srv

532
 Chapter 8 Standard Class User Objects

n_ir
Description InternetResult nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder InternetResult
object.
See also n_cxinfo
n_cxk
n_inet
n_srv

533
n_ms

n_ms
Description MailSession nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder MailSession
object.
See also n_ds
n_err
n_msg
n_pl
n_tr

Functions
N_ms contains one precoded function:
of_MessageBox

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of n_ms
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

534
 Chapter 8 Standard Class User Objects

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in MailSession objects.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’ms_dberror’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

535
n_msg

n_msg
Description Message nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder Message
object.
N_msg includes functions that provide enhanced behavior when passing
numeric, string, or PowerObject values through the Message object. Call these
functions to set and get values instead of accessing DoubleParm, StringParm,
and PowerObjectParm directly.
See also n_ds
n_err
n_ms
n_pl
n_tr

Instance variables
N_msg includes instance variables:
Instance
variable Description Data type Access Usage
idbl_parm Contains passed Double Protected Access with of_GetDoubleParm
numeric values and of_SetDoubleParm
ipo_parm Contains passed objects PowerObject Protected Access with
of_GetPowerObjectParm and
of_SetPowerObjectParm
is_parm Contains passed string String Protected Access with of_GetStringParm and
values of_SetStringParm

536
 Chapter 8 Standard Class User Objects

Functions
N_msg includes precoded functions:
of_CopyTo of_MessageBox
of_GetDoubleParm of_SetDoubleParm
of_GetPowerObjectParm of_SetPowerObjectParm
of_GetStringParm of_SetStringParm

of_CopyTo
Description Copies the contents of the Message object to the specified Message object.
Access Public
Syntax instancename.of_CopyTo ( targetmsg )
Argument Description
instancename Instance name of n_msg
targetmsg N_msg-based Message object to which the function copies values

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to copy contents from one Message object to another. Call
this function instead of simply assigning one object to another (which copies a
reference, not the values).
Examples This example calls the of_CopyTo function (it assumes an imsg_back instance
variable):
Integer li_return

li_return = Message.of_CopyTo(imsg_back)
...

of_GetDoubleParm
Description Retrieves the numeric value stored in the idbl_parm instance variable.
Access Public
Syntax instancename.of_GetDoubleParm ( )
Argument Description
instancename Instance name of n_msg

Return value Double. Returns the idbl_parm instance variable.

537
n_msg

Usage Use this function in combination with of_SetDoubleParm instead of accessing

Message.DoubleParm directly.
Examples This example calls the of_GetDoubleParm function:
Double ldbl_emp_id

ldbl_emp_id = Message.of_GetDoubleParm()
...

of_GetPowerObjectParm
Description Retrieves the PowerObject value stored in the ipo_parm instance variable.
Access Public
Syntax instancename.of_GetPowerObjectParm ( )
Argument Description
instancename Instance name of n_msg

Return value PowerObject. Returns the ipo_parm instance variable.

Usage Use this function in combination with of_SetPowerObjectParm instead of
accessing Message.PowerObjectParm directly.
You can use this function to access any object that descends from PowerObject.
Examples This example calls the of_GetPowerObjectParm function:
PowerObject lpo_obj
n_tr ltr_trans

lpo_obj = Message.of_GetPowerObjectParm()
IF TypeOf.lpo_obj = n_tr THEN
ltr_trans = lpo_obj
dw_1.of_SetTransObject(ltr_trans)
...

of_GetStringParm
Description Retrieves the string value stored in the is_parm instance variable.
Access Public
Syntax instancename.of_GetStringParm ( )
Argument Description
instancename Instance name of n_msg

538
 Chapter 8 Standard Class User Objects

Return value String. Returns the is_parm instance variable.

Usage Use this function in combination with of_SetStringParm instead of accessing
Message.StringParm directly.
Examples This example calls the of_GetStringParm function:
String ls_empname

ls_empname = Message.of_GetStringParm()
...

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of n_msg
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

539
n_msg

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in Message objects.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’msg_dberror’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

of_SetDoubleParm
Description Sets the numeric value stored in the idbl_parm instance variable.
Access Public
Syntax instancename.of_SetDoubleParm ( parm )
Argument Description
instancename Instance name of n_msg
parm Double specifying the value to be saved

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Use this function in combination with of_GetDoubleParm instead of accessing
Message.DoubleParm directly.
Examples This example calls the of_SetDoubleParm function:
Double ldbl_emp_id

ldbl_emp_id = 599
Message.of_SetDoubleParm(ldbl_emp_id)
...

of_SetPowerObjectParm
Description Sets the PowerObject value stored in the ipo_parm instance variable.
Access Public
Syntax instancename.of_SetPowerObjectParm ( parm )
Argument Description
instancename Instance name of n_msg
parm PowerObject containing the instance to be saved

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.

540
 Chapter 8 Standard Class User Objects

Usage Use this function in combination with of_GetPowerObjectParm instead of

accessing Message.PowerObjectParm directly.
You can use this function for any object that descends from PowerObject.
Examples This example calls the of_SetPowerObjectParm function:
PowerObject lpo_obj
n_tr ltr_trans

lpo_obj = n_tr
Message.of_SetPowerObjectParm(lpo_obj)
Open(w_deptinfo)
...

of_SetStringParm
Description Sets the string value stored in the is_parm instance variable.
Access Public
Syntax instancename.of_SetStringParm ( parm )
Argument Description
instancename Instance name of n_msg
parm String specifying the value to be saved

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Use this function in combination with of_GetStringParm instead of accessing
Message.StringParm directly.
Examples This example calls the of_SetStringParm function:
Message.of_SetStringParm("w_products")
of_SendMessage("pfc_Open")

541
n_oo

n_oo
Description OLEObject nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder OLEObject
object.
See also n_ostg
n_ostm

542
 Chapter 8 Standard Class User Objects

n_ostg
Description OLEStorage nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder OLEStorage
object.
See also n_oo
n_ostm

543
n_ostm

n_ostm
Description OLEStream nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder OLEStream
object.
See also n_oo
n_ostg

544
 Chapter 8 Standard Class User Objects

n_pl
Description Pipeline nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder pipeline object.
See also n_ds
n_err
n_ms
n_msg
n_tr

Functions
N_pl contains one precoded function:
of_MessageBox

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of n_pl
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text

545
n_pl

Argument Description
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in Pipeline objects.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’pl_dberror’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

546
 Chapter 8 Standard Class User Objects

n_srv
Description Service nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder Service object.
The Service object is used in implementing extensions to the PowerBuilder
context feature.
See also n_cxinfo
n_cxk
n_inet
n_ir

547
n_tmg

n_tmg
Description Timing nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships n_cst_tmgmultiple
n_cst_tmgsingle
Usage Use this nonvisual object instead of the standard PowerBuilder Timing object.
See also n_tr

Instance variables
N_tmg includes instance variables:
Instance variable Description Data type Access Usage
inv_multiple Reference variable for N_cst_tmgmultiple Public Call of_SetMultiple to
multiple notify service enable
inv_single Reference variable for N_cst_tmgsingle Public Call of_SetSingle to
single notify service enable

Functions
N_tmg includes precoded object functions:
of_SetMultiple
of_SetSingle

of_SetMultiple
Description Enables or disables n_cst_tmgmultiple, which provides the multiple notify
service.
Access Public
Syntax instancename.of_SetMultiple ( boolean )

548
 Chapter 8 Standard Class User Objects

Argument Description
instancename Instance name of n_tmg
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) an instance of the n_cst_tmgmultiple object

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage You cannot use both n_cst_tmgsingle and n_cst_tmgmultiple at the same time.
Examples This example calls the of_SetMultiple function:
Integer li_return

li_return = itmg_timer.of_SetMultiple(TRUE)
IF li_return = -1 THEN
MessageBox("Timer", "Error with of_SetMultiple")
END IF

of_SetSingle
Description Enables or disables n_cst_tmgsingle, which provides the single notify service.
Access Public
Syntax instancename.of_SetSingle ( boolean )
Argument Description
instancename Instance name of n_tmg
boolean Boolean specifying whether to enable (TRUE) or disable
(FALSE) an instance of the n_cst_tmgsingle object

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage You cannot use both n_cst_tmgsingle and n_cst_tmgmultiple at the same time.
Examples This example calls the of_SetSingle function:
Integer li_return

li_return = itmg_timer.of_SetSingle(TRUE)
IF li_return = -1 THEN
MessageBox("Timer", "Error with of_SetSingle")
END IF

549
n_tr

n_tr
Description Transaction object for use with all PFC applications. You can use this object as
is, or create DBMS- or application-specific descendants that include
customized or extended functionality.
N_tr includes integration with the SQL Spy debugging service.
For more information on using SQL Spy, see the PFC User’s Guide.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Object relationships n_cst_trregistration
Usage Use n_tr functions instead of native SQL transaction management statements.
For example, to connect to the database, use of_Connect instead of the
CONNECT statement.
To register an n_tr-based Transaction object with the transaction registration
service, call the n_cst_trregistration of_Register function.
To use n_tr:
1 If the Transaction object is not SQLCA, create it:
// Assumes an itr_security instance variable
itr_security = CREATE n_tr
2 (Optional) If you are using the transaction registration service:
• Register all Transaction objects:
gnv_app.inv_trregistration.of_Register(SQLCA)
// Assumes an itr_security instance variable

550
 Chapter 8 Standard Class User Objects

gnv_app.inv_trregistration.of_Register &
(itr_security)
• Establish a transaction name for use with the transaction registration
service:
// Assumes an itr_security instance variable
SQLCA.of_SetName("SQLCA")
itr_security.of_SetName("Security")
3 Initialize the ib_autorollback instance variable, which specifies what to do
if the application closes (or the object is otherwise destroyed) while the
transaction is still connected:
SQLCA.of_SetAutoRollback(TRUE)
itr_security.of_SetAutoRollback(FALSE)
4 Call n_tr functions as needed.
See also n_cst_trregistration

Instance variables
N_tr includes instance variables:
Instance
variable Description Data type Access Usage
ib_autorollback Specifies whether the Boolean Protected The Destructor event uses this event
Destructor event issues to determine whether to call
a COMMIT or a of_Commit or of_Rollback:
ROLLBACK if the • TRUE — Call of_Rollback
transaction is still
• FALSE (default) — Call
connected
of_Commit
Set with of_SetAutoRollback. This
controls how n_tr handles
transactions if the application closes
(or the object is otherwise
destroyed) while the transaction is
still connected
ib_trace Specifies whether trace Boolean Protected Call of_GetTrace to access this
is enabled value (default is FALSE)

551
n_tr

Instance
variable Description Data type Access Usage
is_name A name used to identify String Protected You can reuse transactions between
the transaction windows by passing this value
(using OpenWithParm) when
opening a new window. The new
window can use the passed value
with the n_cst_trregistration
of_GetByName function to access
the Transaction object
Call of_GetName and of_SetName
to access this value

Events
N_tr includes a precoded event:
Destructor

Destructor
Description If the instance is still connected to a database, this event commits or rolls back
the transaction, depending on the ib_autorollback instance variable. It then
disconnects the transaction.
Usage This event’s functionality is meant to ensure efficient use of system resources.
However, it’s best to commit, rollback, and disconnect explicitly using this
object’s of_Commit, of_Rollback, and of_Disconnect functions.

Functions
N_tr includes precoded object functions:
of_Begin of_GetTrace
of_Commit of_Init
of_Connect of_IsConnected
of_CopyTo of_MessageBox
of_Disconnect of_Rollback
of_DistinctValues of_SetAutoRollback
of_End of_SetLogidAndPassword

552
 Chapter 8 Standard Class User Objects

of_Execute of_SetName
of_GetAutoRollback of_SetTrace
of_GetName of_SetUser
of_GetSqlState of_SetUserIdAndPassword

of_Begin
Description Empty function into which you can code DBMS-specific BEGIN
TRANSACTION statements in n_tr descendants.
Access Public
Syntax instancename.of_Begin ( )
Argument Description
instancename Instance name of n_tr

Return value Long. Always returns -1. Add DBMS-specific returns values in your n_tr
descendant.
Usage Call this function to begin a database transaction.
You should connect to the database before issuing this function. Use
of_Connect to connect to the database.

of_Commit
Description Issues a COMMIT statement.
Access Public
Syntax instancename.of_Commit ( )
Argument Description
instancename Instance name of n_tr

Return value Long. Returns the SQLCODE value from the COMMIT statement.
Usage Call this function instead of the COMMIT statement to make any changes to
the database permanent and end a logical unit of work.
Examples This example calls the of_Commit function:
IF dw_sheet.Update( ) = -1 THEN
itr_trans.of_Rollback( )
MessageBox("Update", "Update failed")
ELSE
itr_trans.of_Commit( )

553
n_tr

gnv_app.of_GetFrame( ).SetMicroHelp &

("Update succeeded")
END IF

of_Connect
Description Connects to the database.
Access Public
Syntax instancename.of_Connect ( )
Argument Description
instancename Instance name of n_tr

Return value Long. Returns the SQLCODE value from the CONNECT statement.
Usage Call this function instead of the CONNECT statement to connect the
transaction to the database.
You must initialize the Transaction object before calling this function. The
fields initialized vary, depending on your DBMS. You can call the of_Init
function to initialize the Transaction object.
Examples This example initializes itr_security fields and connects to the database:
String ls_dbms, ls_database, ls_logid, ls_logpass
String ls_servername
Long ll_return

itr_security.DBMS = "Syb"
itr_security.Database = "agora"
itr_security.LogID = "williamk"
itr_security.LogPass = "billpass"
itr_security.ServerName = "MUSTANG"

ll_return = itr_security.of_Connect()
IF ll_return <> 0 THEN
MessageBox("Connect", "Connect error")
END IF

of_CopyTo
Description Copies the contents of the Transaction object to the specified Transaction
object.
Access Public

554
 Chapter 8 Standard Class User Objects

Syntax instancename.of_CopyTo ( targettrans )

Argument Description
instancename Instance name of n_tr
targettrans N_tr-based Transaction object to which the function copies values

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to copy contents from one Transaction object to another. Call
this function instead of simply assigning one object to another (which copies a
reference, not the values).
Examples This example calls the of_CopyTo function (it assumes an itr_back instance
variable):
Integer li_return

li_return = SQLCA.of_CopyTo(itr_back)
...

of_Disconnect
Description Disconnects from the database.
Access Public
Syntax instancename.of_Disconnect ( )
Argument Description
instancename Instance name of n_tr

Return value Long. Returns the SQLCODE value from the DISCONNECT statement.
Usage Call this function instead of the DISCONNECT statement to disconnect the
transaction from the database.
Be sure to check the return value to ensure that the function succeeded.
Examples This example disconnects from the database:
Long ll_return

ll_return = itr_security.of_Disconnect()
IF ll_return <> 0 THEN
MessageBox("Disconnect", "Disconnect error")
END IF

555
n_tr

of_DistinctValues
Description Retrieves distinct values for the specified database column.
Access Public
Syntax instancename.of_DistinctValues ( table, column, values )
Argument Description
instancename Instance name of n_tr
table String specifying the database table
column String specifying the column for which the function returns
distinct values
values Unbounded string array into which the function places distinct
values for column

Return value Long. Returns the number of elements in the values array.
Examples This calls the of_DistinctValues function:
Long ll_return
String ls_values[ ]

ll_return = SQLCA.of_DistinctValues &

("employee", "dept_id", ls_values)
...

of_End
Description Empty function into which you can code DBMS-specific END
TRANSACTION statements in n_tr descendants.
Access Public
Syntax instancename.of_End ( )
Argument Description
instancename Instance name of n_tr

Return value Long. Always returns -1. Add DBMS-specific returns values in your n_tr
descendant.
Usage Call this function to end a database transaction.

of_Execute
Description Executes a specified SQL statement.
Access Public

556
 Chapter 8 Standard Class User Objects

Syntax instancename.of_Execute ( sqlstatement )

Argument Description
instancename Instance name of n_tr
sqlstatement String containing the SQL statement to execute

Return value Long. Returns the SQLCODE returned by the EXECUTE IMMEDIATE
statement. A value of -10 indicates that there is no database connection.
Examples This example calls the of_Execute function:
Long ll_return
String ls_sql

ls_sql = "DELETE from employee WHERE dept_id = 100"

ll_return = SQLCA.of_Execute(ls_sql)
...

of_GetAutoRollback
Description Reports whether autorollback is enabled.
Access Public
Syntax instancename.of_GetAutoRollback ( )
Argument Description
instancename Instance name of n_tr

Return value Boolean. Returns TRUE if autorollback is enabled and FALSE if it is not.
Examples This example calls the of_GetAutoRollback function:
IF SQLCA.of_GetAutoRollback() THEN
MessageBox("Transaction", &
"Autorollback is enabled")
ELSE
MessageBox("Transaction", &
"Autorollback is disabled")
END IF

of_GetName
Description Retrieves the transaction name, as specified by the of_SetName function.
Access Public
Syntax instancename.of_GetName ( )

557
n_tr

Argument Description
instancename Instance name of n_tr

Return value String. Returns the transaction name.

Usage N_cst_trregistration functions call this function to access the Transaction
object name.
Examples This example is from the n_cst_trregistration of_GetByName function:
...
FOR li_cnt = 1 to li_upperbound
IF istr_trans[li_cnt].b_used AND &
IsValid (istr_trans[li_cnt].tr_object) THEN
ls_name = &
istr_trans[li_cnt].tr_object.of_GetName()
IF ls_name = as_name THEN
atr_obj = istr_trans[li_cnt].tr_object
lb_found = TRUE
EXIT
END IF
END IF
NEXT
...

of_GetSqlState
Description Retrieves the SQL state string returned by the DBMS.
Access Public
Syntax instancename.of_GetSqlState ( )
Argument Description
instancename Instance name of n_tr

Return value String. Returns the SQL state string returned by the DBMS.
Examples This example calls the of_GetSqlState function:
String ls_sqlstate

ls_sqlstate = SQLCA.of_GetSqlState()
MessageBox("SQL State", &
"SQL state is: " + ls_sqlstate)

558
 Chapter 8 Standard Class User Objects

of_GetTrace
Description Reports whether the PowerBuilder DBMS trace is enabled.
Access Public
Syntax instancename.of_GetTrace ( )
Argument Description
instancename Instance name of n_tr

Return value Boolean. Returns TRUE if trace is enabled and FALSE if it is not.
Examples This example calls the of_GetTrace function:
IF SQLCA.of_GetTrace() THEN
MessageBox("Transaction", "Trace is enabled")
ELSE
MessageBox("Transaction", "Trace is disabled")
END IF

of_Init
Description Initializes the n_tr-based Transaction object with the passed values.
Access Public
Syntax instancename.of_Init ( fileorkey, section )
Argument Description
instancename Instance name of n_tr
fileorkey String specifying the name of the ini file or registry key containing
connection information. If you specify an INI file, you must also
specify section
section String specifying the INI file section containing connection
information. If fileorkey specifies a registry key, you cannot
specify this value

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to initialize n_tr before connecting to the database. The INI-
file section or registry key must include the following keywords (with DBMS-
specific values as appropriate):
DBMS
Database
LogID
LogPass
ServerName

559
n_tr

UserID
DatabasePassword
Lock
DbParm
Examples This example calls the of_Init function:
String ls_file, ls_section
Long ll_return

ls_file = "c:\pbapp\pbapp.ini"
ls_section = "securityDB"

itr_security.of_Init &
(ls_file, ls_section)
ll_return = itr_security.of_Connect()
IF ll_return <> 0 THEN
MessageBox("Connect", "Connect error")
END IF

of_IsConnected
Description Determines whether the n_tr instance is connected to a database.
Access Public
Syntax instancename.of_IsConnected ( )
Argument Description
instancename Instance name of n_tr

Return value Boolean. Returns TRUE if the n_tr instance is connected to a database and
FALSE if it is not.
Examples This example calls the of_IsConnected function:
Long ll_return

IF NOT itr_security.of_IsConnected() THEN

ll_return = itr_security.of_Connect( )
IF ll_return <> 0 THEN
MessageBox("Connect", "Connect error")
END IF
END IF

of_MessageBox
Description Displays a MessageBox.

560
 Chapter 8 Standard Class User Objects

Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of n_tr
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in Transaction objects.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’tr_dberror’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

of_Rollback
Description Rolls back the database transaction.

561
n_tr

Access Public
Syntax instancename.of_Rollback ( )
Argument Description
instancename Instance name of n_tr

Return value Long. Returns 0 if the function succeeds, -10 if the transaction is not connected
and any other nonzero value if an error occurs.
Usage Call this function instead of the ROLLBACK statement to reverse all
uncommitted changes.
Examples This example calls the of_Rollback function:
IF dw_sheet.Update() = -1 THEN
itr_trans.of_Rollback()
MessageBox("Update", "Update failed")
ELSE
itr_trans.of_Commit()
gnv_app.of_GetFrame().SetMicroHelp &
("Update succeeded")
END IF

of_SetAutoRollback
Description Controls whether autorollback is enabled.
If autorollback is enabled, the n_tr Destructor event issues a ROLLBACK for
a connected transaction. If autorollback is disabled, the n_tr Destructor event
issues a COMMIT.
Access Public
Syntax instancename.of_SetAutoRollback ( boolean )
Argument Description
instancename Instance name of n_tr
boolean Boolean indicating whether autorollback is enabled (TRUE) or
not (FALSE)

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Examples This example calls the of_SetAutoRollback function:
SQLCA.of_SetAutoRollback(TRUE)

562
 Chapter 8 Standard Class User Objects

of_SetLogidAndPassword
Description Sets the property values of the Transaction object for LogID and LogPass.
Access Public
Syntax instancename.of_SetLogidAndPassword ( loginid , logpassword )
Argument Description
instancename Instance name of n_tr
loginid String specifying the name of the login ID
logpassword String specifying the name of the login password

Return value None

See also of_Init
of_SetUser
of_SetUserIdAndPassword

of_SetName
Description Specifies the transaction name, which is used by the transaction registration
service.
Access Public
Syntax instancename.of_SetName ( name )
Argument Description
instancename Instance name of n_tr
name String specifying a name for the transaction

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Call this function to specify a transaction name when you are using the
transaction registration service.
Examples This example calls the of_SetName function:
SQLCA.of_SetName("SQLCA")
itr_security.of_SetName("Security")

of_SetTrace
Description Specifies whether the PowerBuilder DBMS trace is enabled.
Access Public
Syntax instancename.of_SetTrace ( boolean )

563
n_tr

Argument Description
instancename Instance name of n_tr
boolean Boolean specifying whether trace is enabled (TRUE) or not
(FALSE)

Return value Integer. Returns 1 if the function succeeds, 0 if trace is already in the specified
state, and -1 if an error occurs.
Examples This example calls the of_SetTrace function to enable trace:
SQLCA.of_SetTrace(TRUE)

of_SetUser
Description Specifies the DBMS user ID and password (DBPass).
Access Public
Syntax instancename.of_SetUser ( userid, password )
Argument Description
instancename Instance name of n_tr
userid String specifying the user ID (Transaction object UserID
property)
password String specifying the password (Transaction object DBPass
property)

Return value None

Usage Use this function for ODBC database connections. For native connections, use
of_SetLogidAndPassword or of_SetUserIdAndPassword, depending on the
DBMS.
Examples This example, which is from an n_cst_appmanager pfc_Logon event, calls the
of_SetUser function:
SQLCA.of_SetUser(as_userid, as_password)
IF SQLCA.of_Connect() >= 0 THEN
Return 1
ELSE
MessageBox (iapp_object.DisplayName, &
"Connect failed")
Return -1
END IF
See also of_SetLogidAndPassword
of_SetUserIdAndPassword

564
 Chapter 8 Standard Class User Objects

of_SetUserIdAndPassword
Description Sets the property values of the Transaction object for UserID and DBPass.
Access Public
Syntax instancename.of_SetUserIDAndPassword ( userid , password )
Argument Description
instancename Instance name of n_tr
userid String specifying the name of the user’s login ID
password String specifying the name of the user’s login password

Return value None

See also of_Init
of_SetLogidAndPassword
of_SetUser

565
n_trp

n_trp
Description Transport nonvisual user object ancestor.
Ancestry

Library PFCMAIN.PBL
PFEMAIN.PBL
Usage Use this nonvisual object instead of the standard PowerBuilder Transport
object.
See also n_cn

Functions
N_trp contains one precoded function:
of_MessageBox

of_MessageBox
Description Displays a MessageBox.
Access Protected
Syntax instancename.of_MessageBox ( id, title, message, icon, button, default )
Argument Description
instancename Instance name of n_trp
id String specifying an ID for the message
title String specifying the title of the MessageBox
message String specifying the message text
icon Icon enumerated data type indicating the icon you want to display
on the left side of the message box. Values are:
• Information!
• StopSign!
• Exclamation!
• Question!
• None!

566
 Chapter 8 Standard Class User Objects

Argument Description
button Button enumerated data type indicating the set of
CommandButtons you want to display at the bottom of the
message box. The buttons are numbered in the order listed in the
enumerated data type. Values are:
• OK!
• OKCancel!
• YesNo!
• YesNoCancel!
• RetryCancel!
• AbortRetryIgnore!
default Integer specifying the number of the button you want to be the
default button

Return value Integer. Returns 1 if the function succeeds and -1 if an error occurs.
Usage Override this function to control MessageBox behavior in Transport objects.
The id argument is not used in the default implementation.
Examples This example calls the of_MessageBox function:
of_Messagebox(’trp_dberror’,’Save’, &
as_error, StopSign!, Ok!, 1)
...

567
n_trp

568
Index

A w_master 21
CloseQuery event 21
Activate event
code examples 8
w_frame 12
color service 619
w_master 21
ColumnClick event 224
w_sheet 57
CommandButton 128
application INI file
Commit 553
of_GetAppIniFile 584
Connect 554
of_SetAppIniFile 591
Constructor
application manager 572
n_cst_mru 1137
application services
Constructor event
n_cst_apppreference 601
n_cst_appmanager 576
n_cst_dwcache 668
n_cst_debug 653
n_cst_error 950
n_cst_dwsrv_report 843
n_cst_security 1206
n_cst_filesrvwin32 1006
n_cst_trregistration 1285
n_cst_inifile 1026
n_cst_luw 1053
n_cst_lvsrv_datasource 1075
B n_cst_platformwin32 1179
n_cst_tmgmultiple 1249
BeginDrag event 338 n_cst_tvsrv_levelsource 1306
binary number service 1164 n_cst_winsrv_sheetmanager 1383
ButtonClicked event n_cst_winsrv_statusbar 1393
u_calculator 399 u_calculator 399
u_calendar 424 u_calendar 424
u_progressbar 460
u_st_splitbar 486
ContextInformation object 504
C ContextKeyword object 505
calculator 396 ContextMenu event
calendar 419 u_ddlb 136
CbnEditChange event u_ddplb 143
u_cbx 135 u_em 196
u_ddplb 142 u_lvs 224
CheckBox 131 u_mle 254
Clicked event u_oc 260
u_calendar 424 u_sle 308
u_dw 153 conversion service 621
Close event
w_frame 12

Index-1
Index

D n_cst_linkedlistbase 1031
n_cst_luw 1075
data type conversion service 621
n_cst_tmgmultiple 1249
DataStore 507
n_cst_trregistration 1286
DataStore services
n_cst_tvsrv_levelsource 1306
n_cst_dssrv 664
n_ds 510
n_cst_dssrv_multitable 665
n_tr 552
n_cst_dssrv_printpreview 666
u_base 382
n_cst_dssrv_report 667
u_calculator 399
DataWindow caching service
u_calendar 424
main discussion 668
u_dw 154
of_SetDwCache 593
u_em 196
DataWindow control 148
u_lvs 224
DataWindow properties
u_rte 286
n_cst_dwsrv_property 826
u_tvs 338
of_SetDWProperty 656
Disconnect 555
DataWindow services
distributed computing
base object 682
pfc_ConnectionBegin 578
dropdown DataWindow search service 706
pfc_ConnectionEnd 579
filter service 717
DoubleClicked event 424
find service 728
DragDrop event 338
linkage service 744
dropdown calculator 396
multitable update service 806
dropdown calendar 419
n_cst_dwsrv_printpreview 817
dropdown DataWindows
query mode service 830
of_PopulateDDDW 701
reporting 841
of_RefreshDDDWs 701
required column 884
search service 706
resize service 891
Dropdown event 154
row manager 908
dropdown service 658
row selection 918
DropDownListBox 134
sort 934
DropDownPictureListBox 141
u_dw 148
DynamicDescriptionArea object 506
date/time service 633
DynamicStagingArea object 529
DBError event
n_ds 510
u_dw 154
debug service E
main discussion 651
e 1191
of_SetDebug 593
EditMask 195
Destructor
EndLabelEdit event
n_cst_mru 1137
u_lvs 224
Destructor event
u_tvs 338
n_cst_appmanager 577
Error object 530
n_cst_debug 653
error service
n_cst_dwcache 670
main discussion 950
n_cst_dwsrv_report 843
of_SetError 594
n_cst_error 954

Index-2
 Index

examples 8 u_vsb 372

u_vtb 375
Graph 204
GroupBox 203
F
f_SetFilesrv 78
f_SetPlatform 79
file service H
f_SetFilesrv 78 Help
n_cst_filesrv 978 accessing 7
FileExists event 286 of_GetHelpFile 586
filter service 717 of_SetHelpFile 595
find service 728 Hide event 13
frame menu 64 HorizontalProgressBar 207
HorizontalScrollBar 210
HorizontalTrackBar 213

G
GetFocus event
u_calculator 399 I
u_calendar 425 Inet object 532
u_cb 128 INI file
u_cbx 131 of_GetAppIniFile 584
u_ddlb 136 of_SetAppIniFile 591
u_ddplb 143 of_SetUserIniFile 598, 617, 1150
u_dw 154 INI file service 1025
u_em 197 InternetResult object 533, 548
u_gr 204 ItemChanged event 154
u_hpb 207 ItemError event 154
u_hsb 210 ItemExpanding event 339
u_htb 213 ItemFocusChanged event 155
u_lb 216
u_lvs 224
u_mle 254
u_oc 260 K
u_p 267 Key event
u_pb 270 u_calculator 399
u_phl 273 u_calendar 425
u_plb 276 KeyDown event
u_rb 280 u_lvs 225
u_rte 286 u_tvs 338
u_sle 308
u_st 313
u_sth 316
u_tv 338 L
u_vpb 369 LButtonDown event 155

Index-3
Index

LButtonUp event n_cst_dwsrv_multitable 806

u_dw 155
u_st_splitbar 486
linkage service 744
ListBox 216 N
ListView 220 n_base 570
ListView service n_cn 500
base 1067 n_cst_aboutattrib 82
data source 1073 n_cst_appmanager 572
sort 1114 n_cst_apppreference 601
logical unit of work service 1051 n_cst_baseattrib 83
logon n_cst_calculatorattrib 84
of_LogonDlg 590 n_cst_calendarattrib 85
pfc_Logon 580 n_cst_color 619
pfc_PreLogonDlg 582 n_cst_columnattrib 86
LoseFocus event n_cst_conversion 621
u_calculator 400 n_cst_datetime 633
u_calendar 425 n_cst_dberrorattrib 87
n_cst_debug
main discussion 651
n_cst_sqlspy 1218
M n_cst_dirattrib 88
m_dw 60 n_cst_dropdown 658
m_edit 62 n_cst_dssrv 664
m_frame 64 n_cst_dssrv_multitable 665
m_lvs 65 n_cst_dssrv_multitableattrib 89, 807
m_master 68 n_cst_dssrv_printpreview 666
m_oc 73 n_cst_dssrv_report 667
m_tvs 75 n_cst_dwcache 668
MailSession object 534 n_cst_dwcacheattrib 90, 669
master menu 68 n_cst_dwobjectattrib 91
master/detail processing 744 n_cst_dwpropertyattrib 92
menu service 1120 n_cst_dwsrv 682
Message object 536 n_cst_dwsrv_dropdownsearch 706
metaclass service 1126 n_cst_dwsrv_dropdownsearchattrib 93, 707
MicroHelp n_cst_dwsrv_filter 717
of_GetMicrohelp 587 n_cst_dwsrv_find 728
of_SetMicrohelp 596 n_cst_dwsrv_linkage 744
pfc_MicroHelp 13, 25, 57 n_cst_dwsrv_multitable 806
most recently used object service 1133 n_cst_dwsrv_multitableattrib 94, 807
MouseMove event 486 n_cst_dwsrv_printpreview 817
Move event 13, 21 n_cst_dwsrv_property 826
MultiLineEdit 253 n_cst_dwsrv_querymode 830
multitable update service n_cst_dwsrv_querymodeattrib 95, 831
n_cst_dssrv_multitable 665 n_cst_dwsrv_report 841
n_cst_dssrv_printpreview 666 n_cst_dwsrv_reqcolumn 884

Index-4
 Index

n_cst_dwsrv_resize 891 n_cst_sql 1215

n_cst_dwsrv_resizeattrib 96, 892 n_cst_sqlattrib 113
n_cst_dwsrv_rowmanager 908 n_cst_sqlspy 1218
n_cst_dwsrv_rowselection 918 n_cst_stack 1224
n_cst_dwsrv_sort 934 n_cst_string 1227
n_cst_error 950 n_cst_textstyleattrib 114
n_cst_errorattrib 97 n_cst_tmgmultiple 1247
n_cst_filesrv 978 n_cst_tmgregisterattrib 115
n_cst_filesrvwin32 1004 n_cst_tmgsingle 1257
n_cst_filterattrib 98 n_cst_toolbarattrib 116
n_cst_findattrib 99 n_cst_tree 1266
n_cst_infoattrib 100 n_cst_treenode 1279
n_cst_inifile 1025 n_cst_treenodecompare 1283
n_cst_itemattrib 101 n_cst_trregistration 1285
n_cst_linkageattrib 102 n_cst_trregistrationattrib 117, 1286
n_cst_linkedlistbase 1030 n_cst_tvattrib 118
n_cst_linkedlistnode 1038 n_cst_tvsrv 1294
n_cst_linkedlistnodecompare 1039 n_cst_tvsrv_levelsource 1303
n_cst_list 1042 n_cst_tvsrv_print 1358
n_cst_logonattrib 103 n_cst_tvsrvattrib 119
n_cst_luw 1051 n_cst_winsrv 1362
n_cst_lvsrv 1067 n_cst_winsrv_preference 1365
n_cst_lvsrv_datasource 1073 n_cst_winsrv_sheetmanager 1382
n_cst_lvsrv_sort 1114 n_cst_winsrv_sheetmanagerattrib 120, 1382
n_cst_lvsrvattrib 104 n_cst_winsrv_statusbar 1389
n_cst_menu 1120 n_cst_winsrv_statusbarattrib 121, 1390
n_cst_metaclass 1126 n_cst_zoomattrib 122
n_cst_mru 1133 n_cxinfo 504
n_cst_mruattrib 105 n_cxk 505
n_cst_nodebase 1155 n_dda 506
n_cst_nodecomparebase 1161 n_ds 507
n_cst_numerical 1164 n_dsa 529
n_cst_platform 1170 n_err 530
n_cst_platformwin32 1178 n_inet 532
n_cst_propertyattrib 106 n_ir 533
n_cst_queue 1187 n_ms 534
n_cst_resize 1190 n_msg 536
n_cst_resizeattrib 107, 1191 n_oo 542
n_cst_restorerowattrib 108 n_ostg 543
n_cst_returnattrib 109 n_ostm 544
n_cst_rtefind 1200 n_pl 545
n_cst_security 1206 n_srv 547
n_cst_selection 1210 n_tmg 548
n_cst_selectionattrib 110 n_cst_tmgmultiple 1247
n_cst_sortattrib 111 n_cst_tmgsingle 1257
n_cst_splashattrib 112 n_tr

Index-5
Index

main discussion 550 of_AssemblePath 980

n_cst_trregistration 1285 of_Balance 1270
n_trp 566 of_BalanceLeft 1270
naming conventions of_BalanceRight 1271
instance variables 2 of_BarIncrement 1398
objects 2 of_BarReset 1398
numerical service 1164 of_BarUpdateVisuals 1399
of_Begin 553
of_BeginTran 1054
of_Binary 1165
O of_BitwiseAnd 1165
of_About 584 of_BitwiseNot 1166
of_AcceptText of_BitwiseOr 1167
n_cst_dwsrv_linkage 757 of_BitwiseXor 1168
n_cst_luw 1053 of_Boolean 622
n_ds 516 of_BuildColumnNames 732
u_base 385 of_BuildComparison 684
u_dw 174 of_BuildExpression 685
u_lvs 235 of_BuildFilterAttrib 719
u_tab 323 of_BuildFindExpression 732
u_tvs 350 of_BuildSortAttrib 937
w_master 37 of_BuildTextModify 854
of_Add of_BuildTree 1359
n_cst_linkedlistbase 1031 of_Button 623
n_cst_list 1044 of_ButtonClicked 400
n_cst_tree 1268 of_ButtonUp 925
of_AddColumn 709 of_CalculateFileAttributes 980
of_AddCompute 844 of_CalculateMicrohelpHeight 1399
of_AddHead of_CanUndo
n_cst_linkedlistbase 1032 n_cst_lvsrv_datasource 1082
n_cst_list 1044 n_cst_tvsrv_levelsource 1314
of_AddItem u_lvs 236
n_cst_mru 1139 u_tvs 352
u_lvs 236 of_Center 1363
u_tvs 351 of_ChangeDirectory
of_AddLine 847 n_cst_filesrv 981
of_AddMenubarLine 1140 n_cst_filesrvwin32 1006
of_AddNode 1269 of_CheckRequired
of_AddPicture 850 n_cst_dwsrv_linkage 757
of_AddTail n_ds 516
n_cst_linkedlistbase 1032 u_dw 174
n_cst_list 1045 of_ClearLog 653
of_AddText 852 of_ClearUndo
of_AddToUpdate 808 n_cst_lvsrv_datasource 1083
of_ArrayToString 1228 n_cst_tvsrv_levelsource 1314
of_Assemble 1215 of_Commit 553

Index-6
 Index

of_Compare 1162 of_DeleteDetailRows 760

of_CompareAttrib of_DeleteItem 709
n_cst_dwsrv_find 733 n_cst_lvsrv_datasource 1085
n_cst_rtefind 1203 n_cst_tvsrv_levelsource 1317
of_ConfirmDelete of_DeleteRow 912
n_cst_dwsrv_rowmanager 911 of_DeleteRows 761
n_cst_lvsrv_datasource 1083 of_DeleteSelected 912
n_cst_tvsrv_levelsource 1315 of_DelNode 1272
of_ConfirmOnDelete 758 of_DelTree 982
n_cst_lvsrv_datasource 1084 of_Describe 686
n_cst_tvsrv_levelsource 1315 of_Destroy 1287
of_ConfirmOnRowChange 759 n_cst_linkedlistbase 1033
of_Connect 554 n_cst_tree 1273
of_ConvertFileDateTimeToPB of_DirAttribToDS 983
n_cst_filesrvwin32 1007 of_DirectoryExists
of_ConvertPBDateTimeToFile n_cst_filesrv 983
n_cst_filesrvwin32 1008 n_cst_filesrvwin32 1009
of_ConvertToRow 1084, 1316 of_DirList
of_CopyTo n_cst_filesrv 984
n_cst_nodebase 1156 n_cst_filesrvwin32 1010
n_cst_treenode 1280 of_DiscardChildren 1318
n_msg 537 of_Disconnect 555
n_tr 554 of_DistinctValues 556
of_Count of_DrawMonth 427
n_cst_linkedlistbase 1033 of_DropDown
n_cst_tree 1271 u_calculator 401
of_CountOccurrences 1228 u_calendar 428
of_Create 1272 of_DSToDirAttrib 984
of_CreateComposite 856 of_DWArguments 688
of_CreateDirectory of_DWItemStatus 624
n_cst_filesrv 982 of_EncodeKey
n_cst_filesrvwin32 1009 n_cst_lvsrv_datasource 1086
of_CreateDWObject 1400 n_cst_tvsrv_levelsource 1318
of_CreateLogText 955 of_End 556
of_CreateNotifyText 955 of_EndTran 1055
of_CreateUpdateSequence 759 of_EndTranError 1056
of_Date 623 of_Execute 556
of_DayOfWeek 634 of_FileCopy 985
of_Days 635 of_FileRead 986
of_DBError 1055 of_FileRename
of_Decimal 1168 n_cst_filesrv 988
of_DecodeKey n_cst_filesrvwin32 1011
n_cst_lvsrv_datasource 1085 of_FileWrite 988
n_cst_tvsrv_levelsource 1317 of_Filter 720, 1140
of_Delete 1026 of_FilterDetails 761
of_DeleteAll 911 of_Find 734

Index-7
Index

n_cst_list 1045 of_GetBarMinimum 1404

n_cst_tree 1274 of_GetBarMoveColor 487
of_FindFirstItemLevel 1295 of_GetBarPctComplete 1404
of_FindItem 1296 of_GetBarPosition 1405
of_FindMatchingEvent 1127 of_GetBarStep 1405
of_FindMatchingVariable 1127 of_GetBarTextColor 1406
of_FindMRUItem 1141 of_GetBarWidth 1406
of_FindNext 1068 of_GetBeep 956
of_FindRoot 762 of_GetBit 1169
of_FindSelected 1069 of_GetBorderType 1407
of_FindStartAndEndRows 735 of_GetByName 1288
of_FindWindow of_GetCloseStatus 38
n_cst_platform 1171 of_GetColumn 710
n_cst_platformwin32 1180 of_GetColumnDisplayName 690
of_FirstDayOfMonth 635 of_GetColumnDisplayNameStyle 690
of_FirstPage 818 of_GetColumnEditStatus 735
of_FormatData 1086 of_GetColumnHeader 938
of_GCommonDenominator 1249 of_GetColumnInfo
of_Get 1188 n_cst_lvsrv_datasource 1088
n_cst_linkedlistbase 1034 u_lvs 237
n_cst_tree 1275 of_GetColumnLabel 1091, 1323
of_GetAllToolbarIndex 1121 of_GetColumnNameSource 691
of_GetAltFilename of_GetComputerName
n_cst_filesrv 990 n_cst_platform 1172
n_cst_filesrvwin32 1012 n_cst_platformwin32 1180
of_GetAlwaysOnTop of_GetConfirmOnDelete 913
n_cst_debug 654 of_GetContinuousPages 293
n_cst_sqlspy 1219 of_GetCopyright 585
of_GetAncestorClasses 1128 of_GetCount
of_GetAppend 517 n_cst_dwcache 670
of_GetAppIniFile 584 n_cst_tmgsingle 1250, 1259
of_GetAppKey 585 n_cst_trregistration 1289
of_GetArgs 1319 of_GetCreationDate 990
of_GetArguments 763 of_GetCreationDateTime
of_GetAttributes n_cst_filesrv 991
n_cst_lvsrv_datasource 1087 n_cst_filesrvwin32 1013
of_GetAutoRollback 557 of_GetCreationTime 991
of_GetBackColor 461 of_GetCurrentDirectory
of_GetBalance 1281 n_cst_filesrv 992
of_GetBar 1401 n_cst_filesrvwin32 1014
of_GetBarAutoClear 1414 of_GetCurrentState 1384
of_GetBarColor 487 of_GetCurrentText 461
of_GetBarDisplayStyle 1401 of_GetCustomUpdate
of_GetBarFillColor 1402 n_cst_dwsrv_linkage 763
of_GetBarFillStyle 1403 n_cst_tvsrv_levelsource 1319
of_GetBarMaximum 1403 of_GetData 1157

Index-8
 Index

of_GetDataAny 1297 n_cst_filesrv 993

of_GetDataNumeric 1297 n_cst_filesrvwin32 1016
of_GetDataObject of_GetFileName 294
n_cst_lvsrv_datasource 1088 of_GetFileSize
n_cst_tvsrv_levelwsource 1320 n_cst_filesrv 994
of_GetDataRow 1089, 1321 n_cst_filesrvwin32 1017
of_GetDataSource 1090 of_GetFillColor 462
of_GetDataStore 1321 of_GetFillStyle 463
of_GetDataString 1298 of_GetFilter 721
of_GetDefaultBackColor 858 of_GetFrame 586
of_GetDefaultBorder 858 of_GetFreeMemory
of_GetDefaultCharset 859 n_cst_platform 1172
of_GetDefaultColor 860 n_cst_platformwin32 1181
of_GetDefaultFontFace 860 of_GetGapWidth 1408
of_GetDefaultFontSize 861 of_GetGDI 1408
of_GetDefaultHeaderSuffix 691 of_GetGDIThreshold 1409
of_GetDeleteStyle of_GetHandle 1323
n_cst_dwsrv_linkage 763 of_GetHeaderName 693
n_cst_tvsrv_levelsource 1322 of_GetHeight 694
of_GetDetails 764 of_GetHelpFile 586
of_GetDiskSpace of_GetHoliday 429
n_cst_filesrv 992 of_GetHolidayColor 429
n_cst_filesrvwin32 1014 of_GetHorizontalPointer 488
of_GetDisplayItem of_GetIgnoreFileExists 294
n_cst_dwsrv 692 of_GetInfo
n_cst_lvsrv 1070 n_cst_dwsrv 694
n_cst_tvsrv 1298 n_cst_dwsrv_dropdownsearch 710
of_GetDisplayStyle 462 n_cst_dwsrv_filter 721, 736
of_GetDisplayUnits n_cst_dwsrv_linkage 765
n_cst_dwsrv 692 n_cst_dwsrv_multitable 808
n_cst_lvsrv 1070 n_cst_dwsrv_printpreview 819
n_cst_tvsrv 1299 n_cst_dwsrv_querymode 833
of_GetDoubleParm 537 n_cst_dwsrv_report 861
of_GetDriveType n_cst_dwsrv_reqcolumn 885
n_cst_filesrv 993 n_cst_dwsrv_resize 894
n_cst_filesrvwin32 1015 n_cst_dwsrv_rowmanager 914
of_GetDWType 38 n_cst_dwsrv_rowselection 925
of_GetEnabled n_cst_dwsrv_sort 939
n_cst_dwsrv_printpreview 819 u_base 385
n_cst_dwsrv_querymode 832 u_calculator 402
of_GetExclude u_calendar 430
n_cst_dwsrv_filter 720 u_lvs 238
n_cst_dwsrv_sort 938 u_progressbar 463
n_cst_lvsrv_sort 1116 u_st_splitbar 488
of_GetExtremePoint 487 u_tab 324
of_GetFileAttributes u_tvs 352

Index-9
Index

w_master 39 of_GetMinObjectSize 489

of_GetInterval of_GetMRUItem 1142
n_cst_tmgmultiple 1250 of_GetName 557
n_cst_tmgsingle 1259 of_GetNext 1158
of_GetItem 695 of_GetNextLevel 353
of_GetItemAny 696 of_GetNotifyConnection 958
of_GetItemIndex 1090 of_GetNotifyPreTitle 958
of_GetKey 1157 of_GetNotifySeverity 959
of_GetKeyboard 927 of_GetNotifyWho 959
of_GetKeys 1027 of_GetObjectInformation 895
of_GetKeyValue 1229 of_GetObjects
of_GetLastAccessDate n_cst_dwsrv 697
n_cst_filesrv 994 n_cst_tvsrv_levelsource 1326
n_cst_filesrvwin32 1018 u_lvs 238
of_GetLastWriteDate 994 u_tvs 353
of_GetLastWriteDateTime of_GetOtherSaveObjects 766
n_cst_filesrv 995 of_GetPageInputField 295
n_cst_filesrvwin32 1019 of_GetParentPosition 659
of_GetLastWriteTime 995 of_GetParentWindow
of_GetLevel 1324 n_cst_dropdown 660
of_GetLevelAttributes 1325 n_ds 518, 522
of_GetLevelCount 1325 u_base 386
of_GetLineEnding 1028 u_cb 129
of_GetLogFile 956 u_cbx 132
of_GetLogFileStyle 957 u_ddlb 138
of_GetLogo 587 u_ddplb 145
of_GetLogSeverity 957 u_dw 175
of_GetLongFilename u_em 199
n_cst_filesrv 996 u_gr 205
n_cst_filesrvwin32 1019 u_hpb 208
of_GetMarkedDay 430 u_hsb 211
of_GetMarkedDayColor 431 u_htb 214
of_GetMaster 765 u_lb 217
of_GetMaximum 464 u_lvs 239
of_GetMDIFrame 1121 u_mle 256
of_GetMem 1410 u_oc 264
of_GetMemThreshold 1410 u_p 268
of_GetMenuItems 1368 u_pb 271
of_GetMenuReference 1122 u_phl 274
of_GetMessageText 464 u_plb 277
of_GetMethod u_rb 281
n_cst_lvsrv_datasource 1091 u_rte 295
n_cst_tvsrv_levelsource 1326 u_sle 311
of_GetMicrohelp 587 u_st 314
of_GetMinimum 465 u_sth 317
of_GetMinMaxPoints 1193 u_tab 324

Index-10
 Index

u_tvs 354 of_GetRegistered

u_vpb 370 n_cst_dwcache 671
u_vsb 373 n_cst_dwsrv_dropdownsearch 712
u_vtb 376 n_cst_dwsrv_linkage 767
of_GetPctComplete 465 n_cst_dwsrv_multitable 812
of_GetPhysicalMemory n_cst_dwsrv_reqcolumn 887
n_cst_platform 1173 n_cst_dwsrv_resize 897
n_cst_platformwin32 1181 n_cst_mru 1142
of_GetPictureColumn n_cst_tmgsingle 1260
n_cst_lvsrv_datasource 1092 n_cst_trregistration 1289
n_cst_tvsrv_levelsource 1328 u_calculator 403
of_GetPictureSize 862 u_calendar 433
of_GetPosition 466 of_GetRegisteredl
of_GetPowerObjectParm 538 n_cst_tmgmultiple 1251
of_GetPredefinedSource 960 of_GetRegisteredStyle
of_GetPredefinedSourceType 961 u_calculator 404
of_GetPrev 1158 u_calendar 433
of_GetPropertyInfo of_GetResetCriteria 835
n_cst_dwsrv 698 of_GetRestoreRow 915
n_cst_dwsrv_dropdownsearch 711 of_GetRetrieveArgs 1328
n_cst_dwsrv_filter 722, 737 of_GetRetrieveOnDisabled 835
n_cst_dwsrv_linkage 767 of_GetRoot 1275
n_cst_dwsrv_multitable 809 of_GetRow 239
n_cst_dwsrv_printpreview 820 of_GetRuler 820
n_cst_dwsrv_querymode 833 of_GetSaturdayColor 434
n_cst_dwsrv_report 863 of_GetSaveSound 768
n_cst_dwsrv_reqcolumn 886 of_GetSaveStatus 40
n_cst_dwsrv_resize 896 of_GetSections 1028
n_cst_dwsrv_rowmanager 914 of_GetSelected
n_cst_dwsrv_rowselection 926 u_lb 218
n_cst_dwsrv_sort 940 u_plb 278
u_calculator 402 of_GetSelectedPictureColumn 1329
u_calendar 431 of_GetSeparator 996
of_GetQueryCols 834 of_GetSheetCount 1385
of_GetRefreshRate 1411 of_GetSheets 1385
of_GetRegisterable of_GetSheetsByClass 1386
n_cst_dwsrv_dropdownsearch 712 of_GetSheetsByTitle 1387
n_cst_dwsrv_filter 723 of_GetSort 941
n_cst_dwsrv_multitable 810 of_GetSqlState 558
n_cst_dwsrv_reqcolumn 886 of_GetStartPageNumber 296
n_cst_dwsrv_resize 897 of_GetStatePictureColumn
n_cst_dwsrv_sort 940 n_cst_lvsrv_datasource 1093
u_calculator 403 n_cst_tvsrv_levelsource 1329
u_calendar 432 of_GetStep 466
of_GetRegisterableColumn 811 of_GetStringParm 538
of_GetRegisterableTable 811 of_GetStyle

Index-11
Index

n_cst_dwsrv_filter 723 n_cst_tvsrv_levelsource 1331

n_cst_dwsrv_linkage 769 of_GetUseColLinks 771
n_cst_dwsrv_rowselection 927 of_GetUseDisplay 942
n_cst_dwsrv_sort 942 of_GetUser
n_cst_error 961 n_cst_error 963
of_GetSundayColor 434 n_cst_winsrv_statusbar 1412
of_GetSystemDirectory of_GetUserID
n_cst_platform 1173 n_cst_appmanager 588
n_cst_platformwin32 1182 n_cst_platform 1174
of_GetSystemSetting 660 n_cst_platformwin32 1183
of_GetTextColor 467 of_GetUserIniFile 588, 1143
of_GetTextSize of_GetUserKey 589, 1143
n_cst_platform 1173 of_GetUserThreshold 1413
n_cst_platformwin32 1182 of_GetValue 771
of_GetTextSizePos 863 of_GetVersion 589
of_GetTextStyle 296 of_GetVerticalPointer 489
of_GetTimeOut 962 of_GetVisibleOnly
of_GetTimer 1411 n_cst_dwsrv_filter 724
of_GetTimerInterval 1412 n_cst_dwsrv_sort 943
of_GetToken 1230 of_GetWidth 698
of_GetToolbarItemOrder 1368 of_GetWindow 1371
of_GetToolbarItemSpace 1369 of_GetWindowsDirectory
of_GetToolbarItemVisible 1369 n_cst_platform 1174
of_GetToolbars 1370 n_cst_platformwin32 1184
of_GetToolbarTitles 1370 of_GetWindowText
of_GetTrace 559 n_cst_platform 1175
of_GetTransObject n_cst_platformwin32 1184
n_cst_lvsrv_datasource 1093 of_GetXPosColumn 1094
n_cst_tvsrv_levelsource 1330 of_GetYPosColumn 1094
of_GetType 1056 of_GetZoom 821
of_GetTypeToProcess 1057 of_GlobalReplace 1231
of_GetUnattended 962 of_Gregorian 636
of_GetUndoLevels 865 of_Hours 637
of_GetUpdateable 176 of_Icon 625
of_GetUpdateBottomUp 769 of_IncludeComputes
of_GetUpdateObjects n_cst_dwsrv_find 737
u_base 386 of_IncludeFile
u_tab 325 n_cst_filesrv 997
w_master 40 of_Increment 467
of_GetUpdateRequestor of_Init
n_cst_luw 1057 n_cn 501
u_lvs 240 n_tr 559
u_tvs 354 of_Initialize
of_GetUpdatesPending 770 n_cst_dwsrv_find 738
of_GetUpdateStyle n_cst_rtefind 1203
n_cst_dwsrv_linkage 770 of_InitSecurity 1207

Index-12
 Index

of_InsertDocument 297 of_IsDisabled

of_InsertItem n_cst_tmgsingle 1261
n_cst_lvsrv_datasource 1095 of_IsDisabledl
n_cst_tvsrv_levelsource 1331 n_cst_tmgmultiple 1252
u_lvs 240, 241 of_IsDropDown
u_tvs 355, 356 u_calculator 405
of_InsertPicture 298 of_IsDuplicatesAllowed 1046
of_InsertRow 915 of_IsEmpty 1234
of_Integer 626 n_cst_linkedlistbase 1034
of_InvertSelection 927 of_IsEventDefined 1130
of_IsAllowFindDlg 739 of_IsEventImplemented 1131
of_IsAllowReplaceDlg 739 of_IsExclude 1118
of_IsAllowSqlcaDestroy 1290 of_IsFormat 1234
of_IsAlpha 1231 of_IsFunctionDefined 1131
of_IsAlphaNum 1232 of_IsHolidayBold 437
of_IsAlwaysRedraw 435 of_IsInArray 1122
of_IsAlwaysValidate of_IsInitialValue
n_cst_luw 1058 u_calculator 406
u_base 387 u_calendar 438
u_lvs 242 of_IsInList 1046
u_tab 325 of_IsKey 773
u_tvs 357 of_IsLeapYear 637
w_master 41 of_IsLinked 773
of_IsAncestorClass 1129 of_IsLogOpen 654
of_IsArithmeticOperator 1233 of_IsLower 1235
of_IsAutoDisable of_IsMarkedDayBold 438
n_cst_tmgsingle 1261 of_IsNumericType 407
of_IsAutoDisablel of_IsOngoingFind
n_cst_tmgmultiple 1252 n_cst_dwsrv_find 740
of_IsAutoReset 468 n_cst_rtefind 1204
of_IsCloseOnClick of_IsOperator 407
u_calculator 405 of_IsPredefined 1414
u_calendar 436 of_IsPrintable 1235
of_IsCloseOnDClick 436 of_IsPropertyOpen 827
of_IsColumnHeader 1117 of_IsPunctuation 1236
of_IsCompareObjectAssigned of_IsRecursiveLevel 1333
n_cst_linkedlistbase 1034 of_IsRegistered
of_IsComparisonOperator 1233 n_cst_dwcache 673
of_IsConfirmOnDelete n_cst_dwsrv_dropdownsearch 713
n_cst_dwsrv_linkage 772 n_cst_dwsrv_multitable 813
n_cst_lvsrv_datasource 1096 n_cst_dwsrv_reqcolumn 888
n_cst_tvsrv_levelsource 1332 n_cst_dwsrv_resize 898
of_IsConfirmOnRowChange 772 n_cst_mru 1144
of_IsConnected 560 n_cst_tmgsingle 1253, 1262
of_IsDateType 437 n_cst_trregistration 1291
of_IsDestructorDestroy 1290 u_calculator 408

Index-13
Index

u_calendar 439 of_Load 836

of_IsRegistryAvailable 589 of_LoadMRU 1144
of_IsRestoreApp 605 of_LoadPredefinedMsg 963
of_IsRestoreUser 605 of_LogonDlg 590
of_IsRMBMenu of_Message
u_lvs 243 n_cst_debug 655
u_tvs 357 n_cst_error 964
of_IsRoot of_MessageBox
n_cst_dwsrv_linkage 774 n_base 570
u_dw 176 n_cn 502
of_IsSaturdayBold 439 n_ds 518
of_IsSelfUpdatingObject 1058 n_err 530
of_IsSharedProperty 176 n_ms 534
of_IsSorted 1047 n_msg 539
of_IsSpace 1236 n_pl 545
of_IsSundayBold 440 n_tr 560
of_IsSyncOnKeyChange 774 n_trp 566
of_IsUpdateable u_base 388
n_ds 518 u_cb 129
u_base 387 u_cbx 132
u_dw 177 u_ddlb 139
u_lvs 243 u_ddplb 146
u_tab 326 u_dw 177
u_tvs 358 u_em 200
w_master 41 u_gr 205
of_IsUpdateOnRowChange 775 u_hpb 208
of_IsUpper 1237 u_hsb 211
of_IsValid 638 u_htb 214
of_IsWeekDay 638 u_lb 218
of_IsWeekEnd 639 u_lvs 243
of_IsWhiteSpace 1238 u_mle 257
of_ItemFocusChanged 775 u_oc 265
of_Julian 640 u_p 268
of_JulianDayNumber 640 u_pb 271
of_KeybRowSelect 928 u_phl 274
of_KeybRowSelectExt 929 u_plb 278
of_KeyChanged 776 u_rb 281
of_KeySync 777 u_rte 298
of_LastDayOfMonth 641 u_sle 311
of_LastPage 821 u_st 314
of_LastPos 1238 u_sth 317
of_LButtonUp u_tab 326
u_st_splitbar 490 u_tvs 358
of_LeftTrim 1239 u_vpb 370
of_LinkDetail 777 u_vsb 373
of_LinkTo 778 u_vtb 376

Index-14
 Index

w_master 42 u_tab 327

of_MilliSecsAfter 641 u_tvs 360
of_Modify w_master 43
n_cst_dwsrv 699 of_PrepPrint 865
n_cst_winsrv_statusbar 1415 of_PreUpdate 1059
of_MonthsAfter 642, 643 of_PrintDlg
of_MouseMove 490 n_cst_platform 1176
of_Open n_cst_platformwin32 1185
n_cst_selection 1211 of_PrintLog 655
n_cst_winsrv_statusbar 1415 of_PrintReport 866
of_OpenDocument 300 of_PrintTree 1359
of_OpenLog 655 of_ProcessLog 967
of_OpenProperty 828 of_ProcessMessage 967
of_OpenPropertyService 828 of_ProcessMessageSubstitution 968
of_OpenSQLSpy 1219 of_ProcessNotify 968
of_OSType 626 of_Push 1226
of_PadLeft 1240 of_Put 1189
of_PadRight 1240 of_Quote 1241
of_Page 822 of_ReadKeys 1145
of_PageAcross 822 of_ReadMRUKeys 1145
of_PageCount 823 of_RecalcInterval 1253
of_PageCountAcross 823 of_RedirectFocus
of_PageSetupDlg 1175 u_calculator 409
of_Parse 1216 u_calendar 440
of_ParseArgs 1333 of_Redraw 491
of_ParseCols 1334 of_Refresh
of_ParsePath 998 n_cst_dwcache 674
of_ParseSortAttrib 943 n_cst_dwsrv_linkage 779
of_ParseToArray 1241 n_cst_lvsrv_datasource 1096
of_PerformMath 409 of_RefreshDDDWs 701
of_PlaySound of_Register
n_cst_platform 1176 n_cst_dwcache 674, 676
n_cst_platformwin32 1185 n_cst_dwsrv_dropdownsearch 714
of_Pop 1225 n_cst_dwsrv_linkage 779
of_Populate n_cst_dwsrv_multitable 813
u_lvs 244 n_cst_dwsrv_resize 899
u_tvs 359 n_cst_lvsrv_datasource 1097
of_PopulateDDDW 701 n_cst_mru 1146
of_Position 662 n_cst_resize 1194
of_PostUpdate n_cst_tmgsingle 1254, 1262
n_cst_dwsrv_linkage 778 n_cst_trregistration 1291
n_cst_luw 1059 n_cst_tvsrv_levelsource 1335
n_ds 520 n_cst_winsrv_statusbar 1416
u_base 389 u_calculator 410
u_dw 178 u_calendar 441
u_lvs 245 u_st_splitbar 492

Index-15
Index

of_RegisterArgs 680 n_cst_tvsrv_levelsource 1346

of_RegisterDataSource of_Resize
n_cst_lvsrv_datasource 1103 n_cst_dwsrv_resize 903
n_cst_tvsrv_levelsource 1343 n_cst_resize 1196
of_RegisterPredefined 1417 of_Restore
of_RegisterReportColumn 1104 n_cst_apppreference 606
of_RegisterSkipColumn 888 n_cst_mru 1147
of_RelativeDateTime 643 n_cst_winsrv_preference 1371
of_RelativeMonth 644 of_RestoreApp 608
of_RelativeYear 645 of_RestoreFocusPoint 1418
of_Remove of_RestoreMenu 1373
n_cst_linkedlistbase 1035 of_RestorePositiveNumber 1374
n_cst_list 1048 of_RestoreUpdateSettings 814
n_cst_tree 1276 of_RestoreUser 608
of_RemoveChildren 1344 of_Retrieve
of_RemoveColumn 714 n_cst_dwsrv_linkage 782
of_RemoveDirectory n_cst_lvsrv_datasource 1106
n_cst_filesrv 998 n_cst_tvsrv_levelsource 1346
n_cst_filesrvwin32 1020 n_ds 520
of_RemoveHead u_dw 179
n_cst_linkedlistbase 1035 u_lvs 246
n_cst_list 1048, 1049 u_tvs 361
of_RemoveNonPrint 1242 of_RetrieveDetails 783
of_RemoveTail of_RightTrim 1243
n_cst_linkedlistbase 1036 of_Rollback 561
of_RemoveWhiteSpace 1242 of_RowSelect 929
of_Replace 740 of_RowSelectExt 930
of_Reset of_RowSelectMulti 931
n_cst_dwsrv_linkage 780 of_RowSelectSingle 931
n_cst_lvsrv_datasource 1105 of_Save
n_cst_mru 1147 n_cst_apppreference 609
n_cst_tvsrv_levelsource 1345 n_cst_dwsrv_linkage 784
u_calculator 412 n_cst_dwsrv_querymode 837
u_calendar 443 n_cst_luw 1060
u_dw 179 n_cst_mru 1148
u_lvs 245 n_cst_winsrv_preference 1375
u_progressbar 468 of_SaveApp 611
u_tvs 360 of_SaveMenu 1376
of_ResetArguments 780 of_SaveUser 612
of_ResetList 1105 of_ScrollDetails 784
of_ResetMaster 781 of_Search 1277
of_ResetTree 1345 of_SearchChild 1299
of_ResetUndo 867 of_SearchItem 715
of_ResetUpdate of_SecondsAfter 645
n_cst_dwsrv_linkage 781 of_SelectedCount 932
n_cst_lvsrv_datasource 1106 of_SelectText 741

Index-16
 Index

of_SendMessage of_SetBarWidth 1425

m_master 71 of_SetBase
n_cst_menu 1123 n_ds 521
of_SetAllowFindDlg 742 u_dw 180
of_SetAllowReplaceDlg 742 u_lvs 247
of_SetAllowSqlcaDestroy 1292 u_tvs 362
of_SetAlwaysOnTop w_master 44
n_cst_debug 656 of_SetBatchMode 1221
n_cst_sqlspy 1220 of_SetBeep 969
of_SetAlwaysRedraw 444 of_SetBorder 870
of_SetAlwaysValidate of_SetBorderType 1425
n_cst_luw 1061 of_SetCache
u_base 389 n_cst_lvsrv_datasource 1107
u_lvs 246 n_cst_tvsrv_levelsource 1347
u_tab 328 of_SetCloseOnClick
u_tvs 361 u_calculator 413
w_master 43 u_calendar 445
of_SetAppend 520 of_SetCloseOnDClick 445
of_SetAppIniFile of_SetColor 871
n_cst_appmanager 591 of_SetColumnDisplayNameStyle 702
of_SetAppKey 591, 614 of_SetColumnHeader
of_SetAppPreference n_cst_dwsrv_sort 944
n_cst_appmanager 592 n_cst_lvsrv_sort 1118
of_SetArguments 785 of_SetColumnNameSource 702
of_SetAutoDisable of_SetCompare
n_cst_tmgsingle 1263 n_cst_linkedlistbase 1036
of_SetAutoDisablel n_cst_tree 1277
n_cst_tmgmultiple 1255 of_SetConfirmOnDelete
of_SetAutoReset 469 n_cst_dwsrv_linkage 786
of_SetAutoRollback 562 n_cst_dwsrv_rowmanager 916
of_SetBackColor 469 n_cst_lvsrv_datasource 1107
of_SetBackground 867 n_cst_tvsrv_levelsource 1348
of_SetBalance 1281 of_SetConfirmOnRowChange 786
of_SetBar 1418 of_SetContinuousPages 300
of_SetBarAutoClear 1419 of_SetCopyright 592
of_SetBarColor 492 of_SetCreationDateTime
of_SetBarFillColor 1420 n_cst_filesrv 999
of_SetBarFillStyle 1421 n_cst_filesrvwin32 1021
of_SetBarMax 1421, 1422 of_SetCurrentState 1388
of_SetBarMoveColor 493 of_SetCustomUpdate
of_SetBarOffsetX 1422 n_cst_dwsrv_linkage 787
of_SetBarOffsetY 1423 n_cst_tvsrv_levelsource 1348
of_SetBarPosition 1423 of_SetData 1158
of_SetBarStep 1424 of_SetDataSource
of_SetBarStyle 1419 u_lvs 247
of_SetBarTextColor 1425 u_tvs 362

Index-17
Index

of_SetDate of_SetDWProperty 656

u_calendar 446 of_SetEnabled
of_SetDateFormat n_cst_dwsrv_printpreview 824
u_calendar 446 n_cst_dwsrv_querymode 838
of_SetDBErrorMsg of_SetError 594
n_cst_luw 1062 of_SetExclude
w_master 44 n_cst_dwsrv_filter 725
of_SetDebug 593 n_cst_dwsrv_sort 945
of_SetDefaultBackColor 873 n_cst_lvsrv_sort 1119
of_SetDefaultBorder 873 of_SetFileArchive 999
of_SetDefaultCharset 874 of_SetFileAttributes
of_SetDefaultColor 875 n_cst_filesrv 1000
of_SetDefaultFontFace 875 n_cst_filesrvwin32 1022
of_SetDefaultFontSize 875 of_SetFileHidden 1000
of_SetDefaultHeaderSuffix 703 of_SetFileName 301
of_SetDeleteStyle of_SetFileReadonly 1001
n_cst_dwsrv_linkage 787 of_SetFileSystem 1001
n_cst_tvsrv_levelsource 1349 of_SetFillColor 471
of_SetDelimiter 1148 of_SetFillStyle 471
of_SetDestructorDestroy 1292 of_SetFilter
of_SetDisabled n_cst_dwsrv_filter 725
n_cst_tmgsingle 1264 u_dw 182
of_SetDisabledl of_SetFind
n_cst_tmgmultiple 1255 u_dw 182
of_SetDisplayItem u_rte 301
n_cst_dwsrv 703 of_SetFindWindowClasses 1176
n_cst_lvsrv 1071 of_SetFocusOnRequestor
n_cst_tvsrv 1300 u_calculator 414
of_SetDisplayStyle 470 u_calendar 448
of_SetDisplayUnits of_SetFont
n_cst_dwsrv 704 n_cst_dwsrv_report 876
n_cst_lvsrv 1071 u_progressbar 472
n_cst_tvsrv 1301 of_SetFontBold 474
of_SetDoubleParm 540 of_SetFontCharSet 474
of_SetDropDown of_SetFontFace 475
u_calculator 413 of_SetFontFamily 475
u_calendar 447 of_SetFontItalic 476
of_SetDropDownCalculator of_SetFontPitch 476
u_dw 180 of_SetFontSize 477
u_em 201 of_SetFontUnderline 477
of_SetDropDownCalendar of_SetFrame 594
u_dw 181 of_SetGapWidth 1426
u_em 202 of_SetGDI 1427
of_SetDropDownSearch 181 of_SetGDIThreshold 1427
of_SetDuplicatesAllowed 1049 of_SetGDIWidth 1428
of_SetDwCache 593 of_SetHelpFile 595

Index-18
 Index

of_SetHoliday 448 of_SetMemWidth 1429

of_SetHolidayBold 449 of_SetMenuItems 1377
of_SetHolidayColor 449 of_SetMessageText 479
of_SetHorizontalPointer 493 of_SetMicrohelp 596
of_SetIgnoreFileExists 302 of_SetMinimum 479
of_SetInitialValue of_SetMinObjectSize 494
u_calculator 415 of_SetMinSize
u_calendar 450 n_cst_dwsrv_resize 904
of_SetItem 704 n_cst_resize 1197
of_SetItemAttributes of_SetMRU 596
n_cst_lvsrv_datasource 1108 of_SetMultiple 548
n_cst_tvsrv_levelsource 1349 of_SetMultiTable
of_SetItemCount 1149 n_ds 521
of_SetKey 1159 u_dw 183
of_SetKeyboard 932 of_SetName 563
of_SetKeyCols 788 of_SetNext 1159
of_SetKeyValue 1244 of_SetNotifyConnection 971
of_SetKeyValues 789 of_SetNotifyPreTitle 972
of_SetLastAccessDate of_SetNotifySeverity 972
n_cst_filesrv 1002 of_SetNotifyWho 973
n_cst_filesrvwin32 1023 of_SetOrigSize
of_SetLastWriteDateTime n_cst_dwsrv_resize 904
n_cst_filesrv 1002 n_cst_resize 1197
n_cst_filesrvwin32 1024 of_SetOtherSaveObjects 790
of_SetLineEnding 1029 of_SetOverlayPicture
of_SetLinkage 183 n_cst_lvsrv_datasource 1092
of_SetLogFile n_cst_tvsrv_levelsource 1327
n_cst_error 969 of_SetOverLayPictureColumn
n_cst_sqlspy 1221 n_cst_lvsrv_datasource 1109
of_SetLogFileStyle 970 n_cst_tvsrv_levelsource 1350
of_SetLogicalUnitOfWork of_SetPageInputField 302
u_base 390 of_SetParent
u_lvs 248 m_dw 61
u_tab 328 m_edit 63
u_tvs 363 m_oc 74
w_master 45 m_tvs 76
of_SetLogidAndPassword 563 m_view 66
of_SetLogo 595 of_SetPictureColumn
of_SetLogSeverity 971 n_cst_lvsrv_datasource 1109
of_SetMarkedDay 451 n_cst_tvsrv_levelsource 1350
of_SetMarkedDayBold 451 of_SetPosition 480
of_SetMarkedDayColor 452 of_SetPosSize 1378
of_SetMaster 789 of_SetPowerObjectParm 540
of_SetMaximum 478 of_SetPredefinedSource 974
of_SetMem 1428 of_SetPreference
of_SetMemThreshold 1429 w_master 45

Index-19
Index

of_SetPrev 1160 of_SetRuler 824

of_SetPrint 363 of_SetSaturdayBold 453
of_SetPrintPreview of_SetSaturdayColor 454
n_ds 522 of_SetSaveSound 791
u_dw 184 of_SetSecurity
of_SetProperty 184 n_cst_appmanager 597
of_SetQueryCols 838 n_cst_security 1209
of_SetQuerymode 185 of_SetSelectedPictureColumn 1352
of_SetRecursive 1351 of_SetSharedProperty 188
of_SetRedraw 790 of_SetSheetManager 16
of_SetRefreshRate 1430 of_SetSingle 549
of_SetRelativeZoom 880 of_SetSort
of_SetReport n_cst_dwsrv_sort 945
n_ds 523 u_dw 189
u_dw 186 u_lvs 248
of_SetReqColumn 186 of_SetSorted 1050
of_SetRequestor of_SetSQLSpy 657
n_cst_apppreference 614 of_SetStartPageNumber 303
n_cst_dropdown 662 of_SetStatePictureColumn
n_cst_dwsrv 705 n_cst_lvsrv_datasource 1110
n_cst_dwsrv_resize 905 n_cst_tvsrv_levelsource 1353
n_cst_luw 1062 of_SetStatusBar 16
n_cst_lvsrv 1072 of_SetStep 480
n_cst_rtefind 1205 of_SetStringParm 541
n_cst_tmgsingle 1264 of_SetStyle
n_cst_tvsrv 1301 n_cst_dwsrv_filter 726
n_cst_winsrv 1363 n_cst_dwsrv_linkage 791
u_calculator 415 n_cst_dwsrv_rowselection 933
u_calendar 452 n_cst_dwsrv_sort 946
of_SetRequestorl n_cst_error 974
n_cst_tmgmultiple 1256 of_SetSundayBold 454
of_SetResetCriteria 839 of_SetSundayColor 455
of_SetResize of_SetSyncOnKeyChange 792
u_base 390 of_SetTextColor 481
u_dw 187 of_SetTextStyleBold 303
u_tab 329 of_SetTextStyleItalic 304
w_master 46 of_SetTextStyleStrikeout 304
of_SetRestoreApp 615 of_SetTextStyleSubscript 305
of_SetRestoreRow 916 of_SetTextStyleSuperscript 305
of_SetRestoreUser 616 of_SetTextStyleUnderline 306
of_SetRetrieveOnDisabled 840 of_SetTimeOut 975
of_SetRMBMenu of_SetTimer 1430
u_lvs 248 of_SetTimerFormat 1430
u_tvs 364 of_SetTimerInterval 1431
of_SetRowManager 187 of_SetTimerWidth 1432
of_SetRowSelect 188 of_SetToNullIfEmpty 889

Index-20
 Index

of_SetToolbarItemOrder 1378 n_tr 564

of_SetToolbarItemSpace 1379 of_SetUseRegistry 1149
of_SetToolbarItemVisible 1379 of_SetUserID 597
of_SetToolbars 1380 of_SetUserIdAndPassword 565
of_SetToolbarTitles 1380 of_SetUserIniFile 1150
of_SetTrace 563 n_cst_appmanager 598
of_SetTransObject n_cst_apppreference 617
n_cst_dwsrv_linkage 793 of_SetUserKey 1151
n_ds 523 n_cst_appmanager 598
u_dw 189 n_cst_apppreference 617
of_SetTrRegistration 597 of_SetUserThreshold 1433
of_SetTypeToProcess 1063 of_SetUserWidth 1433
of_SetUnattended 976 of_SetValue 416
of_SetUndo of_SetValueOnRequestor 417
n_cst_lvsrv_datasource 1110 of_SetVersion 599
n_cst_tvsrv_levelsource 1353 of_SetVerticalPointer 495
of_SetUpdateable of_SetVisibleOnly
n_ds 524 n_cst_dwsrv_filter 727
u_base 391 n_cst_dwsrv_sort 947
u_dw 190 of_SetWindow 1381
u_lvs 249 of_SetXPosColumn 1111
u_tab 329 of_SetYPosColumn 1111
u_tvs 364 of_SetZoom 825
w_master 46 of_ShiftBand 881
of_SetUpdateBottomUp 793 of_Sort 948
of_SetUpdateObjects of_SortDirList 1003
u_base 391 of_SortMRU 1152
u_tab 329 of_Splash 600
w_master 47 of_SQLPreviewType 627
of_SetUpdateOnRowChange 794 of_SQLSyntax 1222
of_SetUpdateRequestor of_StoreUpdateSettings 815
n_cst_dwsrv_linkage 794 of_String 628
n_cst_luw 1063 of_Time 631
n_ds 524 of_ToolbarAlignment 631
u_base 392 of_ToolbarExists 1124
u_dw 190 of_Traverse 1278
u_lvs 249, 330 of_TriggerEvent
u_tvs 365 n_cst_dwsrv_linkage 796
w_master 47 n_cst_menu 1124
of_SetUpdateStyle of_Trim 1244
n_cst_tvsrv_levelsource 795, 1354 of_TypeOf 1198
of_SetUseColLinks 796 of_UnDelete 917
of_SetUseDisplay 947 of_Undo 882
of_SetUser of_UndoModified 797
n_cst_error 976 of_Unlink 797
n_cst_winsrv_statusbar 1432 of_UnlinkDetail 798

Index-21
Index

of_UnRegister u_base 393

n_cst_dwcache 680 u_dw 193
n_cst_dwsrv_dropdownsearch 715 u_lvs 251
n_cst_dwsrv_linkage 798 u_tab 331
n_cst_dwsrv_multitable 815 u_tvs 366
n_cst_dwsrv_reqcolumn 889 w_master 49
n_cst_dwsrv_resize 906 of_UpdateSkipString 890
n_cst_mru 1152 of_UpdatesPending
n_cst_resize 1198 n_cst_luw 1065
n_cst_tmgsingle 1265 n_ds 527
n_cst_trregistration 1293 u_base 394
n_cst_winsrv_statusbar 1434 u_dw 193
u_calculator 417 u_lvs 251
u_calendar 455 u_tab 332
of_UnRegisterl u_tvs 367
n_cst_tmgmultiple 1256 w_master 50
of_UnRegisterPredefined 1434 of_UpdateTopDown 803
of_UnRegisterReportColumn 1112 of_UpdateTopDownAndBottomUp 804
of_UnRegistert of_UpdateVisuals 481
n_cst_lvsrv_datasource 1112 n_cst_mru 1152
n_cst_tvsrv_levelsource 1355 of_UsesDisplayValue 948
of_Update of_Validation
n_cst_dwsrv_linkage 799 n_cst_dwsrv_linkage 805
n_cst_dwsrv_multitable 816 n_cst_luw 1066
n_cst_luw 1064 n_ds 528
n_cst_lvsrv_datasource 1113 u_base 394
n_cst_tvsrv_levelsource 1355 u_dw 194
n_ds 525 u_lvs 252
u_base 392 u_tab 332
u_dw 191 u_tvs 367
u_lvs 250 w_master 51
u_tab 330 of_Wait 646
u_tvs 365 of_WeekNumber 648
w_master 48 of_WeeksAfter 648
of_UpdateBottomUp 800 of_WindowState 632
of_UpdateBottomUpAndTopDown 800 of_WordCap 1245
of_UpdateChecks 49 of_WriteKeys 1154
of_UpdateCustom of_WriteMRUKeys 1153
n_cst_dwsrv_linkage 801 of_YearsAfter 649
n_cst_tvsrv_levelsource 1356 OLEControl 259
of_UpdateObjectData 495 OLEObject object 542
of_UpdateOnRowChange 802 OLEStorage object 543
of_UpdatePredefined 1435 OLEStream object 544
of_UpdatePrep 803 online Help
n_cst_luw 1064 accessing 7
n_ds 527 of_GetHelpFile 586

Index-22
 Index

of_SetHelpFile 595 w_master 22

Open event 21 pfc_ColumnClick 1115
pfc_ConnectionBegin 578
pfc_ConnectionEnd 579
pfc_ControlGotFocus
P w_master 22
PEAT sample application 8 w_sheet 57
pfc_AcceptText pfc_Copy
u_base 382 u_ddlb 136
u_dw 155 u_ddplb 143
u_lvs 225 u_dw 156
u_tab 320 u_em 197
u_tvs 339 u_mle 255
w_master 22 u_oc 261
pfc_AddAll u_rte 286
u_lvs 225 u_sle 309
u_tvs 339 pfc_Cut
pfc_AddItem u_ddlb 137
u_lvs 226 u_ddplb 144
u_tvs 340 u_dw 156
pfc_AddRow u_em 197
n_cst_dwsrv_rowmanager 909 u_mle 255
u_dw 156 u_oc 261
pfc_Apply 54 u_rte 287
pfc_BeginTran 22 u_sle 309
pfc_Cancel 54 pfc_DBError 23
pfc_Cascade pfc_DDCalculator
n_cst_winsrv_sheetmanager 1383 u_dw 157
w_frame 13 u_em 197
pfc_Clear pfc_DDCalendar
u_ddlb 136 u_dw 157
u_ddplb 143 u_em 198
u_dw 156 pfc_Debug 158
u_em 197 pfc_Decode
u_mle 254 n_cst_mru 1137
u_oc 260 pfc_Default 55
u_rte 286 pfc_Delete
u_sle 308 u_lvs 226
pfc_Clicked u_tvs 340
n_cst_dwsrv_linkage 749, 750 pfc_DeleteItem
n_cst_dwsrv_rowselection 921 n_cst_lvsrv_datasource 1076
n_cst_dwsrv_sort 936 n_cst_tvsrv_levelsource 1306
pfc_Close pfc_DeleteRow
n_cst_appmanager 577 n_cst_dwsrv_linkage 750
n_cst_apppreference 603 n_cst_dwsrv_rowmanager 909
n_cst_mru 1137 u_dw 158

Index-23
Index

pfc_Descendant u_lb 216

u_dw 158 u_lvs 227
w_master 23 u_plb 276
pfc_DropDown pfc_ItemChanged 751
u_calculator 400 pfc_ItemExpanding 1309
u_calendar 425 pfc_ItemFocusChanged
pfc_EditChanged 707 n_cst_dwsrv_dropdownsearch 708
pfc_EditObject 261 n_cst_dwsrv_linkage 751
pfc_Encode pfc_LastPage
n_cst_mru 1138 u_dw 159
pfc_EndLabelEdit u_rte 288
n_cst_lvsrv_datasource 1076 pfc_Layer
n_cst_tvsrv_levelsource 1307 n_cst_winsrv_sheetmanager 1383
pfc_EndTran w_frame 13
w_master 23 pfc_LButtonDown 921
pfc_Exit 579 pfc_LButtonUp 922
pfc_FilterDlg pfc_Logon 580
n_cst_dwsrv_filter 719 pfc_MessageRouter 24
u_dw 158 pfc_MicroHelp
pfc_FindDlg w_frame 13
n_cst_dwsrv_find 730 w_master 25
n_cst_rtefind 1201 w_sheet 57
u_dw 158 pfc_MinimizeAll
u_rte 287 n_cst_winsrv_sheetmanager 1383
pfc_FindNext w_frame 14
n_cst_dwsrv_find 730 pfc_Move event 1393
n_cst_rtefind 1201 pfc_MRUClicked 25
pfc_FirstPage pfc_MRUProcess 25
u_dw 159 pfc_MRURestore 26
u_rte 287 pfc_MRUSave 27
pfc_Help 24 pfc_New
pfc_Hide event 1393 u_lvs 228
pfc_Idle 579 u_tvs 341
pfc_InsertFile 287 w_master 27
pfc_InsertItem pfc_NextDay 425
n_cst_lvsrv_datasource 1077 pfc_NextMonth 426
n_cst_tvsrv_levelsource 1308 pfc_NextPage
u_lvs 226 u_dw 159
u_tvs 340 u_rte 288
pfc_InsertObject 262 pfc_NextWeek 426
pfc_InsertPicture 288 pfc_Open
pfc_InsertRow n_cst_appmanager 580
n_cst_dwsrv_linkage 751 n_cst_apppreference 604
n_cst_dwsrv_rowmanager 910 n_cst_mru 1138
u_dw 159 u_rte 288
pfc_InvertSelection w_master 27

Index-24
 Index

pfc_OpenObject 262 pfc_PreInsert

pfc_Operators u_lvs 229
n_cst_dwsrv_querymode 832 u_tvs 343
u_dw 159 pfc_PreInsertRow
pfc_PageSetup n_cst_dwsrv_linkage 752
n_ds 510 u_dw 162
u_dw 160 pfc_PreLogonDlg 582
w_master 28 pfc_PreMRUSave 30
pfc_PageSetupDlg pfc_PreOpen 30
n_ds 510 pfc_PrePageSetupDlg
u_dw 160 n_ds 511
pfc_Paste u_dw 163
u_ddlb 137 pfc_PrePrintDlg
u_ddplb 144 n_ds 511
u_dw 160 u_dw 163
u_em 198 u_rte 289
u_mle 255 pfc_PreRefreshItem
u_oc 262 u_lvs 229
u_rte 289 u_tvs 343
u_sle 309 pfc_PreRefreshLevel 344
pfc_PasteSpecial 263 pfc_PreReplaceDlg 164
pfc_Populate pfc_PreRestoreRow
u_lvs 228 u_dw 165
u_tvs 342 pfc_PreRmbMenu
pfc_PopulateDDDW 160 u_ddlb 137
pfc_PostOpen u_ddplb 144
w_frame 14 u_dw 165
w_master 28 u_em 198
pfc_PostUpdate u_lvs 230
n_ds 511 u_mle 255
u_base 382 u_oc 263
u_dw 161 u_rte 289
u_lvs 228 u_sle 309
u_tab 321 u_tvs 344
u_tvs 342 pfc_PreSplash 582
w_master 29 pfc_PreToolbar 14
pfc_PreAbout 581 pfc_PreUpdate
pfc_PreClose 29 u_dw 166
pfc_PreDebug 164 w_master 31
pfc_PreDelete pfc_PrevDay 426
u_lvs 229 pfc_PreviousPage
u_tvs 343 u_dw 166
pfc_PreDeleteRow u_rte 290
n_cst_dwsrv_linkage 752 pfc_PrevMonth 426
u_dw 162 pfc_PrevWeek 427
pfc_PreFindDlg 162 pfc_Print

Index-25
Index

n_ds 512 n_cst_dwsrv_find 731

u_dw 166 n_cst_rtefind 1202
u_rte 290 u_dw 168
w_master 31 u_rte 291
pfc_PrintDlg pfc_ResetUpdate
n_ds 512 n_ds 513
u_dw 166 u_dw 168
u_rte 290 pfc_Resize event
pfc_PrintImmediate n_cst_dwsrv_resize 894
n_ds 512 n_cst_resize 1193
u_dw 167 n_cst_winsrv_statusbar 1394
u_rte 291 pfc_RestoreRow
w_frame 32 n_cst_dwsrv_rowmanager 910
pfc_PrintPreview u_dw 168
n_ds 513 pfc_Retrieve
u_dw 167 n_ds 513
u_rte 291 u_dw 168
pfc_Properties u_lvs 231
u_dw 167 u_tvs 346
u_lvs 230 pfc_RetrieveDDDW 169
u_tvs 345 pfc_RetrieveEnd 753
pfc_RButtonDown pfc_RetrieveStart 754
n_cst_dwsrv_linkage 753 pfc_RowChanged
n_cst_dwsrv_rowselection 923 n_cst_dwsrv_linkage 754
pfc_RButtonUp 923 u_dw 169
pfc_Refresh pfc_RowFocusChanged
n_cst_lvsrv_datasource 1078 n_cst_dwsrv_linkage 754
u_lvs 230 n_cst_dwsrv_rowselection 924
pfc_RefreshItem pfc_RowFocusChanging 755
n_cst_lvsrv_datasource 1078 pfc_RowValidation 169
n_cst_tvsrv_levelsource 1309 pfc_Ruler
u_lvs 231 n_ds 513
u_tvs 345 u_dw 169
pfc_RefreshLevel u_rte 291
n_cst_tvsrv_levelsource 1310 pfc_Save
u_tvs 345 u_rte 292
pfc_Rename w_master 32
u_lvs 231 pfc_SaveAs
u_tvs 346 u_rte 292
pfc_Replace w_master 33
n_cst_dwsrv_find 730 pfc_SaveObjects 33
n_cst_rtefind 1202 pfc_SearchCompare 347
pfc_ReplaceAll pfc_SelectAll
n_cst_dwsrv_find 731 u_ddlb 137
n_cst_rtefind 1202 u_ddplb 144
pfc_ReplaceDlg u_dw 170

Index-26
 Index

u_em 199 pfc_UndoEdit

u_lb 217 n_cst_lvsrv_datasource 1080
u_lvs 232 n_cst_tvsrv_levelsource 1312
u_mle 256 pfc_UndoInsert
u_plb 277 n_cst_lvsrv_datasource 1081
u_rte 292 n_cst_tvsrv_levelsource 1312
u_sle 310 pfc_Update
pfc_SetItemAttributes n_ds 514
n_cst_lvsrv_datasource 1079 u_base 383
n_cst_tvsrv_levelsource 1310 u_dw 170
u_lvs 232 u_lvs 232
u_tvs 347 u_tab 321
pfc_Show event 1394 u_tvs 348
pfc_Sort 1116 w_master 34
pfc_SortDlg pfc_UpdateLinks 263
n_cst_dwsrv_sort 937 pfc_UpdateObjects 34
u_dw 170 pfc_UpdatePrep
pfc_StatusBarClicked event 1395 n_ds 514
pfc_StatusBarDoubleClick event 1395 u_base 383
pfc_StatusBarRButtonUp event 1396 u_dw 171
pfc_SystemError 583 u_lvs 233
pfc_TileHorizontal u_tab 321
n_cst_winsrv_sheetmanager 1384 u_tvs 348
w_frame 14 w_master 35
pfc_TileVertical pfc_UpdatesPending
n_cst_winsrv_sheetmanager 1384 n_ds 514
w_frame 14 u_base 383
pfc_Timer u_dw 171
n_cst_tmgmultiple 1249, 1258 u_lvs 233
pfc_Toolbars 15 u_tab 322
pfc_Undo u_tvs 349
n_cst_lvsrv_datasource 1079 w_master 35
n_cst_tvsrv_levelsource 1311 pfc_UpdatesPendingRef 36
u_dw 170 pfc_Validation
u_em 199 n_ds 514
u_lvs 232 u_base 384
u_mle 256 u_dw 171
u_rte 292 u_lvs 234
u_sle 310 u_tab 322
u_tvs 348 u_tvs 349
pfc_UndoArrange w_master 36
n_cst_winsrv_sheetmanager 1384 pfc_Values
w_frame 15 n_cst_dwsrv_querymode 832
pfc_UndoDelete u_dw 171
n_cst_lvsrv_datasource 1080 pfc_Zoom
n_cst_tvsrv_levelsource 1311 n_ds 515

Index-27
Index

u_dw 172 registry

Picture 267 of_GetAppKey 585
PictureButton 270 of_IsRegistryAvailable 589
PictureHyperlink 273 of_SetAppKey 591, 614
PictureListBox 276 of_SetUserKey 598, 617, 1151
Pipeline object 545 report service
platform service n_cst_dssrv_report 667
f_SetPlatform 79 n_cst_dwsrv_report 841
n_cst_platform 1170 required column 884
n_cst_platformwin32 1178 Resize event
popup menu u_base 384
m_dw 60 u_dw 172
m_edit 62 u_tab 322
m_lvs 65 w_frame 15
m_oc 73 w_master 37
m_tvs 75 resize service
preference service 1365 DataWindow 891
print preview service n_cst_resize 1190
n_cst_dwsrv_printpreview 817 RetrieveEnd event 173
PrintHeader event 293 RetrieveStart event
property service n_ds 515
main discussion 826 u_dw 173
RichTextEdit 283
RightClicked event
u_lvs 234
Q u_tvs 349
query mode service 830 Rollback 561
queue object 1187 row manager service 908
row selection services 918
RowFocusChanged event 173

R
RadioButton 280
RButtonDown event S
u_dw 172 s_pagesetupattrib 123
u_progressbar 460 s_paperattrib 124
RButtonUp event s_printdlgattrib 125
u_ddlb 138 s_svalue 126
u_ddplb 145 sample application 8
u_dw 172 security service
u_em 199 n_cst_security 1206
u_lvs 234 of_SetAppPreference 592
u_mle 256 of_SetMRU 596
u_oc 264 of_SetSecurity 597
u_rte 293 selection service 1210
u_sle 310 Service object 547

Index-28
 Index

sheet manager service 1382 u_ddplb 141

Show event 15 u_dw
SingleLineEdit 307 m_dw 60
Sort event 234 main discussion 148
sort service 934 u_em 195
splash screen u_gb 203
of_Splash 600 u_gr 204
pfc_PreSplash 582 u_hpb 207
splitbar service 483 u_hsb 210
SQL parsing service 1215 u_htb 213
SQL Spy u_lb 216
main discussion 1218 u_lvs
of_SetSQLSpy 657 m_lvs 65
SQLPreview event main discussion 220
n_ds 515 u_mle 253
u_dw 173 u_oc
StaticText 313 m_oc 73
StaticTextHyperlink 316 main discussion 259
status bar service 1389 u_p 267
string parsing service 1227 u_pb 270
u_phl 273
u_plb 276
u_progressbar 457
T u_rb 280
Tab control 319 u_rte
TabPage 497 main discussion 283
token 1230 n_cst_rtefind 1200
transaction object 550 u_sle 307
transaction registration service u_st 313
main discussion 1285 u_st_splitbar 483
of_SetTrRegistration 597 u_sth 316
Transport object 566 u_tab
TreeView 334 main discussion 319
TreeView base service 1294 n_cst_resize 1190
TreeView level source service 1303 u_tabpg 497
TreeView print service 1358 u_tvs
m_tvs 75
main discussion 334
u_vpb 369
U u_vsb 372
u_base 380 u_vtb 375
u_calculator 396 user INI file 598, 617, 1150
u_calendar 419
u_cb 128
u_cbx 131
u_ddlb 134

Index-29
Index

V
VerticalProgressBar 369
VerticalScrollBar 372
VerticalTrackBar 375

W
w_child 10
w_debuglog 656
w_frame 11
w_main 17
w_master
main discussion 18
n_cst_resize 1190
w_popup 52
w_response 53
w_sheet 56
w_sqlspy 1220
window services
n_cst_winsrv 1362
n_cst_winsrv_preference 1365
n_cst_winsrv_sheetmanager 1382
n_cst_winsrv_statusbar 1389

Z
zoom
of_GetZoom 821
of_SetRelativeZoom 880
pfc_Zoom (n_ds) 515
pfc_Zoom (u_dw) 172

Index-30