PFC programming Basics

Summary:
This chapter describes the basic skills of PFC programming and shows you how to use PFC to write applications.
Set Application Manager
The first step to create a PFC application is to configure the application and create the Application Manager--n_cst_appmanager. The Application Manager replaces the original application object. All the scripts originally written in the Application object will be rewritten in the Application Manager. The Application Manager also maintains the attributes of the application through instance variables and functions. There are frame windows, INI files of applications and users, registration keys, and help files.

Note:
Use separate physical files
Each Independent Application must have its own set of files. You cannot share parent files, that is, files starting with PFC. This is determined by the internal inheritance relationship of PFC.
For example, assume that both application 1 and Application 2 have their own set of extended PFC library files, but they share parent files (PFC library files ). In this case, Application 1 adds a function named of_SetData to the w_master of its PFE (PFC extension library. In this way, this function will be valid in all child classes of w_master. These child classes are pfc_w_main, pfc_w_frame, and pfc_w_sheet. These objects are exactly in the parent files shared by the two applications (PFC library files. In this way, when application 2 re-generates the application (regenerate), because the PFE file of Application 2 does not contain the of_SetData function. In this way, the pointer to the of_SetData function in all child classes of w_master will be deleted. In this way, when application 1 runs, it will cause runtime errors and compilation errors.

Procedure
1. Open the application paint brush.
2. Define the library file list.
PFCAPSRV. PBL
PFCDWSRV. PBL
PFCMAIN. PBL
PFCUTIL. PBL
Pfcwnsrv. PBL
Pfeapsrv. PBL
Pfedwsrv. PBL
Pfemain. PBL
Pfeutil. PBL
Pfewnsrc. PBL
Pfcold. PBL (if your application uses an earlier version of the PFC library, add this file to the library List)
3. Open the script brush in the application paint brush and define the global variable GNV _ app of the n_cst_appmanager type.
The n_cst_appmanger gnv_app variable name must be gnv_app, because the object, function, and event of PFC all need the n_cst_appm anager or its subclass's global variable-gnv_app.

4. Add the following code to the open event of the Application object. It is used to create n_cst_appmanager and call the pfc_open event.
Gnv_app = create n_cst_appmanager
Gnv_app.event pfc_open (CommandLine)
5. Add the following code to the close event of the Application object.
Gnv_app.event pfc_close ()
Destroy gnv_app
6. Add the following code to the systemerror event of the Application object. Call the pfc_systemerror event.
Gnv_app.event pfc_systemerror ()
7. Close the application paint brush and save the changes.
8. Open the User-Defined Object paint brush. Locate n_cst_appmanager in pfeapsrv. PBL and open it, or its subclass.
9. Call its function in the constructor event of n_cst_appmanager to initialize instance variables related to the software version number, company, and INI files.
10. Open the application service you want in the pfc_open event of n_cst_appmanager.
The service you want to open calls the function application preference of_setapppreference datawindow caching of_setdwcache error of_seterror most recently used object of_setmru transaction registration of_setsecurity debug of_setdebug

11. Add the code to open your initial window in the pfc_open event, for example, frame window or call the of_splash () function that displays the flash window.
12. (optional) Add the code to the pfc_preabout, pfc_prelogondlg, and pfc_presplash events to customize the dialog box (about box), logon box, and splash screen ).

13. (optional) Add the code to the pfc_idle, pfc_connectionbegin, and pfc_connectionend events.
L _ calls the pfc_idle event in the idle event of the Application object.
L _ call the pfc_connectionbegin event in the connectionbegin event of the Application object.
L _ call the pfc_connectionend event in the connectionend event of the Application object.
14. Save n_cst_appmanager
How to display a pop-up window
It is very simple. You only need to write the following code before opening the code in the first window in the pfc_open event:
This. of_splash (1)
Open (w_tut_frame) (varies depending on different applications !)
How to display the logon window
1. Call the of_logondlg function in the open event of the Framework Window:
Integer li_return
Li_return = gnv_app.of_logondlg ()
If li_return = 1 then
This. setmicrohelp ("Logon successful ")
Else
MessageBox ("Logon", "Logon Failed ")
Close (this)
End if
The of_logondlg function displays the w_logon dialog box and prompts you to enter the user name and password. When the user clicks the OK button, the pfc_logon event of n_cst_appmanager is triggered.

Similarly, you can call the of_logondlg function immediately after opening the framework window in the pfc_open event of n_cst_appmanager. However, do not call of_logondlg immediately after of_splash.

2. Write the login code to the database in the pfc_logon event of n_cst_appmanager. This example assumes that there is an INI file that contains all the information that needs to be logged on to the database, except the user name and password. It is also assumed that you have changed the default sqlca type to n_tr (the bookstore object type specified by PFC ).

Integer li_returnstring ls_inifile, ls_userid, ls_password
Ls_inifile = gnv_app.of_GetAppIniFile ()
If sqlca. of_Init (ls_inifile, "Database") =-1 THEN
Return-1
END IF
// As_userid and as_password are arguments
// To the pfc_Logon event
SQLCA. of_SetUser (as_userid, as_password)
If sqlca. of_Connect () =-1 THEN
Return-1
ELSE
Gnv_app.of_SetUserID (as_userid)
Return 1
End If
Create an application
Create an MDI Application
Use the w_frame and w_sheet windows as the parent class of your frame window and form window. In the w_sheet window, add the events, instance variables, and functions required by all form windows in your application.
You must define a menu for each form window.
Procedure:
1. Make specific changes to the application in the w_frame window. It is best to create a subclass of the w_frame window and then modify the subclass.
2. (optional) add instance variables, functions, and user-defined events to w_sheet.
3. Create a form window that inherits w_sheet.
4. Create a frame window menu. Generally, w_frame is used.
5. Specify the corresponding Framework Window menu for the Framework Window.
6. Create a menu for the form window
7. Specify the corresponding form menu for the sheet window.
8. Add the code for opening the Framework Window to the pfc_open event of n_cst_appmanager.
9. (optional) enable the Framework Window service when necessary.
L _ call the of_setstatusbar function of w_frame to enable the status bar service.
L _ call the of_setsheetmanager function of w_frame to enable the form management service.
Open the form window in the MDI application:
1. Write the script for opening the form window in the clicked event of the menu item. You need to pass the form window name to message. stringparm in the form of a string, and then call the of_sendmessage function with the pfc_open parameter:

N_cst_menu lnv_menu
Message. stringparm = "w_products"
Lnv_menu.of_sendmessage (this, "pfc_open ")
2. Access message. stringparm in the pfc_open event of w_frame to open the specified form window.
String ls_sheet
W_sheet lw_sheet
Ls_sheet = message. stringparm
Opensheet (lw_sheet, ls_sheet, this, 0, layered !)
Create an SDI application
In creating an SDI application using PFC, you will use the w_main window as the parent class of all your main window types. To make your events, functions, and instance variables valid in all windows, you only need to add them to w_main.

If your window requires a menu, you must define a menu for each window.
Procedure
1. inherit the w_main window and create a main window, which is the most main window. It is best to directly modify the w_main window.
2. Create a main menu.
3. create other menus and windows as needed.
4. Write a script to open the main window in the pfc_Open event of n_cst_appmanager.
Function usage during PFC Programming
Almost all PFC functions are object-level functions. This means that you must define the POWERBUILDER object before using the function. The PB-encapsulated function allows you to easily see which function belongs to which object.

PFC uses the Set/Get/Is naming rules to control instance variables.
The l _ of_Set function allows you to assign values to instance variables.
The l _ of_Get function allows you to obtain the value of a non-Boolean variable.
The l _ of_Is function allows you to determine the true and false values of a Boolean variable.
Access rules for other types of instance variables
When PFC defines variables, it is also specified as public, so you can directly access them at will.
In addition, some variables are only used internally, so they cannot be accessed through functions.
In addition to the Set/Get/Is naming rules, PFC uses the Regist er/UnRegister rule when defining entry parameters for a Service. For example, you can call the of_Register function of the u_calculator object to define the column of Datawindow using the drop-down calendar.

Object qualificationPFC uses access levels (public, private, protected
) To control your access to functions designed for internal automatic call of use.
When you call these functions from outside the object, use dot notatio
N to qualify the function name. Qualify the function name with the ref
Erence variable used to create the object (in some cases you qualify t
He function name with the actual object name ).
Call the PFC Object Function
1. Check whether the object has been created.
PowerBuilder creates a window, menu, and visual user object when the window is opened. You need to use the of_Setservicename function to create most invisible user objects. For example, the following u_dw object function creates a sort Service (n_cst_dwsrv_sort user object) and retains its reference in the instance variable inv_sort in u_dw's. These codes are usually used in the Datawindow construction event:

This. of_SetSort (True)
Automatically instantiate objects
Some PFC objects use the automatic instantiation function provided by Powerbuilder. These objects do not have the Set function. PowerBuilder will automatically instantiate them when they are declared.
2. Call appropriate object functions in the Application
This example shows that the Sorting Service uses the column name of DataWindow, the displayed value of sorting, and sorts the data after clicking. A drop-down dialog box is displayed on the menu bar.
This. inv_sort.of_SetColumnNameSource (this. inv_sort.HEADER) this. inv_s
Ort. of_SetUseDisplay (TRUE) this. inv_sort.of_SetColumnHeader (TRUE)
This. inv_sort.of_SetStyle (this. inv_sort.DRAGDROP)
Function overload PFC uses function overload to provide a rich and elastic programming interface. It implements function overloading in two ways.
L _ multiple syntaxes multiple functions have different parameter types and different parameter sequences. This allows the PFC function to process multiple data types.
L _ random number of parameters many functions have a parameter with the same data type, the same order, and the variable number of parameters. It also allows PFC to provide default values for common parameters.
Only used for internal processing of overloaded functions
In addition to public-type overload functions, PFC usually has a protection version, which is generally used for internal calls. For example, the of_Addline function in n_cst_dwsrv_report has four public-type versions and one protection-type version. This protection version is available for the other four calls. Although some versions of these protection types can be called, they are designed purely for internal calls.

.
Programming of PFC events
PFC includes pre-code events and user-defined events used to implement the PFC Service. There are also some empty events in which you can add specific code to your application or execute some specific tasks. All events are public and you can directly access them.

"Pre-code events" and other user-defined events
Pre-code events refer to events that have been numbered in the PFC layer object. PFC has many "pre-code events" with certain functions ". This means that if you enable a Service and the PFC object finds that the Service is enabled, these "pre-code events" will execute the code.
For example, the Clicked event of u_dw is a "pre-code event", which automatically calls the enabled Service functions. You can extend these events but cannot overwrite them.
Empty Custom Event
PFC defines many empty user-defined events. You can write specific code into your application. Many of these events are triggered by menus. Others are triggered by application code.
For example:
There is a user-defined event pfc_Retrieve in u_dw, where you can add code for data retrieval.
Return this. Retrieve ()
For more information about PFC events, see PFC Object Reference.
How does an event in PFC work?
PFC uses the following method to call events in Services:
1. When you trigger an event of an object, PFC will call the Custom Event of the corresponding Service and pass the corresponding parameters. For example, the clicked event of u_dw calls the pfc_Clicked event of n_cst_dwsrv_sort and transmits X coordinates, Y coordinates, and DW objects (these are actually parameters of DW Clicked events ).

2. These Services events may also call other object functions. For example, the n_cst_dwsrv_sort function is also called in the pfc_Clicked event of n_cst_dwsrv_sort.

Although you can directly call the object function of PFC, it is easier to call the corresponding events because these events include the error detection code.
Processing before event triggering
PFC has a custom event named Prename. This means that these events occur before the event name. We call it pre_event. You can add code to pre_event to expand the corresponding event processing capability. These pre_events include:

Pfc_PreAbout
Pfc_PreClose
Pfc_PreLogonDlg
Pfc_PreOpen
Pfc_PrePageSetupDlg
Pfc_PrePrintDlg
Pfc_PreRestoreRow
Pfc_PreSplash
Pfc_PreToolbar
Pfc_PreUpdate
Generally, all these events have a reference variable of the user object that has been automatically instantiated. The attributes of this object can affect the running of this event. You can modify the attributes of this user object to change the running effect of the event or extend the running effect of the event. Sometimes you need to modify some other objects.

For example, to control the Display Effect of an additional control in the About dialog box, you need:
1. Expand the user object n_cst_aboutattrib and add an instance variable (a user ID) that represents the Display Effect in w_about ).
2. Add the control (sle_userid) to w_about)
3. write code in the w_about open event and put the user ID value in the single row edit box (sle_userid)
Sle_userid.text = inv_aboutattrib.is_userid
4. Write the initialization code in the pfc_preabout event of n_cst_appmanager:
Inv_aboutattrib.is_userid = This. of_getuserid ()
Then, when you need to display w_about, call the of_about function of the Application Manager.
How to use Attribute objects
PFC provides many specialized attribute user objects. These user objects have the following features:
L _ contains public instance variables
L _ automatic instantiation
L _ name ends with attrib
L _ is usually used to transmit information to the pre_event of PFC, for example, pfc_preabout
L _ extensible, where you can define other instance variables.
Because you may extend these objects. Therefore, PFC uses objects instead of objects.
You can also define object functions to control these objects at will.
These property objects include:
Usage of attribute objects
N_cst_aboutattrib pfc_pre_about (n_cst_appmanager) Call the of_about function of n_cst_appmanager to open the about dialog box.

N_cst_calculatorattrib Constructor (u_calculator) automatically calls the n_cst_dirattrib File service object internally.

N_cst_dwobjectattrib Of_Describe (n_cst_dssrv and n_cst_dwsrv) functions Of_De scribe return the object attributes in DataWindow.

N_cst_dwproperyattrib DataWindow Properties objects automatically calls n_cst_errorattrib Error message service internally to pass the display content to the w_message window.

N_cst_filterattrib DataWindow filter service is used to transmit information to the filter dialog box.
N_cst_findattrib DataWindow find service transmits information to the Find dialog box
N_cst_itemattrib PFC ListBox, PictureListBox, and TreeView are automatically called internally.
N_cst_linkageattr B DataWindow linkage service is automatically called internally
N_cst_logonattrib Pfc_PreLogonDlg (n_cst_appman ger) Call the of_LogonDlg function of n_cst_appmanager to open the w_logon window.

N_cst_mruattrib MRU service is used for the pfc_MRUProcess and pfc_PreMRUSave events of the form.
N_cst_restoreroattrib DataWindow row manager service is automatically called internally.
N_cst_returnattrib DataWindow filter and sort services are automatically called internally.
N_cst_selectionattrib Selection service Populated with arguments to th
E n_cst_selection of_Open function
N_cst_sortattrib DataWindow sort service is used to transmit information to the Sort dialog box.
N_cst_splashattrib Pfc_PreSplash event (n_cst_appman ger) calls the of_Splash function of n_cst_ap pmanager to open w_splash.

N_cst_sqlattrib SQL service this attribute object contains part of the SQL statement.
N_cst_textstyleattrib PFC RichTextEdit control is used to set and obtain text attributes (italic, italic, etc ).
N_cst_toolbarattrib Pfc_PreToolbars event (w_frame) calls the pfc_Toolbars event of w_frame to open w_toolbars.

N_cst_zoomattrib DataWindow print preview service is automatically called internally
Constant of PFC
Many PFC objects contain constants. Use constants to make the program easier to read. For example, the following two sections of Code set the linkage style of Datawindow, but the second section is easier to understand:
// 1 = Filter linkage style.
Dw_emp.inv_linkage.of_SetStyle (1)
// Filter as a constant
Dw_emp.inv_linkage.of_setstyle (dw_emp.inv_linkage.filter)
Convention: All constants of PFC are capitalized.
Message routing
A message router can be used for communication between any object and a form. However, most of the time is used for message transmission between menus and forms. It provides a search algorithm to determine which object to receive messages.
When using message routing:
L _ the code in your menu only needs to know which event to substitute, and you do not need to know the current window or the object name associated with it.
L _ your window does not need to maintain user events. You only need to simply call the datawindow event. This reduces the number of events to be maintained in the window.
Message = user event
The message transmitted through message routing is actually the user event name. After receiving these messages, the window and control call corresponding events.
Built-in debug messages
The message routing mechanism also provides the built-in debug
Workflow of function of_sendmessage
When you select a menu item, the code in the clicked event calls the of_sendmessage function with the name of the user event to be triggered (in the form of a string. Of_sendmessage calls the of_sendmessage function of n_cst_menu. The of_sendmessage function of n_cst_menu calls the pfc_messagerou ter event of the form, the pfc_messagerouter event will call the user event you want to trigger (that is, passing string parameters in clicke D ).

In the MDI and SDI applications, the function of_sendmessage calls pfc_messagerouter.
Message routing is a bridge between menus and windows. You cannot trigger the pfc_MessageRouter event by clicking the button. Because message routing calls the GetFocus function to determine the current control. In this way, when you press the button, the button becomes the current control.

Transaction object in PFC
One of the powerful functions of PowerBuilder is its ability to quickly and conveniently access multiple databases. PowerBuild er uses the Transaction Object as a bridge between PowerBuilder and Database. SQLCA is a default transaction object.

User-Defined Object n_tr
The PFC has an n_tr object. It is a subclass of a standard transaction object. Instance variables, user-defined events, and functions are provided to expand the communication capability with the database.
N_tr provides a set of standard functions for database operations such as connection, disconnection, submission, and rollback. Use these functions to replace the original database statements. For example, use of_Connect to replace the CONNECT statement.
N_tr is used in two places
L _ sqlca substitution: In the Application Properties dialog box, set the default data type of SQLCA to n_tr.
L _ additional transaction object: When you need to access multiple databases, you can define another transaction object.
If you use multiple transaction objects, you can use the registration service of the transaction object to commit all opened transaction objects at a time and roll back all opened transaction objects at a time.
Set SQLCA to n_tr
1. Open the application paint brush
2. display the Properties window and select the Variable page.
3. Enter n_tr in the sqlca box
4. Click OK.
Use n_tr
1. If you do not use SQLCA, but use other transaction objects.
The following example assumes that itr_security is an instance variable of n_tr.
Itr_security = create n_tr
2. initialize the instance variable ib_autorollback. This variable is used to determine how to operate the transaction object when the transaction object is in the connection state and the application is closed or the transaction object is deleted.

Itr_security.of_setautorollback (false)
For extended initialization of ib_autorollback, You can initialize ib_autorollback in the n_tr constructor.
3. Use the of_init function of n_tr to initialize the attributes of the transaction object.
Integer li_return
String ls_inifile
Ls_inifile = gnv_app.of_getappinifile ()
If sqlca. of_init (ls_inifile, "Database") =-1 then
MessageBox ("Database", "error initializing from" + ls_inifile)
Halt close
End if
4. Call of_connect to connect to the database
If sqlca. of_connect () =-1 then
MessageBox ("Database", "unable to connect using" + ls_inifile)
Halt close
Else
Gnv_app.of_GetFrame (). SetMicroHelp ("Connection complete ")
End if
5. Call the member function of n_tr
Call the functions and events of the parent class
When expanding the functions and events of the parent class, you may need to call the functions or events of the parent class first, and then perform the following processing based on the returned values. This is especially meaningful for events with a return value prefix of PFC. Before executing the subclass code, you must first check whether the code of the parent class is successfully executed.

Override functions of the parent class
To extend the code of the parent class, obtain the return value of the parent class. You must overwrite the code of the parent class and then display the function or event that calls the parent class.
The following syntax format is used to call the parent class events, while passing parameters and obtaining return values:
Result = Super: Event eventname (arguments
Call the function of the parent class in the following syntax format, PASS Parameters, and obtain the return value:
Result = Super: Function functionname (arguments
The following example overwrites the pfc_Update event of u_dw. When the parent class event is processed successfully, the Child class records the information in the log.
Integer li_return
// Call ancestor event, passing
// Descendant's arguments.
Li_return = Super: Event pfc_Update (AB _accepttext, AB _resetflag)
IF li_return = 1 THEN
// Ue_WriteLog is a user-defined event.
Li_return = this. Event ue_WriteLog
END IF
Return li_return
Add online help in the Application
Online help is a very important part of applications. PFC provides many functions and events that allow you to conveniently add online help to your applications.
For more information, see "Deploying PFC dialog box HELP ".
1. Use the of_SetHelpFile function of n_cst_appmanager to set the Help file. Usually in the construction event:
This. of_SetHelpFile ("c: \ eis \ eisapp. hlp ")
2. pfc_PreOpen is the best place to set the help topic for the window.
Long ll_helpid
Ll_helpid = 1020 // 1020 is a help topic ID
Ia_helptypeid = ll_helpid
In this way, you can provide detailed help for the window selected by the user. You can set the ia_helptypeid to a growth INTEGER (in this case, PFC interprets it as the ID of the help topic) or a string (in this case, PFC interprets it as a keyword ).

3. (optional) if you do not use the m_master subclass of PFC. Then, call the pfc_Help event of the Form in your HELP menu. Because pfc_Help is defined in the w_master window, all PFC windows have events.

4. For the dialog box, write in the Clicked event of the HELP button:
Parent. Event pfc_Help ()
PFC automatically handles window-level help
When you select Help> Help from the menu of m_master subclass, the message routing mechanism automatically calls the pfc_help event of the current active window.
PFC upgrade
The upgraded version of PowerBuilder also includes the upgraded file of PFC. Follow the following rules to upgrade PFC:
When no layers (such as the PFC layer, PFE layer, and intermediate layer) of the l _ PFC are modified: You can directly install a new PBLs to overwrite the original PBLs.
Note: An original file backup is retained each time the PFC is upgraded.
L _ if you modify a layer in PFC: You must ensure that your modifications will not be overwritten! Follow these steps:
Upgrade PFC to the latest version.
1. Move the PBL files of all extension layers to a directory that will not be overwritten by the installation process.
Note: You should not modify the most basic class of PFC (Objects prefixed with PFC). Here, we assume that you have not modified the most basic class of PFC.
2. Determine the version number of your current PFC. You can view it in the readme.txt file or in the instance variable of pfc_n_cst_debug. Version Number Format: Major version number. Minor version number. revision number

3. Execute the installation program and place the PBL file of the PFC installation port to the directory where the PFC is located. it overwrites the original PBLS of the most basic PFC class, that is, the library file starting with PFC.
4. merge existing extension objects with newly installed extension objects. First, read in detail the list of new extension objects described in readme.txt. Then merge the objects according to the following two methods:
L _ COPY the new object to your extension PBLS.
L _ COPY existing objects to the new extension PBLS.
5. Start PowerBuilder
6. (optional) Adjust the library list of the application when necessary.
7. Open the library paint brush and re-compile all objects on one side.